Creating comment-based help_Mastering PowerCLI-QQ阅读女频青春网

书名：Mastering PowerCLI
作者名：Sajal Debnath
本章字数：1260字
更新时间：2025-02-27 06:01:49

Creating comment-based help

Comment-based help is the easiest way to create help for the scripts that you write. If you write comment-based help in your function, then the Get-Help cmdlet will show you help for the function in the same way as it shows the help for any other PowerShell native cmdlet. So, whenever you are writing an advanced function, you should include comment-based help so that end users can utilize the help of the Get-help cmdlet to work with the function.

Before we go ahead and dive into comment-based help, I would like to draw your attention to the following fact.

You have just seen the preceding function where I created a dynamic variable to accept the user id, vmName, and environment where I can create VMs. Note that, in this function, I did not write any help, so what happens if I try to run Get-Help on this function? Let's see.

Wow! It gives a short description. Let's try the –Full version.

Pretty amazing right? It provides help in the same format as it provides for other cmdlets without us doing anything. So, how do we fill up those empty areas and write our own help portions? Let's start doing this.

Comment-based help can be used in the following three situations:

Functions
Scripts
Script modules

The syntax of comment-based help is as follows:

        # .< help keyword>
        # <help content>

OR:

<#
            .< help keyword>
< help content>
        #>

There are several rules for writing comment-based help. We will cover a few of them in this section. The rest will be covered in their respective sections:

Rule 1: You can write the entire help portion with successive comment lines with # or you can simply create a comment block with <# and #>.
Rule 2: All the lines in a comment-based help topic must be contagious. If a help topic follows a normal comment, which is not part of the topic, then there must be at least one blank line between the last nonhelp comment line and the beginning of a comment-based help line.
Rule 3: Keywords define each section of comment-based help. Each keyword must start with a dot (.).
Rule 4: Keywords can appear in any order and the keyword names are not case sensitive.
Rule 5. The most important fact is that, if one of the keywords is misspelled, then the entire block may be ignored. So, take special care to properly spell each keyword.
Rule 6: The comment block must contain at least one keyword. The help content begins one line after the keyword line and may span multiple lines.

In functions:

Comment-based help for a function can be inserted in any one of three locations:

At the beginning of the function body:

function Get-Function
        {
<#
            .< help keyword>
< help content>
            #>

<function commands>
        }

At the end of the function body:

function Get-Function
        {
<function commands>

<#
            .< help keyword>
< help content>
            #>
        }

Just before the function keyword. Note that there cannot be more than one blank line between the last line of the function help and the function declaration:
```
<#
        .< help keyword>
< help content>
        #>
        function Get-Function { }
```

In scripts:

The following rules apply for the location of comment-based help in scripts:

The comment-based help portion can be kept at the beginning of the script file. The help portion can be preceded either by comment lines or blank lines:
```
<#
        .< help keyword>
< help content>
        #>

        function Get-Function { }
```
If the first item in the script body after the help declaration is a function, then there must be at least two blank lines between the end of the script help and the beginning of the function declaration. Otherwise, the help will be considered to be the help for the function and not for the script.
The help script block can be put at the end of the script file. But if the script is signed, then we need to put the help block at the beginning of the script file, as the end is reserved for the signature block:
```
        function Get-Function { }

<#
        .< help keyword>
< help content>
        #>
```

In script modules:

In script modules, we need to put comment-based help as per the syntax for functions. We cannot use comment-based help here, as we do in case of scripts, to define help for all the functions defined in the module. So, in case of modules, if we are using comment-based help, then we need to either define help for each of the functions, or if we are using external help files (XML-based help files), then we need to define them for each of the functions:

    # .ExternalHelp <XML-file-name>
    function <function-name>
    {
        ...
    }

Tip

Here, we used an XML-based help file as a help file so that it can be updated. Also, note the position of the .ExternalHelp keyword declaration location.

Next, let's take a closer look at some of the most used keywords in comment-based help:

