Como adicionar sintaxe a um tópico da Ajuda do cmdlet

Artigo
03/25/2025

Observação

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.

Antes de começar a codificar o XML para o diagrama de sintaxe no arquivo de Ajuda do cmdlet, leia esta seção para obter uma imagem clara do tipo de dados que você precisa fornecer, como os atributos de parâmetro e como esses dados são exibidos no diagrama de sintaxe.

Atributos de parâmetro

Obrigatório
- Se true, o parâmetro deve aparecer em todos os comandos que usam o conjunto de parâmetros.
- Se false, o parâmetro é opcional em todos os comandos que usam o conjunto de parâmetros.
Posição
- Se nomeado, o nome do parâmetro é necessário.
- Se posicional, o nome do parâmetro é opcional. Quando é omitido, o valor do parâmetro deve estar na posição especificada no comando. Por exemplo, se o valor for position="1", o valor do parâmetro deve ser o primeiro ou o único valor de parâmetro sem nome no comando.
Entrada de pipeline
- Se true (ByValue), você pode canalizar a entrada para o parâmetro. A entrada é associada ao parâmetro ("vinculado a"), mesmo que o nome da propriedade e o tipo de objeto não correspondam ao tipo esperado. Os componentes de vinculação de parâmetros do PowerShell tentam converter a entrada para o tipo correto e falham no comando somente quando o tipo não pode ser convertido. Apenas um parâmetro em um conjunto de parâmetros pode ser associado por valor.
- Se true (ByPropertyName), você pode canalizar a entrada para o parâmetro. No entanto, a entrada é associada ao parâmetro somente quando o nome do parâmetro corresponde ao nome de uma propriedade do objeto de entrada. Por exemplo, se o nome do parâmetro for Path, os objetos canalizados para o cmdlet serão associados a esse parâmetro somente quando o objeto tiver uma propriedade chamada path.
- Se true (ByValue, ByPropertyName), você pode canalizar a entrada para o parâmetro pelo nome da propriedade ou pelo valor. Apenas um parâmetro em um conjunto de parâmetros pode ser associado por valor.
- Se false, você não pode canalizar a entrada para esse parâmetro.
Globbing
- Se verdadeiro, o texto que o usuário digita para o valor do parâmetro pode incluir caracteres curinga.
- Se false, o texto que o usuário digita para o valor do parâmetro não pode incluir caracteres curinga.

Atributos de valor de parâmetro

Obrigatório
- Se true, o valor especificado deve ser usado sempre que usar o parâmetro em um comando.
- Se false, o valor do parâmetro é opcional. Normalmente, um valor é opcional somente quando é um dos vários valores válidos para um parâmetro, como em um tipo enumerado.

O atributo Required de um valor de parâmetro é diferente do atributo Required de um parâmetro.

O atributo required de um parâmetro indica se o parâmetro (e seu valor) deve ser incluído ao invocar o cmdlet. Por outro lado, o atributo required de um valor de parâmetro é usado somente quando o parâmetro é incluído no comando. Ele indica se esse valor específico deve ser usado com o parâmetro.

Normalmente, os valores de parâmetro que são espaços reservados são necessários e os valores de parâmetro que são literais não são necessários, porque eles são um dos vários valores que podem ser usados com o parâmetro.

Recolha de informações de sintaxe

Comece com o nome do cmdlet.
```
SYNTAX
    Get-Tech
```
Liste todos os parâmetros do cmdlet. Digite um hífen (-) antes do nome de cada parâmetro. Separe os parâmetros em conjuntos de parâmetros (alguns cmdlets podem ter apenas um conjunto de parâmetros). Neste exemplo, o cmdlet Get-Tech tem dois conjuntos de parâmetros.
```
SYNTAX
    Get-Tech -Name -Type
    Get-Tech -Id -List -Type
```
Inicie cada conjunto de parâmetros com o nome do cmdlet.

Liste primeiro o conjunto de parâmetros padrão. O parâmetro padrão é especificado pela classe de cmdlet.

Para cada conjunto de parâmetros, liste seu parâmetro exclusivo primeiro, a menos que haja parâmetros posicionais que devam aparecer primeiro. No exemplo anterior, os parâmetros Name e Id são parâmetros exclusivos para os dois conjuntos de parâmetros (cada conjunto de parâmetros deve ter um parâmetro exclusivo para esse conjunto de parâmetros). Isso torna mais fácil para os usuários identificar qual parâmetro eles precisam fornecer para o conjunto de parâmetros.

Liste os parâmetros na ordem em que devem aparecer no comando. Se a ordem não for importante, liste os parâmetros relacionados juntos ou liste os parâmetros usados com mais frequência primeiro.

Certifique-se de listar os parâmetros WhatIf e Confirm se o cmdlet oferecer suporte a ShouldProcess.

