How to Add a Cmdlet Description (Como Adicionar a Descrição de um Cmdlet)

Note

A criação manual de ajuda baseada em XML é muito difícil. O módulo PlatyPS permite escrever ajuda em Markdown e, em seguida, convertê-la em ajuda baseada em XML. Isso torna muito mais fácil escrever e manter a ajuda. PlatyPS também pode criar os pacotes de Ajuda atualizáveis para você. Para obter mais informações, consulte Ajuda para criar base em XML usando o PlatyPS.

Esta secção descreve como adicionar conteúdo que é exibido na secção DESCRIÇÃO do cmdlet Help. No ficheiro Help, este conteúdo é adicionado ao nó Command para cada cmdlet.

Note

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

Para adicionar uma descrição

O <maml:description> nó contém a descrição detalhada do cmdlet. Este elemento contém um ou mais <maml:para> elementos. A descrição está incluída num <maml:para> elemento. O exemplo seguinte mostra a estrutura do XML:

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

Dicas de escrita

  • Comece por explicar as características básicas do cmdlet com mais detalhe. Em muitos casos, pode explicar os termos usados no nome do cmdlet e ilustrar conceitos desconhecidos com um exemplo. Por exemplo, se o cmdlet acrescentar dados a um ficheiro, explique que adiciona dados ao final de um ficheiro existente.

  • Para encontrar todas as funcionalidades do cmdlet, consulte a lista de parâmetros. Descreva a função principal do cmdlet e depois inclua outras funções e características. Por exemplo, se a função principal do cmdlet for alterar uma propriedade, mas o cmdlet pode alterar todas as propriedades, diga isso na descrição detalhada. Se os parâmetros do cmdlet permitem aos utilizadores solicitar informação de formas diferentes, explique-a.

  • Inclua informações sobre as formas como os utilizadores podem usar o cmdlet, para além das utilizações óbvias. Por exemplo, podes usar o objeto que o Get-Host cmdlet recupera para mudar a cor do texto na janela de comandos do PowerShell do Windows.

    Exemplo: "O Get-Acl cmdlet recebe objetos que representam o descritor de segurança de um ficheiro ou recurso. O descritor de segurança contém as listas de controlo de acesso (ACLs) do recurso. A ACL especifica as permissões que os utilizadores e grupos de utilizadores têm para aceder ao recurso."

  • A descrição detalhada deve descrever o cmdlet, mas não deve descrever conceitos que o cmdlet utiliza. Definições de conceitos de colocação em Notas Adicionais.

Ver também

Windows PowerShell SDK

  • Last updated on