Como adicionar a sinopse e o nome do cmdlet a um tópico de ajuda do cmdlet

Esta seção descreve como adicionar conteúdo que é exibido nas seções NAME e SYNOPSIS da ajuda do cmdlet. No arquivo de Ajuda, esse conteúdo é adicionado ao nó Comando para cada cmdlet.

Observação

Para uma exibição completa de um arquivo de Ajuda, abra um dos dll-Help.xml arquivos localizados no diretório de instalação do PowerShell. Por exemplo, o Microsoft.PowerShell.Commands.Management.dll-Help.xml arquivo contém conteúdo para vários dos cmdlets do PowerShell.

Para adicionar o nome do cmdlet e uma sinopse

• A Ajuda do cmdlet pode exibir duas descrições para o cmdlet. A primeira descrição é uma breve descrição conhecida como a sinopse. A segunda descrição é uma descrição mais detalhada que é discutida em Adicionando a descrição detalhada a um tópico de ajuda do cmdlet. Essas duas descrições devem ser escritas como um único parágrafo.

• Nas sinopses, não repita o nome do cmdlet. Informar o usuário de que o Get-Server cmdlet obtém um servidor é breve, mas não informativo. Em vez disso, use sinônimos e adicione detalhes à descrição.

  Exemplo: "Obtém um objeto que representa um computador local ou remoto."

• Use verbos simples como "get", "create" e "change" nas sinopses. Evite usar "set" porque ele é impreciso e palavras sofisticadas, como "modificar".

  Exemplo: "Obtém informações sobre a assinatura Authenticode em um arquivo."

• Escreva em voz ativa. Por exemplo, "Usar o objeto TimeSpan..." é muito mais claro do que "o objeto TimeSpan pode ser usado para..."

• Evite o verbo "display" ao descrever cmdlets que get objects. Embora Windows PowerShell exibe dados de cmdlet, é importante apresentar aos usuários o conceito de que o cmdlet retorna .NET Framework objetos cujos dados podem não ser exibidos. Se você enfatizar a exibição, o usuário poderá não perceber que o cmdlet pode ter retornado muitas outras propriedades e métodos úteis que não são exibidos.

Consulte Também

SDK do Windows PowerShell