Comment-Based palavras-chave da Ajuda

Este tópico lista e descreve as palavras-chave na ajuda baseada em comentários.

Palavras-chave na Ajuda do Comment-Based

A seguir estão as palavras-chave da Ajuda válidas baseadas em comentários. Eles são listados na ordem em que normalmente aparecem em um tópico da Ajuda junto com o 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.

Observe que a palavra-chave .EXTERNALHELP tem precedência sobre todas as outras palavras-chave de ajuda baseadas em comentários. Quando .EXTERNALHELP está presente, o cmdlet Get-Help não exibe a ajuda baseada em comentários, mesmo quando não consegue encontrar um arquivo de ajuda que corresponda ao valor da palavra-chave.

.SYNOPSIS

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

.DESCRIPTION

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

.PARAMETER <Parameter-Name>

A descrição de um parâmetro. Você pode incluir uma palavra-chave .PARAMETER para cada parâmetro na função ou script.

As palavras-chave .PARAMETER podem aparecer em qualquer ordem no bloco de comentários, mas a ordem em que os parâmetros aparecem na instrução param ou na declaração de função determina a ordem em que os parâmetros aparecem no tópico da Ajuda. Para alterar a ordem dos parâmetros no tópico da Ajuda, altere a ordem dos parâmetros na instrução param ou na declaração de função.

Você também pode especificar uma descrição de parâmetro colocando um comentário na instrução param imediatamente antes do nome da variável de parâmetro. Se você usar um comentário de declaração param e uma palavra-chave .PARAMETER, a descrição associada à palavra-chave .PARAMETER será usada e o comentário da declaração param será ignorado.

.EXAMPLE

Um comando de exemplo que usa a função ou script, opcionalmente seguido por saída de exemplo e uma descrição. Repita esta 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. Repita esta palavra-chave para cada tipo de entrada.

.OUTPUTS

O tipo .NET dos objetos que o cmdlet retorna. Você também pode incluir uma descrição dos objetos retornados. Repita esta palavra-chave para cada tipo de saída.

.NOTES

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

.LINK

O nome de um tópico relacionado. Repita esta palavra-chave para cada tópico relacionado. Esse conteúdo aparece na seção Links relacionados do tópico da Ajuda.

O conteúdo da palavra-chave .LINK 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 Get-Help usa esse valor para filtrar os resultados da pesquisa retornados por Get-Help.

.ROLE

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

.FUNCTIONALITY

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

.FORWARDHELPTARGETNAME <Command-Name>

Redireciona para o tópico da Ajuda do comando especificado. Você pode redirecionar os usuários para qualquer tópico da ajuda, incluindo conteúdo 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, General, FAQ, Glossary, ScriptCommand, ExternalScript, Filterou All. Use essa palavra-chave para evitar conflitos quando houver comandos com o mesmo nome.

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE <PSSession-variable>

Especifica uma sessão que contém o tópico da ajuda. Insira uma variável que contenha um objeto PSSession. Essa palavra-chave é usada pelo cmdlet [Export-PSSession][09] para localizar o conteúdo de ajuda dos 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 palavra-chave .EXTERNALHELP é necessária quando uma função ou script é documentado em arquivos XML. Sem essa palavra-chave, Get-Help não é possível encontrar o arquivo de ajuda baseado em XML para a função ou script.

A palavra-chave .EXTERNALHELP 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 encontrar um tópico de ajuda que corresponda ao valor da palavra-chave .EXTERNALHELP.

Se a função for exportada por um módulo, defina o valor da palavra-chave .EXTERNALHELP 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 module. Não há requisitos para o nome do arquivo de ajuda baseado em XML para uma função. A partir do PowerShell 5.0, as funções exportadas por um módulo podem ser documentadas em um arquivo de ajuda nomeado para o módulo. Você não precisa usar .EXTERNALHELP a palavra-chave de comentário. Por exemplo, se a Test-Function função for exportada MyModule pelo módulo, você poderá nomear o arquivo de MyModule-help.xmlajuda . O Get-Help cmdlet procura ajuda para a Test-FunctionMyModule-help.xml função no arquivo no diretório module.

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, o Get-Help pesquisará os subdiretórios recursivamente em busca de um arquivo XML com o nome do script ou função de acordo com os padrões de fallback de linguagem estabelecidos para o Windows, assim como faz 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 Ajuda de Cmdlet.