Não liste os parâmetros comuns (como Verbose, Debug e ErrorAction) no diagrama de sintaxe. O cmdlet Get-Help adiciona essas informações para você quando exibe o tópico da Ajuda.
Adicione os valores dos parâmetros. No PowerShell, os valores de parâmetro são representados por seu tipo .NET. No entanto, o nome do tipo pode ser abreviado, como "string" para System.String.
```
SYNTAX
    Get-Tech -Name string -Type Basic Advanced
    Get-Tech -Id int -List -Type Basic Advanced
```
Abreviar tipos, desde que seu significado seja claro, como string para System.String e int para System.Int32.

Liste todos os valores de enumerações, como o parâmetro -Type no exemplo anterior, que pode ser definido como básico ou avançado.

Os parâmetros de opção, como -List no exemplo anterior, não têm valores.
Adicione colchetes angulares a valores de parâmetros que são espaços reservados, em comparação com valores de parâmetros que são literais.
```
SYNTAX
    Get-Tech -Name <string> -Type Basic Advanced
    Get-Tech -Id <int> -List -Type Basic Advanced
```

Coloque os parâmetros opcionais e seus vales entre colchetes.

SYNTAX
    Get-Tech -Name <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]

Coloque nomes de parâmetros opcionais (para parâmetros posicionais) entre colchetes. O nome dos parâmetros que são posicionais, como o parâmetro Name no exemplo a seguir, não precisa ser incluído no comando.
```
SYNTAX
    Get-Tech [-Name] <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]
```
Se um valor de parâmetro puder conter vários valores, como uma lista de nomes no parâmetro Name, adicione um par de colchetes diretamente após o valor do parâmetro.
```
SYNTAX
    Get-Tech [-Name] <string[]> [-Type Basic Advanced]
    Get-Tech -Id <int[]> [-List] [-Type Basic Advanced]
```
Se o usuário puder escolher entre parâmetros ou valores de parâmetros, como o parâmetro Type, coloque as opções entre colchetes e separe-as com o(;) símbolo(s) exclusivo(s) OR.
```
SYNTAX
    Get-Tech [-Name] <string[]> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]
```

Se o valor do parâmetro precisar usar formatação específica, como aspas ou parênteses, mostre o formato na sintaxe.

SYNTAX
    Get-Tech [-Name] <"string[]"> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]

Codificando o XML do diagrama de sintaxe

O nó de sintaxe do XML começa imediatamente após o nó de descrição, que termina com a marca </maml:description>. Para obter informações sobre como coletar os dados usados no diagrama de sintaxe, consulte Coletando informações de sintaxe.

Adicionando um nó de sintaxe

O diagrama de sintaxe exibido no tópico da Ajuda do cmdlet é gerado a partir dos dados no nó de sintaxe do XML. O nó de sintaxe é incluído em um par de <command:syntax> tags. Com cada conjunto de parâmetros do cmdlet incluído em um par de <command:syntaxitem> tags. Não há limite para o número de <command:syntaxitem> tags que você pode adicionar.

O exemplo a seguir mostra um nó de sintaxe que tem nós de item de sintaxe para dois conjuntos de parâmetros.

<command:syntax>
  <command:syntaxItem>
    ...
    <!--Parameter Set 1 (default parameter set) parameters go here-->
    ...
  </command:syntaxItem>
  <command:syntaxItem>
    ...
    <!--Parameter Set 2 parameters go here-->
    ...
  </command:syntaxItem>
</command:syntax>

Adicionando o nome do cmdlet aos dados do conjunto de parâmetros

Cada conjunto de parâmetros do cmdlet é especificado em um nó de item de sintaxe. Cada nó de item de sintaxe começa com um par de marcas <maml:name> que incluem o nome do cmdlet.

O exemplo a seguir inclui um nó de sintaxe que tem nós de item de sintaxe para dois conjuntos de parâmetros.

<command:syntax>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
</command:syntax>

Adicionando parâmetros

Cada parâmetro adicionado ao nó do item de sintaxe é especificado dentro de um par de marcas <command:parameter>. Você precisa de um par de marcas de <command:parameter> para cada parâmetro incluído no conjunto de parâmetros, com exceção dos parâmetros comuns fornecidos pelo PowerShell.

Os atributos da marca <command:parameter> de abertura determinam como o parâmetro aparece no diagrama de sintaxe. Para obter informações sobre atributos de parâmetro, consulte Parameter Attributes.

Observação

A tag <command:parameter> oferece suporte a um elemento filho <maml:description> cujo conteúdo nunca é exibido. As descrições dos parâmetros são especificadas no nó do parâmetro do XML. Para evitar inconsistências entre as informações no item de sintaxe e o nó do parâmetro, omita o (<maml:description> ou deixe-o vazio.

O exemplo a seguir inclui um nó de item de sintaxe para um conjunto de parâmetros com dois parâmetros.

<command:syntaxItem>
  <maml:name>Cmdlet-Name</maml:name>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByValue)" position="1">
    <maml:name>ParameterName1</maml:name>
    <command:parameterValue required="true">
      string[]
    </command:parameterValue>
  </command:parameter>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByPropertyName)">
    <maml:name>ParameterName2</maml:name>
    <command:parameterValue required="true">
      int32[]
    </command:parameterValue>
  </command:parameter>
</command:syntaxItem>

Partilhar via