about_Comment_Based_Help

Artigo
10/04/2023

Descrição breve

Descreve como escrever tópicos de ajuda baseados em comentários para funções e scripts.

Descrição longa

Você pode escrever tópicos de ajuda baseados em comentários para funções e scripts usando palavras-chave de comentário de ajuda especiais.

O cmdlet Get-Help exibe a ajuda baseada em comentários no mesmo formato em que exibe os tópicos de ajuda do cmdlet gerados a partir de arquivos XML. Os usuários podem usar todos os parâmetros do Get-Help, como Detalhado, Completo, Exemplos e Online, para exibir o conteúdo da ajuda baseada em comentários.

Você também pode escrever arquivos de ajuda baseados em XML para funções e scripts. Para habilitar o Get-Help cmdlet para localizar o arquivo de ajuda baseado em XML para uma função ou script, use a .ExternalHelp palavra-chave. Sem essa palavra-chave, Get-Help não é possível localizar tópicos de ajuda baseados em XML para funções ou scripts.

Este tópico explica como escrever tópicos de ajuda para funções e scripts. Para obter informações sobre como exibir tópicos de ajuda para funções e scripts, consulte Get-Help.

Os cmdlets Update-Help e Save-Help funcionam somente em arquivos XML. A Ajuda atualizável não oferece suporte a tópicos de ajuda baseados em comentários.

Sintaxe para ajuda baseada em comentários

A sintaxe da ajuda baseada em comentários é a seguinte:

# .<help keyword>
# <help content>

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

A ajuda baseada em comentários é escrita como uma série de comentários. Você pode digitar um símbolo # de comentário antes de cada linha de comentários ou pode usar os <# símbolos e #> para criar um bloco de comentários. Todas as linhas dentro do bloco de comentários são interpretadas como comentários.

Todas as linhas em um tópico de ajuda baseado em comentários devem ser contíguas. Se um tópico de ajuda baseado em comentário seguir um comentário que não faz parte do tópico de ajuda, deve haver pelo menos uma linha em branco entre a última linha de comentário não ajuda e o início da ajuda baseada em comentário.

As palavras-chave definem cada seção da ajuda baseada em comentários. Cada palavra-chave de ajuda baseada em comentários é precedida por um ponto .. As palavras-chave podem aparecer em qualquer ordem. Os nomes de palavras-chave não diferenciam maiúsculas de minúsculas.

Por exemplo, a .Description palavra-chave precede uma descrição de uma função ou script.

<#
.Description
Get-Function displays the name and syntax of all functions in the session.
#>

O bloco de comentários deve conter pelo menos uma palavra-chave. Algumas das palavras-chave, como .EXAMPLE, podem aparecer muitas vezes no mesmo bloco de comentários. O conteúdo de ajuda para cada palavra-chave começa na linha após a palavra-chave e pode abranger várias linhas.

Sintaxe para ajuda baseada em comentários em funções

A ajuda baseada em comentários para uma função pode aparecer em um dos três locais:

No início do corpo da função.
No final do corpo da função.
Antes da function palavra-chave. Não pode haver mais de uma linha em branco entre a última linha da função help e a function palavra-chave.

Por exemplo:

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

  # function logic
}

