PowerShell Language

From DataSelf Knowledge Base
Jump to navigation Jump to search

Comment-based help

The Powershell shell knows to look for specially formatted comments inside of a script or function, and it parses those comments to construct the same type of help display you’d see with a native cmdlet.

  • The help data can be used inside a function body or in a script.
  • In order for the help comments to be parsed, they must be the FIRST comments in the function or script.
  • Comment-based help for a function can appear in one of three locations:
  1. -- At the beginning of the function body.
  2. -- At the end of the function body.
  3. -- Before the Function keyword. There cannot be more than one blank line between the last line of the function help and the Function keyword.

Example

 function foo
 {
 <#  
 .SYNOPSIS  
    Counts the Grateful Dead shows in my archives
 .OUTPUTS
    System.String. Add-Extension returns a string with the extension or file name.
 ...
 #>
 ...
 Return "somestring"
  } 

Main Key Words

  • .SYNOPSIS –a brief explanation of what the script or function does.
  • .DESCRIPTION – a more detailed explanation of what the script or function does.
  • .PARAMETER name – an explanation of a specific parameter. Replace name with the parameter name. You can have one of these sections for each parameter the script or function uses.
    • Type the parameter name on the same line as the .PARAMETER keyword.
      • Type the parameter description on the lines following the .PARAMETER keyword.
  • .EXAMPLE – an example of how to use the script or function. You can have multiple .EXAMPLE sections if you want to provide more than one example.
  • .NOTES – any miscellaneous notes on using the script or function.
  • .LINK – a cross-reference to another help topic; you can have more than one of these. If you include a URL beginning with http:// or https://, the shell will open that URL when the Help command’s –online parameter is used.
  • .RETURNVALUE
  • .INPUTS - The Microsoft .NET Framework types of objects that can be piped to the function or script. You can also include a description of the input objects.
  • .OUTPUTS - The .NET Framework type of the objects that the cmdlet returns. You can also include a description of the returned objects.
  • .FUNCTIONALITY - The intended use of the function. This content appears when the Get-Help command includes the Functionality parameter of Get-Help.


Strings