- Enterprise PowerShell Scripting Bootcamp
- Brenton J.W. Blawat
- 167字
- 2021-07-09 21:03:04
Comment blocks
The first recommendation is to create comment blocks for detailed tracking information about the PowerShell script itself. Comment blocks can track information about the script's creation, authors, changes, and other useful information that will enable you to quickly determine what the script is doing. PowerShell has built-in comment block support which integrates with the get-help cmdlet.
The required components include the following:
- Comment block location: The comment block must be the first item defined at the top of your script. If you use parameter blocks, you specify the parameter blocks after the comment block.
- Start comment block: In order to integrate with the help system, you need to specify the starting of the comment block. To start a comment block, you type
<#. .SYNOPSIS: To create a synopsis for the script, type.SYNOPSISon a line, and then on a subsequent line type a one-line description of why the script is being created..DESCRIPTION: To create a full description for the script, type.DESCRIPTIONon a line, and then on a subsequent line type a description of the script's functions so that any editor of the script will know the script's basic function. If it is a complicated script or a script that invokes other scripts, describe the overall process for it. You may also want to include author information that contains the author's name, author's position, author's company, contact information, initial release number, and date of the initial release..PARAMETER: To provide parameter information that can be used while running the script, you can type.PARAMETER, and specify the parameter name. On a subsequent line, type a description of that parameter. If you have multiple parameters, you can define multiple.PARAMETERstatements referencing parameter names..EXAMPLE: To provide an example of usage for your script, you can type.EXAMPLEand provide an example on how to run the script from a command line. If you have multiple examples, you can define multiple.EXAMPLEstatements..NOTES: To provide notes for execution caveats, you can type.NOTES, and on a subsequent line type a usage note to execute the script..LINK: If you have other help topics you want to link to, you can type.LINK, and on a subsequent line provide a URL to another help topic.Ending comment block: In order to integrate with the help system, you need to specify the ending of the comment block. To end a comment block, you type#>.
The following screenshot displays a proper comment block that will integrate with the help system:
This properly shows the syntax of a comment block that is usable via the PowerShell help system. You start by first defining the commend block with <#. You then create a .SYNOPSIS section with a synopsis of the script. Then you create a .DESCRIPTION section and provide a detailed description of the script. You also provide details regarding the author, revision, and editing revisions to the script. Following that section, you define a .PARAMETER PATH section, which provides detailed information about the .PARAMETER PATH in the script. Next, you create an .EXAMPLE section, to provide an example for usage, and you create a .NOTES section to provide information about the required execution environment. You then close the comment block by issuing #>.