Palavras-chave da Ajuda Comment-Based

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

Palavras-chave na Ajuda Comment-Based

Veja a seguir palavras-chave válidas da Ajuda baseada em comentários. Eles são listados na ordem em que normalmente aparecem em um tópico da Ajuda, juntamente 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 estiver presente, o cmdlet Get-Help não exibirá ajuda baseada em comentários, mesmo quando não conseguir encontrar um arquivo de ajuda que corresponda ao valor da palavra-chave.

.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 <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 na qual os parâmetros aparecem na instrução param ou na declaração de função determina a ordem na qual 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 instrução param e uma palavra-chave .PARAMETER, a descrição associada à palavra-chave .PARAMETER será usada e o comentário da instrução param será ignorado.

.EXAMPLE

Um comando de exemplo que usa a função ou o script, opcionalmente seguido pela 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. Repita essa palavra-chave para cada tipo de entrada.

.OUTPUTS

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

.NOTES

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

.LINK

O nome de um tópico relacionado. Repita essa 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. Quando você usa o parâmetro Online de Get-Help, a versão online é aberta. 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 de 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 de ajuda para o comando especificado. Você pode redirecionar usuários para qualquer tópico de 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 de ajuda. Insira uma variável que contenha um objeto PSSession. Essa palavra-chave é usada pelo cmdlet [Export-PSSession][09] para localizar o conteúdo da 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 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 o 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á ajuda baseada em comentários, mesmo que não encontre 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 do 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. 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 pelo MyModule módulo, você poderá nomear o arquivo MyModule-help.xmlde ajuda. O Get-Help cmdlet procura ajuda para a Test-Function função no MyModule-help.xml arquivo no diretório do módulo.

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 (UI), Get-Help pesquisará os subdiretórios recursivamente por um arquivo XML com o nome do script ou função conforme os padrões de fallback de linguagem estabelecidos para o Windows, do mesmo modo que faz em um diretório de módulo.

Para obter mais informações sobre o formato de arquivo de ajuda baseado em XML do cmdlet, consulte [How to Write Cmdlet Help].