Skip to content

Instantly share code, notes, and snippets.

@jdhitsolutions
Last active November 13, 2020 18:07
Show Gist options
  • Star 2 You must be signed in to star a gist
  • Fork 3 You must be signed in to fork a gist
  • Save jdhitsolutions/ebb32a812dd4762f44f012bbb9b3f0e5 to your computer and use it in GitHub Desktop.
Save jdhitsolutions/ebb32a812dd4762f44f012bbb9b3f0e5 to your computer and use it in GitHub Desktop.
My PowerShell function template for getting information from remote computers. The file also contains a json entry for a PowerShell snippet in VSCode.
Function Get-Something {
<#
.SYNOPSIS
Get something
.DESCRIPTION
Describe what this does.
Many of the parameters are the same as in Invoke-Command.
.PARAMETER Computername
Specifies the computers on which the command runs. The default is the local computer.
When you use the ComputerName parameter, Windows PowerShell creates a temporary connection that is used only to run the specified command and is then closed. If you need a persistent connection, use the Session parameter.
Type the NETBIOS name, IP address, or fully qualified domain name of one or more computers in a comma-separated list. To specify the local computer, type the computer name, localhost, or a dot (.).
To use an IP address in the value of ComputerName , the command must include the Credential parameter. Also, the computer must be configured for HTTPS transport or the IP address of the remote computer must be included in the WinRM TrustedHosts list on the local computer. For instructions for adding a computer name to the TrustedHosts list, see "How to Add a Computer to the Trusted Host List" in about_Remote_Troubleshooting.
On Windows Vista and later versions of the Windows operating system, to include the local computer in the value of ComputerName , you must open Windows PowerShell by using the Run as administrator option.
.PARAMETER Credential
Specifies a user account that has permission to perform this action. The default is the current user.
Type a user name, such as User01 or Domain01\User01. Or, enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, this cmdlet prompts you for a password.
.PARAMETER UseSSL
Indicates that this cmdlet uses the Secure Sockets Layer (SSL) protocol to establish a connection to the remote computer. By default, SSL is not used.
WS-Management encrypts all Windows PowerShell content transmitted over the network. The UseSSL parameter is an additional protection that sends the data across an HTTPS, instead of HTTP.
If you use this parameter, but SSL is not available on the port that is used for the command, the command fails.
.PARAMETER ThrottleLimit
Specifies the maximum number of concurrent connections that can be established to run this command. If you omit this parameter or enter a value of 0, the default value, 32, is used.
The throttle limit applies only to the current command, not to the session or to the computer.
.PARAMETER Authentication
Specifies the mechanism that is used to authenticate the user's credentials. The acceptable values for this
parameter are:
- Default
- Basic
- Credssp
- Digest
- Kerberos
- Negotiate
- NegotiateWithImplicitCredential
The default value is Default.
CredSSP authentication is available only in Windows Vista, Windows Server 2008, and later versions of the Windows operating system.
For information about the values of this parameter, see the description of the AuthenticationMechanismEnumeration (http://go.microsoft.com/fwlink/?LinkID=144382) in theMicrosoft Developer Network (MSDN) library.
CAUTION: Credential Security Support Provider (CredSSP) authentication, in which the user's credentials are passed to a remote computer to be authenticated, is designed for commands that require authentication on more than one resource, such as accessing a remote network share. This mechanism increases the security risk of the remote operation. If the remote computer is compromised, the credentials that are passed to it can be used to control the
network session.
.EXAMPLE
PS C:\> Get-Something
.INPUTS
System.String
.OUTPUTS
Custom object
.NOTES
Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/
.LINK
Invoke-Command
#>
[cmdletbinding()]
[OutputType("custom object")]
[alias('wver')]
Param (
[Parameter(ValueFromPipeline, ValueFromPipelineByPropertyName,Position = 0)]
[ValidateNotNullOrEmpty()]
[string[]]$Computername = $env:COMPUTERNAME,
[PSCredential]$Credential,
[switch]$UseSSL,
[Int32]$ThrottleLimit,
[ValidateSet('Default', 'Basic', 'Credssp', 'Digest', 'Kerberos', 'Negotiate', 'NegotiateWithImplicitCredential')]
[ValidateNotNullorEmpty()]
[string]$Authentication = "default"
)
Begin {
Write-Verbose "Starting $($MyInvocation.Mycommand)"
$sb = {
#add your code
#you can pass local variables with $using or define scriptblock parameters and pass arguments
} #close scriptblock
#update PSBoundParameters so it can be splatted to Invoke-Command
$PSBoundParameters.Add("ScriptBlock", $sb) | Out-Null
$PSBoundParameters.Add("HideComputername", $True) | Out-Null
} #begin
Process {
if (-Not $PSBoundParameters.ContainsKey("Computername")) {
#add the default value if nothing was specified
$PSBoundParameters.Add("Computername", $Computername) | Out-Null
}
$PSBoundParameters | Out-String | Write-Verbose
Invoke-Command @PSBoundParameters | Select-Object -Property * -ExcludeProperty RunspaceID, PS*
} #process
End {
Write-Verbose "Ending $($MyInvocation.Mycommand)"
} #end
} #close function
<#
json powershell snippet for VSCode
"get-something": {
"prefix": "get-something",
"body": [
"\r",
"Function Get-Something {\r",
"<#\r",
".SYNOPSIS\r",
"Get ...\r",
".DESCRIPTION\r",
"Describe what this does.\r",
"\r",
"Many of the parameters are the same as in Invoke-Command.\r",
".PARAMETER Computername\r",
"Specifies the computers on which the command runs. The default is the local computer.\r",
"\r",
"When you use the ComputerName parameter, Windows PowerShell creates a temporary connection that is used only to run the specified command and is then closed. If you need a persistent connection, use the Session parameter.\r",
"\r",
"Type the NETBIOS name, IP address, or fully qualified domain name of one or more computers in a comma-separated list. To specify the local computer, type the computer name, localhost, or a dot (.).\r",
"\r",
"To use an IP address in the value of ComputerName , the command must include the Credential parameter. Also, the computer must be configured for HTTPS transport or the IP address of the remote computer must be included in the WinRM TrustedHosts list on the local computer. For instructions for adding a computer name to the TrustedHosts list, see \"How to Add a Computer to the Trusted Host List\" in about_Remote_Troubleshooting.\r",
"\r",
"On Windows Vista and later versions of the Windows operating system, to include the local computer in the value of ComputerName , you must open Windows PowerShell by using the Run as administrator option.\r",
".PARAMETER Credential\r",
"Specifies a user account that has permission to perform this action. The default is the current user.\r",
"\r",
"Type a user name, such as User01 or Domain01\\User01. Or, enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, this cmdlet prompts you for a password.\r",
".PARAMETER UseSSL\r",
"Indicates that this cmdlet uses the Secure Sockets Layer (SSL) protocol to establish a connection to the remote computer. By default, SSL is not used.\r",
"\r",
"WS-Management encrypts all Windows PowerShell content transmitted over the network. The UseSSL parameter is an additional protection that sends the data across an HTTPS, instead of HTTP.\r",
"\r",
"If you use this parameter, but SSL is not available on the port that is used for the command, the command fails.\r",
".PARAMETER ThrottleLimit\r",
"Specifies the maximum number of concurrent connections that can be established to run this command. If you omit this parameter or enter a value of 0, the default value, 32, is used.\r",
"\r",
"The throttle limit applies only to the current command, not to the session or to the computer.\r",
".PARAMETER Authentication\r",
"Specifies the mechanism that is used to authenticate the user's credentials. The acceptable values for this\r",
"parameter are:\r",
"\r",
"- Default\r",
"- Basic\r",
"- Credssp\r",
"- Digest\r",
"- Kerberos\r",
"- Negotiate\r",
"- NegotiateWithImplicitCredential\r",
"\r",
"The default value is Default.\r",
"\r",
"CredSSP authentication is available only in Windows Vista, Windows Server 2008, and later versions of the Windows operating system.\r",
"\r",
"For information about the values of this parameter, see the description of the AuthenticationMechanismEnumeration (http://go.microsoft.com/fwlink/?LinkID=144382) in theMicrosoft Developer Network (MSDN) library.\r",
"\r",
"CAUTION: Credential Security Support Provider (CredSSP) authentication, in which the user's credentials are passed to a remote computer to be authenticated, is designed for commands that require authentication on more than one resource, such as accessing a remote network share. This mechanism increases the security risk of the remote operation. If the remote computer is compromised, the credentials that are passed to it can be used to control the\r",
"network session.\r",
".EXAMPLE\r",
"PS C:\\> Get-Something\r",
"\r",
".INPUTS\r",
"System.String\r",
".OUTPUTS\r",
"Custom object\r",
".NOTES\r",
"Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/\r",
".LINK\r",
"Invoke-Command\r",
"#>\r",
"\r",
" [cmdletbinding()]\r",
" [OutputType(\"custom object\")]\r",
" [alias('wver')]\r",
"\r",
" Param (\r",
" [Parameter(ValueFromPipeline, Position = 0)]\r",
" [ValidateNotNullOrEmpty()]\r",
" [string[]]$$Computername = $$env:COMPUTERNAME,\r",
" [PSCredential]$$Credential,\r",
" [switch]$$UseSSL,\r",
" [Int32]$$ThrottleLimit,\r",
" [ValidateSet('Default', 'Basic', 'Credssp', 'Digest', 'Kerberos', 'Negotiate', 'NegotiateWithImplicitCredential')]\r",
" [ValidateNotNullorEmpty()]\r",
" [string]$$Authentication = \"default\"\r",
" )\r",
"\r",
" Begin {\r",
"\r",
" Write-Verbose \"Starting $($$MyInvocation.Mycommand)\"\r",
"\r",
" $$sb = {\r",
"\r",
" #add your code\r",
" #you can pass local variables with $using or define scriptblock parameters and pass arguments\r",
"\r",
" } #close scriptblock\r",
"\r",
" #update PSBoundParameters so it can be splatted to Invoke-Command\r",
" $$PSBoundParameters.Add(\"ScriptBlock\", $$sb) | Out-Null\r",
" $$PSBoundParameters.Add(\"HideComputername\", $$True) | Out-Null\r",
" } #begin\r",
"\r",
" Process {\r",
" if (-Not $$PSBoundParameters.ContainsKey(\"Computername\")) {\r",
" #add the default value if nothing was specified\r",
" $$PSBoundParameters.Add(\"Computername\", $$Computername) | Out-Null\r",
" }\r",
" $$PSBoundParameters | Out-String | Write-Verbose\r",
" Invoke-Command @PSBoundParameters | Select-Object -Property * -ExcludeProperty RunspaceID, PS*\r",
" } #process\r",
"\r",
" End {\r",
"\r",
" Write-Verbose \"Ending $($$MyInvocation.Mycommand)\"\r",
"\r",
" } #end\r",
"} #close function\r",
""
],
"description": "template for my Get-Something technique"
}
#>
@jdhitsolutions
Copy link
Author

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment