How to Add Examples to a Cmdlet Help Topic (Como Adicionar Exemplos ao Tópico de Ajuda de um Cmdlet)

  • Artigo

Coisas a saber sobre exemplos na Ajuda cmdlet

  • Listar todos os nomes dos parâmetros no comando, mesmo quando os nomes dos parâmetros são opcionais. Isto ajuda o utilizador a interpretar facilmente o comando.

  • Evite pseudónimos e nomes parciais de parâmetros, mesmo que trabalhem no PowerShell.

  • Na descrição do exemplo, explique o racional para a construção do comando. Explique por que escolheu parâmetros e valores específicos e como utiliza variáveis.

  • Se o comando utilizar expressões, explique-as em detalhe.

  • Se o comando utilizar propriedades e métodos de objetos, especialmente propriedades que não aparecem no visor predefinido, utilize o exemplo como uma oportunidade para dizer ao utilizador sobre o objeto.

Ajudar vistas que exibem exemplos

Exemplos aparecem apenas nas vistas detalhadas e completas da Ajuda cmdlet.

Adicionar um nó exemplos

O XML que se segue mostra como adicionar um nó Exemplos que contém um único nó exemplo. Adicione nós de exemplo adicionais para cada exemplo que pretende incluir no tópico.

<command:examples>
  <command:example>
  </command:example>
</command:examples>

Adicionar um título de exemplo

O XML que se segue mostra como adicionar um título para o exemplo. O título é usado para distinguir o exemplo de outros exemplos. PowerShell usa um cabeçalho padrão que inclui um número de exemplo sequencial.

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
  </command:example>
</command:examples>

Adicionar caracteres anteriores

O XML que se segue mostra como adicionar caracteres, como o Windows PowerShell de 200, que são apresentados imediatamente antes do comando do exemplo (sem quaisquer espaços de intervenção). PowerShell utiliza o Windows PowerShell pedido: C:\PS> .

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:Introduction>
      <maml:paragraph>C:\PS></maml:paragraph>
    </maml:Introduction>
</command:example>
</command:examples>

Adicionar o Comando

O XML que se segue mostra como adicionar o comando real do exemplo. Ao adicionar o comando, digite o nome inteiro (não utilize pseudónimo) de cmdlets e parâmetros. Além disso, utilize caracteres minúsculos sempre que possível.

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:Introduction>
      <maml:paragraph>C:\PS></maml:paragraph>
    </maml:Introduction>
    <dev:code> command </dev:code>
</command:example>
</command:examples>

Adicionar uma descrição

O XML que se segue mostra como adicionar uma descrição para o exemplo. O PowerShell utiliza um único conjunto de <maml:para> tags para a descrição, mesmo que <maml:para> possam ser utilizadas várias tags.

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:Introduction>
      <maml:paragraph>C:\PS></maml:paragraph>
    </maml:Introduction>
    <dev:code> command </dev:code>
    <dev:remarks>
      <maml:para> command description </maml:para>
    </dev:remarks>
</command:example>
</command:examples>

Adicionar saída de exemplo

O XML que se segue mostra como adicionar a saída do comando. A informação dos resultados do comando é opcional, mas em alguns casos é útil para demonstrar o efeito da utilização de parâmetros específicos. PowerShell usa dois conjuntos de etiquetas em branco <maml:para> para separar a saída de comando do comando.

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:Introduction>
      <maml:paragraph>C:\PS></maml:paragraph>
    </maml:Introduction>
    <dev:code> command </dev:code>
    <dev:remarks>
      <maml:para> command description </maml:para>
      <maml:para></maml:para>
      <maml:para></maml:para>
      <maml:para> command output </maml:para>
</dev:remarks>
</command:example>
</command:examples>