Como adicionar sintaxe a um tópico de ajuda de cmdlet

Observação

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.

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 for true, o parâmetro deverá aparecer em todos os comandos que usam o conjunto de parâmetros.
- Se for falso, o parâmetro será opcional em todos os comandos que usam o conjunto de parâmetros.
Posição
- Se nomeado, o nome do parâmetro será necessário.
- Se posicional, o nome do parâmetro será opcional. Quando ele é 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 deverá ser o primeiro ou apenas o valor do parâmetro sem nome no comando.
Entrada de pipeline
- Se true (ByValue), você pode redirecionar a entrada para o parâmetro. A entrada é associada ao parâmetro ("bound to") mesmo que o nome da propriedade e o tipo de objeto não correspondam ao tipo esperado. Os componentes de associação de parâmetros do PowerShell tentam converter a entrada no tipo correto e falham no comando somente quando o tipo não pode ser convertido. Somente um parâmetro em um conjunto de parâmetros pode ser associado por valor.
- Se true (ByPropertyName), você pode redirecionar 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 um caminho nomeado de propriedade.
- Se true (ByValue, ByPropertyName), você pode redirecionar a entrada para o parâmetro por nome de propriedade ou por valor. Somente um parâmetro em um conjunto de parâmetros pode ser associado por valor.
- Se for falso, você não poderá direcionar 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 for falso, 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 for true, o valor especificado deverá ser usado sempre que usar o parâmetro em um comando.
- Se for falso, o valor do parâmetro será 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 obrigatório de um valor de parâmetro é diferente do atributo required de um parâmetro.

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

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

Coletando 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 de cada nome de 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 o conjunto de parâmetros padrão primeiro. O parâmetro padrão é especificado pela classe cmdlet.

Para cada conjunto de parâmetros, liste seu parâmetro exclusivo primeiro, a menos que haja parâmetros posicionais que devem aparecer primeiro. No exemplo anterior, os parâmetros Nome 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 facilita que os usuários identifiquem qual parâmetro eles precisam fornecer para o conjunto de parâmetros.

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

Certifique-se de listar os parâmetros WhatIf e Confirm se o cmdlet for compatível com 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 de parâmetro. 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 de cadeia de caracteres para System.String e int para System.Int32.

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

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

Coloque parâmetros opcionais e seus vales em 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) em 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 seguindo 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âmetro, como o parâmetro Type, coloque as opções entre colchetes e separe-as com o símbolo OR exclusivo (;)).
```
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 diagrama de sintaxe XML

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 é colocado em um par de marcas de <command:syntax>. Com cada conjunto de parâmetros do cmdlet colocado em um par de marcas de <command:syntaxitem>. Não há limite para o número de marcas de <command:syntaxitem> 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ó de item de sintaxe é especificado dentro de um par de marcas de <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 de <command:parameter> de abertura determinam como o parâmetro aparece no diagrama de sintaxe. Para obter informações sobre atributos de parâmetro, consulte atributos de parâmetro.

Observação

A marca <command:parameter> dá suporte a um elemento filho <maml:description> cujo conteúdo nunca é exibido. As descrições de parâmetro são especificadas no nó de parâmetro do XML. Para evitar inconsistências entre as informações no item de sintaxe e o nó de 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>

Comentários

Esta página foi útil?

Last updated on 2025-03-25