function Get-Function
{
   # function logic

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

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

Sintaxe para ajuda baseada em comentários em scripts

A ajuda baseada em comentários para um script pode aparecer em um dos dois locais a seguir no script.

No início do arquivo de script. A ajuda do script pode ser precedida no script apenas por comentários e linhas em branco.

Se o primeiro item no corpo do script (após a ajuda) for uma declaração de função, deverá haver pelo menos duas linhas em branco entre o final da ajuda do script e a declaração de função. Caso contrário, a ajuda é interpretada como sendo ajuda para a função, não ajuda para o script.
No final do arquivo de script. No entanto, se o script estiver assinado, coloque a ajuda baseada em comentários no início do arquivo de script. O final do script é ocupado pelo bloco de assinatura.

Por exemplo:

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


function Get-Function { }

function Get-Function { }

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

Sintaxe para ajuda baseada em comentários em módulos de script

Em um módulo .psm1de script, a ajuda baseada em comentários usa a sintaxe para funções, não a sintaxe para scripts. Não é possível usar a sintaxe de script para fornecer ajuda para todas as funções definidas em um módulo de script.

Por exemplo, se você estiver usando a .ExternalHelp palavra-chave para identificar os arquivos de ajuda baseados em XML para as funções em um módulo de script, deverá adicionar um .ExternalHelp comentário a cada função.

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

Palavras-chave de ajuda baseadas em comentários

A seguir estão palavras-chave de ajuda válidas baseadas em comentários. Eles são listados na ordem em que normalmente aparecem em um tópico de ajuda junto com seu uso pretendido. Essas palavras-chave podem aparecer em qualquer ordem na ajuda baseada em comentários e não diferenciam maiúsculas de minúsculas.

.SYNOPSIS

Uma breve descrição da função ou script. Essa palavra-chave pode ser usada apenas uma vez em cada tópico.

.DESCRIPTION

Uma descrição detalhada da função ou script. Essa palavra-chave pode ser usada apenas uma vez em cada tópico.

.PARAMETER

A descrição de um parâmetro. Adicione uma .PARAMETER palavra-chave para cada parâmetro na sintaxe da função ou do script.

Digite o nome do parâmetro na mesma linha que a .PARAMETER palavra-chave. Digite a descrição do parâmetro nas linhas após a .PARAMETER palavra-chave. O Windows PowerShell interpreta todo o texto entre a linha e a .PARAMETER próxima palavra-chave ou o final do bloco de comentários como parte da descrição do parâmetro. A descrição pode incluir quebras de parágrafo.

.PARAMETER  <Parameter-Name>

As palavras-chave Parameter podem aparecer em qualquer ordem no bloco de comentários, mas a sintaxe de função ou script determina a ordem em que os parâmetros (e suas descrições) aparecem no tópico de ajuda. Para alterar a ordem, altere a sintaxe.

Você também pode especificar uma descrição de parâmetro colocando um comentário na sintaxe da função ou do script imediatamente antes do nome da variável de parâmetro. Para que isso funcione, você também deve ter um bloco de comentários com pelo menos uma palavra-chave.

Se você usar um comentário de sintaxe e uma .PARAMETER palavra-chave, a descrição associada à .PARAMETER palavra-chave será usada e o comentário de sintaxe será ignorado.

<#
.SYNOPSIS
    Short description here
#>
function Verb-Noun {
    [CmdletBinding()]
    param (
        # This is the same as .Parameter
        [string]$Computername
    )
    # Verb the Noun on the computer
}

.EXAMPLE

Um comando de exemplo que usa a função ou script, opcionalmente seguido por saída de exemplo e uma descrição. Repita essa palavra-chave para cada exemplo.

.INPUTS

Os tipos .NET de objetos que podem ser canalizados para a função ou script. Você também pode incluir uma descrição dos objetos de entrada.

.OUTPUTS

O tipo .NET dos objetos que o cmdlet retorna. Você também pode incluir uma descrição dos objetos retornados.

.NOTES

Informações adicionais sobre a função ou script.

.LINK

O nome de um tópico relacionado. O valor aparece na linha abaixo da palavra-chave ".LINK" e deve ser precedido por um símbolo # de comentário ou incluído no bloco de comentários.

Repita a .LINK palavra-chave para cada tópico relacionado.

Esse conteúdo aparece na seção Links Relacionados do tópico de ajuda.

O .Link conteúdo da palavra-chave também pode incluir um URI (Uniform Resource Identifier) para uma versão online do mesmo tópico de ajuda. A versão online é aberta quando você usa o parâmetro Online de Get-Help. O URI deve começar com "http" ou "https".

.COMPONENT

O nome da tecnologia ou recurso que a função ou script usa ou ao qual está relacionado. O parâmetro Component de usa esse valor para filtrar os resultados da pesquisa retornados Get-Help pelo Get-Help.

.ROLE

O nome da função de usuário para o tópico de ajuda. O parâmetro Role de usa esse valor para filtrar os resultados da pesquisa retornados Get-Help pelo Get-Help.

.FUNCTIONALITY

As palavras-chave que descrevem o uso pretendido da função. O parâmetro Functionality de usa esse valor para filtrar os resultados da pesquisa retornados Get-Help pelo Get-Help.

.FORWARDHELPTARGETNAME

Redireciona para o tópico de ajuda do comando especificado. Você pode redirecionar os usuários para qualquer tópico de ajuda, incluindo tópicos de ajuda para uma função, script, cmdlet ou provedor.

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

Especifica a categoria de ajuda do item em .ForwardHelpTargetName. Os valores válidos são Alias, Cmdlet, HelpFile, Function, Provider, FAQGeneral, , Glossary, , ScriptCommand, ExternalScriptFilter, ou All. Use essa palavra-chave para evitar conflitos quando houver comandos com o mesmo nome.

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE

Especifica uma sessão que contém o tópico de ajuda. Insira uma variável que contenha um objeto PSSession . Essa palavra-chave é usada pelo cmdlet Export-PSSession para localizar os tópicos de ajuda para os comandos exportados.

# .REMOTEHELPRUNSPACE <PSSession-variable>

.EXTERNALHELP

Especifica um arquivo de ajuda baseado em XML para o script ou função.

# .EXTERNALHELP <XML Help File>

A .ExternalHelp palavra-chave é necessária quando uma função ou script é documentado em arquivos XML. Sem essa palavra-chave, Get-Help não é possível localizar o arquivo de ajuda baseado em XML para a função ou script.

A .ExternalHelp palavra-chave tem precedência sobre outras palavras-chave de ajuda baseadas em comentários. Se .ExternalHelp estiver presente, Get-Help não exibirá a ajuda baseada em comentários, mesmo que não consiga localizar um tópico de ajuda que corresponda ao .ExternalHelp valor da palavra-chave.

Se a função for exportada por um módulo, defina o .ExternalHelp valor da palavra-chave como um nome de arquivo sem um caminho. Get-Help Procura o nome de arquivo especificado em um subdiretório específico do idioma do diretório do módulo. Não há requisitos para o nome do arquivo de ajuda baseado em XML para uma função, mas uma prática recomendada é usar o seguinte formato:

<ScriptModule.psm1>-help.xml

Se a função não estiver incluída em um módulo, inclua um caminho para o arquivo de ajuda baseado em XML. Se o valor incluir um caminho e o caminho contiver subdiretórios específicos da cultura da interface do usuário, Get-Help procurará recursivamente os subdiretórios por um arquivo XML com o nome do script ou da função de acordo com os padrões de fallback de idioma estabelecidos para o Windows, assim como em um diretório de módulo.

Para obter mais informações sobre o formato de arquivo de ajuda baseado em XML da ajuda do cmdlet, consulte Como escrever a Ajuda do cmdlet.

Conteúdo gerado automaticamente

O nome, a sintaxe, a lista de parâmetros, a tabela de atributos de parâmetros, os parâmetros comuns e os Get-Help comentários são gerados automaticamente pelo cmdlet.

Nome

A seção Nome de um tópico de ajuda de função é retirada do nome da função na sintaxe da função. O Nome de um tópico de ajuda de script é retirado do nome do arquivo do script. Para alterar o nome ou suas maiúsculas, altere a sintaxe da função ou o nome do arquivo do script.

Sintaxe

A seção Sintaxe do tópico de ajuda é gerada a partir da sintaxe de função ou script. Para adicionar detalhes à sintaxe do tópico de ajuda, como o tipo .NET de um parâmetro, adicione os detalhes à sintaxe. Se você não especificar um tipo de parâmetro, o tipo de objeto será inserido como o valor padrão.

Lista de parâmetros

A lista de parâmetros no tópico de ajuda é gerada a partir da sintaxe da função ou do script e das descrições que você adiciona usando a .Parameter palavra-chave. Os parâmetros de função aparecem na seção Parâmetros do tópico de ajuda na mesma ordem em que aparecem na sintaxe de função ou script. A ortografia e o uso de maiúsculas nos nomes dos parâmetros também são retirados da sintaxe. Ele não é afetado pelo nome do parâmetro especificado pela .Parameter palavra-chave.

Parâmetros comuns

Os parâmetros comuns são adicionados à sintaxe e à lista de parâmetros do tópico de ajuda, mesmo que não tenham efeito. Para obter mais informações sobre os parâmetros comuns, consulte about_CommonParameters.

Tabela de atributos de parâmetro

Get-Help gera a tabela de atributos de parâmetro que aparece quando você usa o parâmetro Full ou Parameter de Get-Help. O valor dos atributos de valor Required, Position e Default é obtido da sintaxe de função ou script.

Os valores padrão e um valor para caracteres curinga Accept não aparecem na tabela de atributos de parâmetro, mesmo quando são definidos na função ou script. Para ajudar os usuários, forneça essas informações na descrição do parâmetro.

Comentários

A seção Comentários do tópico de ajuda é gerada automaticamente a partir do nome da função ou do script. Você não pode alterar ou afetar seu conteúdo.

Exemplos

Ajuda baseada em comentários para uma função

A seguinte função de exemplo inclui ajuda baseada em comentários:

function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
$name = $name + "." + $extension
$name

<#
.SYNOPSIS

Adds a file name extension to a supplied name.

.DESCRIPTION

Adds a file name extension to a supplied name.
Takes any strings for the file name or extension.

.PARAMETER Name
Specifies the file name.

.PARAMETER Extension
Specifies the extension. "Txt" is the default.

.INPUTS

None. You cannot pipe objects to Add-Extension.

.OUTPUTS

System.String. Add-Extension returns a string with the extension
or file name.

.EXAMPLE

PS> extension -name "File"
File.txt

.EXAMPLE

PS> extension -name "File" -extension "doc"
File.doc

.EXAMPLE

PS> extension "File" "doc"
File.doc

.LINK

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

Os resultados são os seguintes:

Get-Help -Name "Add-Extension" -Full

NAME

Add-Extension

SYNOPSIS

Adds a file name extension to a supplied name.

SYNTAX

Add-Extension [[-Name] <String>] [[-Extension] <String>]
[<CommonParameters>]

DESCRIPTION

Adds a file name extension to a supplied name. Takes any strings for the
file name or extension.

PARAMETERS

-Name
Specifies the file name.

Required?                    false
Position?                    0
Default value
Accept pipeline input?       false
Accept wildcard characters?

-Extension
Specifies the extension. "Txt" is the default.

Required?                    false
Position?                    1
Default value
Accept pipeline input?       false
Accept wildcard characters?

<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type
"get-help about_commonparameters".

INPUTS
None. You cannot pipe objects to Add-Extension.

OUTPUTS

System.String. Add-Extension returns a string with the extension or
file name.

Example 1

PS> extension -name "File"
File.txt

Example 2

PS> extension -name "File" -extension "doc"
File.doc

Example 3

PS> extension "File" "doc"
File.doc

RELATED LINKS

http://www.fabrikam.com/extension.html
Set-Item

Descrições de parâmetros na sintaxe da função

Este exemplo é o mesmo que o anterior, exceto que as descrições de parâmetros são inseridas na sintaxe da função. Esse formato é mais útil quando as descrições são breves.

function Add-Extension
{
param
(

[string]
#Specifies the file name.
$name,

[string]
#Specifies the file name extension. "Txt" is the default.
$extension = "txt"
)

$name = $name + "." + $extension
$name

<#
.SYNOPSIS

Adds a file name extension to a supplied name.

.DESCRIPTION

Adds a file name extension to a supplied name. Takes any strings for the
file name or extension.

.INPUTS

None. You cannot pipe objects to Add-Extension.

.OUTPUTS

System.String. Add-Extension returns a string with the extension or
file name.

.EXAMPLE

PS> extension -name "File"
File.txt

.EXAMPLE

PS> extension -name "File" -extension "doc"
File.doc

.EXAMPLE

PS> extension "File" "doc"
File.doc

.LINK

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

Ajuda baseada em comentários para um script

O script de exemplo a seguir inclui ajuda baseada em comentários. Observe as linhas em branco entre o fechamento #> e a Param instrução. Em um script que não tem uma Param instrução, deve haver pelo menos duas linhas em branco entre o comentário final no tópico de ajuda e a primeira declaração de função. Sem essas linhas em branco, Get-Help associa o tópico de ajuda à função, não ao script.

<#
.SYNOPSIS

Performs monthly data updates.

.DESCRIPTION

The Update-Month.ps1 script updates the registry with new data generated
during the past month and generates a report.

.PARAMETER InputPath
Specifies the path to the CSV-based input file.

.PARAMETER OutputPath
Specifies the name and path for the CSV-based output file. By default,
MonthlyUpdates.ps1 generates a name from the date and time it runs, and
saves the output in the local directory.

.INPUTS

None. You cannot pipe objects to Update-Month.ps1.

.OUTPUTS

None. Update-Month.ps1 does not generate any output.

.EXAMPLE

PS> .\Update-Month.ps1

.EXAMPLE

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv

.EXAMPLE

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath `
C:\Reports\2009\January.csv
#>

param ([string]$InputPath, [string]$OutPutPath)

function Get-Data { }
...

O comando a seguir obtém a ajuda do script. Como o script não está em um diretório listado $env:Path na variável de ambiente, o Get-Help comando que obtém a ajuda do script deve especificar o caminho do script.

Get-Help -Name .\update-month.ps1 -Full

# NAME

C:\ps-test\Update-Month.ps1

# SYNOPSIS

Performs monthly data updates.

# SYNTAX

C:\ps-test\Update-Month.ps1 [-InputPath] <String> [[-OutputPath]
<String>] [<CommonParameters>]

# DESCRIPTION

The Update-Month.ps1 script updates the registry with new data
generated during the past month and generates a report.

# PARAMETERS

-InputPath
Specifies the path to the CSV-based input file.

Required?                    true
Position?                    0
Default value
Accept pipeline input?       false
Accept wildcard characters?

-OutputPath
Specifies the name and path for the CSV-based output file. By
default, MonthlyUpdates.ps1 generates a name from the date
and time it runs, and saves the output in the local directory.

Required?                    false
Position?                    1
Default value
Accept pipeline input?       false
Accept wildcard characters?

<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type,
"get-help about_commonparameters".

# INPUTS

None. You cannot pipe objects to Update-Month.ps1.

# OUTPUTS

None. Update-Month.ps1 does not generate any output.

Example 1

PS> .\Update-Month.ps1

Example 2

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv

Example 3

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath
C:\Reports\2009\January.csv

# RELATED LINKS

Redirecionando para um arquivo XML

Você pode escrever tópicos de ajuda baseados em XML para funções e scripts. Embora a ajuda baseada em comentários seja mais fácil de implementar, a ajuda baseada em XML é necessária para a Ajuda atualizável e para fornecer tópicos de ajuda em vários idiomas.

O exemplo a seguir mostra as primeiras linhas do script Update-Month.ps1. O script usa a .ExternalHelp palavra-chave para especificar o caminho para um tópico de ajuda baseado em XML para o script.

Observe que o .ExternalHelp valor da palavra-chave aparece na mesma linha que a palavra-chave. Qualquer outra colocação é ineficaz.

# .ExternalHelp C:\MyScripts\Update-Month-Help.xml

param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...

Os exemplos a seguir mostram três posicionamentos válidos da .ExternalHelp palavra-chave em uma função.

function Add-Extension
{
# .ExternalHelp C:\ps-test\Add-Extension.xml

param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
}

function Add-Extension
{
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name

# .ExternalHelp C:\ps-test\Add-Extension.xml
}

# .ExternalHelp C:\ps-test\Add-Extension.xml
function Add-Extension
{
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
}

Redirecionando para um tópico de Ajuda diferente

O código a seguir é um trecho do início da função de ajuda interna no PowerShell, que exibe uma tela de texto de ajuda por vez. Como o tópico de ajuda do Get-Help cmdlet descreve a função de ajuda, a função de ajuda usa as .ForwardHelpTargetName palavras-chave e .ForwardHelpCategory para redirecionar o usuário para o tópico de ajuda do Get-Help cmdlet.

function help
{

<#
.FORWARDHELPTARGETNAME Get-Help
.FORWARDHELPCATEGORY Cmdlet
#>
[CmdletBinding(DefaultParameterSetName='AllUsersView')]
param(
[Parameter(Position=0, ValueFromPipelineByPropertyName=$true)]
[System.String]
${Name},
...

O comando a seguir usa esse recurso:

Get-Help -Name help

NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...

about_Comment_Based_Help

Descrição breve

Descrição longa

Sintaxe para ajuda baseada em comentários

Sintaxe para ajuda baseada em comentários em funções

Sintaxe para ajuda baseada em comentários em scripts

Sintaxe para ajuda baseada em comentários em módulos de script

Palavras-chave de ajuda baseadas em comentários

.SYNOPSIS

.DESCRIPTION

.PARAMETER

.EXAMPLE

.INPUTS

.OUTPUTS

.NOTES

.LINK

.COMPONENT

.ROLE

.FUNCTIONALITY

.FORWARDHELPTARGETNAME

.FORWARDHELPCATEGORY

.REMOTEHELPRUNSPACE

.EXTERNALHELP

Conteúdo gerado automaticamente

Nome

Sintaxe

Lista de parâmetros

Parâmetros comuns

Tabela de atributos de parâmetro

Comentários

Exemplos

Ajuda baseada em comentários para uma função

Descrições de parâmetros na sintaxe da função

Ajuda baseada em comentários para um script

Redirecionando para um arquivo XML

Redirecionando para um tópico de Ajuda diferente

Confira também

Comentários

Recursos adicionais