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 de objetos do Microsoft .NET Framework 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 Framework 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. 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 da 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 tópicos da Ajuda para uma função, script, cmdlet ou provedor.

.FORWARDHELPCATEGORY <Category>

Especifica a categoria Ajuda do item em .FORWARDHELPTARGETNAME. Use essa palavra-chave para evitar conflitos quando houver comandos com o mesmo nome.

Os valores válidos são:

• Alias
• Cmdlet
• Ficheiro de Ajuda
• Function
• Provider
• General
• FAQ
• Glossary
• ScriptCommand
• ExternalScript
• Filtrar
• Tudo

.REMOTEHELPRUNSPACE <PSSession-variable>

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

.EXTERNALHELP <XML Help File>

Especifica o caminho e/ou o nome de um arquivo de Ajuda baseado em XML para o script ou função.

A palavra-chave .EXTERNALHELP informa ao cmdlet Get-Help para obter ajuda para o script ou função em um arquivo baseado em XML. A palavra-chave .EXTERNALHELP é necessária ao usar um arquivo de ajuda baseado em XML para um script ou função. Sem ele, Get-Help não encontrará um arquivo de ajuda para a função ou script.

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.

Quando a função é exportada por um módulo de script, o valor de .EXTERNALHELP deve ser um nome de arquivo sem um caminho. Get-Help procura o arquivo em um subdiretório específico da localidade do diretório module. Não há requisitos para o nome do arquivo, mas uma prática recomendada é usar o seguinte formato de nome de arquivo: <ScriptModule>.psm1-help.xml.

Quando a função não estiver associada a um módulo, inclua um caminho e um nome de arquivo no valor da palavra-chave .EXTERNALHELP. Se o caminho especificado para o arquivo XML 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 para todos os tópicos da Ajuda baseados em XML.

Para obter mais informações sobre o formato de arquivo de Ajuda baseado em XML da Ajuda do cmdlet, consulte Escrevendo a Ajuda do Cmdlet do Windows PowerShell.