Pisanie tematów pomocy dotyczących konfiguracji DSCWriting help for DSC configurations

Dotyczy: Windows PowerShell 5,0Applies To: Windows PowerShell 5.0

W konfiguracjach DSC można używać pomocy opartej na komentarzach.You can use comment-based help in DSC configurations. Użytkownicy mogą uzyskać dostęp do pomocy, wywołując konfigurację przy -?użyciu lub korzystając z polecenia cmdlet Get-Help .Users can access the help by calling the Configuration with -?, or by using the Get-Help cmdlet. Umieść pomoc opartą na komentarzach bezpośrednio nad Configuration słowem kluczowym.Place your Comment-based help directly above the Configuration keyword. Możesz umieścić pomoc parametrów w wierszu z blokiem komentarza bezpośrednio nad deklaracją parametru lub obie te metody jak w poniższym przykładzie.You can place parameter help in-line with your comment block, directly above the parameter declaration, or both as in the example below.

Aby uzyskać więcej informacji na temat pomocy opartej na komentarzach programu PowerShell, zobacz about_Comment_Based_Help.For more information about PowerShell comment-based help, see about_Comment_Based_Help.

Uwaga

Środowiska deweloperskie programu PowerShell, takie jak programu vscode i ISE, zawierają także fragmenty kodu umożliwiające automatyczne wstawianie szablonów bloku komentarzy.PowerShell development environments, like VSCode and the ISE, also have snippets to allow you to automatically insert comment block templates.

W poniższym przykładzie przedstawiono skrypt, który zawiera konfigurację i pomoc opartą na komentarzach.The following example shows a script that contains a configuration and comment-based help for it. Ten przykład pokazuje konfigurację z parametrami.This example shows a Configuration with parameters. Aby dowiedzieć się więcej o używaniu parametrów w konfiguracjach, zobacz Dodawanie parametrów do konfiguracji.To learn more about using parameters in your Configurations, see Add Parameters to your Configurations.

<#
.SYNOPSIS
A brief description of the function or script. This keyword can be used only once for each configuration.


.DESCRIPTION
A detailed description of the function or script. This keyword can be used only once for each configuration.


.PARAMETER ComputerName
The description of a parameter. Add a .PARAMETER keyword for each parameter in the function or script syntax.

Type the parameter name on the same line as the .PARAMETER keyword. Type the parameter description on the lines following the .PARAMETER keyword.
Windows PowerShell interprets all text between the .PARAMETER line and the next keyword or the end of the comment block as part of the parameter description.
The description can include paragraph breaks.

The Parameter keywords can appear in any order in the comment block, but the function or script syntax determines the order in which the parameters
(and their descriptions) appear in help topic. To change the order, change the syntax.

.EXAMPLE
HelpSample -ComputerName localhost

A sample command that uses the function or script, optionally followed by sample output and a description. Repeat this keyword for each example.
PowerShell automatically prefaces the first line with a PowerShell prompt. Additional lines are treated as output and description. The example can contain spaces, newlines and PowerShell code.

If you have multiple examples, there is no need to number them. PowerShell will number the examples in help text.
.EXAMPLE
HelpSample -FilePath "C:\output.txt"

This example will be labeled "EXAMPLE 2" when help is displayed to the user.
#>
configuration HelpSample1
{
    param
    (
        [string]$ComputerName = 'localhost',
        # Provide a PARAMETER section for each parameter that your script or function accepts.
        [string]$FilePath = 'C:\Destination.txt'
    )

    Node $ComputerName
    {
        File HelloWorld
        {
            Contents="Hello World"
            DestinationPath = $FilePath
        }
    }
}

Wyświetlanie pomocy dotyczącej konfiguracjiViewing configuration help

Aby wyświetlić pomoc dotyczącą konfiguracji, użyj Get-Help polecenia cmdlet z nazwą funkcji lub wpisz nazwę funkcji, a następnie pozycję. -?To view the help for a configuration, use the Get-Help cmdlet with the name of the function, or type the name of the function followed by -?. Poniżej przedstawiono dane wyjściowe poprzedniej konfiguracji przekazywanej do Get-Help.The following is the output of the previous Configuration passed to Get-Help.

Get-Help HelpSample1 -Detailed
NAME
    HelpSample1

SYNOPSIS
    A brief description of the function or script. This keyword can be used only once for each configuration.


SYNTAX
    HelpSample1 [[-InstanceName] <String>] [[-DependsOn] <String[]>] [[-PsDscRunAsCredential] <PSCredential>] [[-OutputPath] <String>] [[-ConfigurationData] <Hashtable>] [[-ComputerName] <String>] [[-FilePath] <String>] [<CommonParameters>]


DESCRIPTION
    A detailed description of the function or script. This keyword can be used only once for each configuration.


PARAMETERS
    -InstanceName <String>

    -DependsOn <String[]>

    -PsDscRunAsCredential <PSCredential>

    -OutputPath <String>

    -ConfigurationData <Hashtable>

    -ComputerName <String>
        The description of a parameter. Add a .PARAMETER keyword for each parameter in the function or script syntax.

        Type the parameter name on the same line as the .PARAMETER keyword. Type the parameter description on the lines following the .PARAMETER keyword.
        Windows PowerShell interprets all text between the .PARAMETER line and the next keyword or the end of the comment block as part of the parameter description.
        The description can include paragraph breaks.

        The Parameter keywords can appear in any order in the comment block, but the function or script syntax determines the order in which the parameters
        (and their descriptions) appear in help topic. To change the order, change the syntax.

    -FilePath <String>
        Provide a PARAMETER section for each parameter that your script or function accepts.

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).

    -------------------------- EXAMPLE 1 --------------------------

    PS C:\>HelpSample -ComputerName localhost

    A sample command that uses the function or script, optionally followed by sample output and a description. Repeat this keyword for each example.
    PowerShell automatically prefaces the first line with a PowerShell prompt. Additional lines are treated as output and description. The example can contain spaces, newlines and PowerShell code.

    If you have multiple examples, there is no need to number them. PowerShell will number the examples in help text.




    -------------------------- EXAMPLE 2 --------------------------

    PS C:\>HelpSample -FilePath "C:\output.txt"

    This example will be labeled "EXAMPLE 2" when help is displayed to the user.




REMARKS
    To see the examples, type: "get-help HelpSample1 -examples".
    For more information, type: "get-help HelpSample1 -detailed".
    For technical information, type: "get-help HelpSample1 -full".

Uwaga

Pola składni i atrybuty parametrów są generowane automatycznie przez program PowerShell.Syntax fields and parameter attributes are automatically generated for you by PowerShell.

Zobacz teżSee Also