.SYNOPSIS: This section provides a short description of the function or script. This keyword can be used only once in each topic.
.DESCRIPTION: This section provides a detailed description of the function or script. This keyword can also be used only once in each topic.
.PARAMETER <Parameter Name>: In this section, we provide a description of each parameter defined in the function. We need to use the .PARAMETER keyword for each parameter defined in the function/script and provide details of the parameter. Note that the parameter name must be on the same line as the .PARAMETER keyword.
.EXAMPLE: We can use this keyword to define an example for the script. We can give a sample command that will use the function/script with option output details. We can give as many examples as we want. Typically, it should cover most of the use cases for the script.
.INPUTS: Using this keyword, we can show what type of objects can be piped into the function/script with an optional description of the object.
.OUTPUTS: Similar to the .INPUTS keyword, we can use this keyword to define the type of the outputs.
.NOTES: The portion succeeding this keyword provides additional information of the function or script.
.EXTERNALHELP <XML Help File>: This keyword specifies the XML-based help file for the script or function. This XML-based help file takes precedence over the comment-based help. If this keyword is present, then the comment based help is ignored.

Tip

There are other keywords as well. For a detailed list and discussion, visit https://technet.microsoft.com/en-us/library/hh847834.aspx.

Now, let's take a look at an example. In the previous section, we created an advanced function (Create-VM) with dynamic parameters. Let's write a help topic for it. Since this is a single function, we will follow the procedure for writing a comment-based help for functions:

Sample Help:

<#
.SYNOPSIS
    Creates a VM in particular environment based on the inputs provided by the user.
.DESCRIPTION
    Create-VM is a function that can create a VM in any of the three given environment namely "Dedicated", "Shared" and "Cloud". The user chooses where he wants to create the VM. If the user wants to create a VM in the Dedicated environment then he needs to have special administrative permission to create the VM in that environment. The function throws an error if the user provided value does not match the environment permissible values. Also for a user to create a vm in Dedicated environment needs to have "admin" in his user id. Unless his/her userid does not contain "admin" as a keyword he/she will be denied the permission to create a VM there.
.PARAMETER vmName
    The name of the VM which needs to be created. This is a simple string variable.
.PARAMETER environment
    A normal string parameter which identifies which environment should be chosen for the VM creation. The value of this variable can be from "Dedicated", "Shared" and "Cloud" only.
.PARAMETER userName
    This is a dynamic parameter defined within the script. This parameter comes into effect to store the user name when the end user choses "Dedicated" as their destination environment for VM creation.
.EXAMPLE
     Create-VM -vmName 'test-vm' -environment Shared
     Output:
     You have entered VMname : test-vm Environment: Shared

.EXAMPLE
     Create-VM -vmName 'test-vm' -environment Cloud
     Output:
     You have entered VMname : test-vm Environment: Cloud

.EXAMPLE
     Create-VM -vmName 'test-vm' -environment Dedicated -userName sysadmin
     Output:
     You have entered VMname : test-vm Environment: Dedicated UserID:sysadmin

.INPUTS
    None. This function can not take input from pipeline

.OUTPUTS
    System.Object

.NOTES
    Author:  Sajal Debnath
#>

Now, we can get the full help using the Get-Help cmdlet.

Also, note that using the –ShowWindow switch will display the help in a separate window. An example of such a help is shown in the following example. Since I used the ShowWindow parameter, the output is given in another window:

PS C:\PowerShell Files> Get-Help Create-VM -ShowWindow

Since the output could not be given in a single screen, the following is the rest of the output:

Note that the help file in the preceding screenshot shows the information I provided as the $Errorlog and $LogFile parameters. The function that generated the preceding help file is shown in the following screenshot. The $Errorlog and $LogFile parameters were switched in order to turn on logging and had normal comments, shown in the help file.

You can now go ahead and use other keywords in the help topic to make it more informative. Remember that the more information you provide, the easier it becomes for the end users to work with the function or script that you write.