Como adicionar uma descrição do cmdlet

Note

A criação manual de ajuda baseada em XML é muito difícil. O módulo PlatyPS permite que você escreva ajuda no Markdown e converta-a em ajuda baseada em XML. Isso facilita muito a gravação e a manutenção da ajuda. PlatyPS também pode criar os pacotes de Ajuda Atualizáveis para você. Para obter mais informações, consulte Criar ajuda baseada em XML usando o PlatyPS.

Esta seção descreve como adicionar conteúdo exibido na seção DESCRIPTION da Ajuda do cmdlet. No arquivo de Ajuda, esse conteúdo é adicionado ao nó Comando para cada cmdlet.

Note

Para obter 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 uma descrição

O <maml:description> nó contém a descrição detalhada do cmdlet. Esse elemento contém um ou mais <maml:para> elementos. A descrição está entre um <maml:para> elemento. O exemplo a seguir mostra a estrutura do XML:

<maml:description>
  <maml:para>...</maml:para>
</maml:description>

Sugestões de escrita

  • Comece explicando os recursos básicos do cmdlet com mais detalhes. Em muitos casos, você pode explicar os termos usados no nome do cmdlet e ilustrar conceitos desconhecidos com um exemplo. Por exemplo, se o cmdlet anexar dados a um arquivo, explique que ele adiciona dados ao final de um arquivo existente.

  • Para localizar todos os recursos do cmdlet, examine a lista de parâmetros. Descreva a função primária do cmdlet e inclua outras funções e recursos. Por exemplo, se a função principal do cmdlet for alterar uma propriedade, mas o cmdlet puder alterar todas as propriedades, diga-o na descrição detalhada. Se os parâmetros de cmdlet permitirem que os usuários solicitem informações de maneiras diferentes, explique-as.

  • Inclua informações sobre como os usuários podem usar o cmdlet, além dos usos óbvios. Por exemplo, você pode usar o objeto que o Get-Host cmdlet recupera para alterar a cor do texto na janela de comando Windows PowerShell.

    Exemplo: "O Get-Acl cmdlet obtém objetos que representam o descritor de segurança de um arquivo ou recurso. O descritor de segurança contém as ACLs (listas de controle de acesso) do recurso. A ACL especifica as permissões que os usuários e grupos de usuários têm para acessar o recurso."

  • A descrição detalhada deve descrever o cmdlet, mas não deve descrever os conceitos que o cmdlet usa. Coloque definições de conceito em Notas Adicionais.

Consulte Também

Windows SDK do PowerShell

  • Last updated on