Adición de sintaxis a un tema de ayuda de cmdlet

Artículo
2025-03-25

Nota:

La creación manual de ayuda basada en XML es muy difícil. El módulo PlatyPS le permite escribir ayuda en Markdown y, a continuación, convertirlo a ayuda basada en XML. Esto facilita mucho la escritura y el mantenimiento de la ayuda. platyPS también puede crear los paquetes de ayuda actualizables automáticamente. Para obtener más información, consulte ayuda basada en XML mediante PlatyPS.

Antes de empezar a codificar el XML del diagrama de sintaxis en el archivo de ayuda del cmdlet, lea esta sección para obtener una imagen clara del tipo de datos que necesita proporcionar, como los atributos de parámetro y cómo se muestran esos datos en el diagrama de sintaxis.

Atributos de parámetro

Obligatorio
- Si es true, el parámetro debe aparecer en todos los comandos que usan el conjunto de parámetros.
- Si es false, el parámetro es opcional en todos los comandos que usan el conjunto de parámetros.
Posición
- Si se llama, se requiere el nombre del parámetro.
- Si es posicional, el nombre del parámetro es opcional. Cuando se omite, el valor del parámetro debe estar en la posición especificada en el comando . Por ejemplo, si el valor es position="1", el valor del parámetro debe ser el primer valor de parámetro sin nombre en el comando.
Entrada de canalización
- Si es true (ByValue), puede canalizar la entrada al parámetro . La entrada está asociada con el parámetro ("enlazado a") incluso si el nombre de propiedad y el tipo de objeto no coinciden con el tipo esperado. Los componentes de enlace de parámetros de PowerShell intentan convertir la entrada en el tipo correcto y producen un error en el comando solo cuando no se puede convertir el tipo. Solo un parámetro de un conjunto de parámetros se puede asociar por valor.
- Si es true (ByPropertyName), puede canalizar la entrada al parámetro . Sin embargo, la entrada está asociada al parámetro solo cuando el nombre del parámetro coincide con el nombre de una propiedad del objeto de entrada. Por ejemplo, si el nombre del parámetro es Path, los objetos canalizaciones al cmdlet están asociados a ese parámetro solo cuando el objeto tiene una propiedad denominada path.
- Si es true (ByValue, ByPropertyName), puede canalizar la entrada al parámetro por nombre de propiedad o por valor. Solo un parámetro de un conjunto de parámetros se puede asociar por valor.
- Si es false, no se puede canalizar la entrada a este parámetro.
Globbing
- Si es true, el texto que el usuario escribe para el valor del parámetro puede incluir caracteres comodín.
- Si es false, el texto que el usuario escribe para el valor del parámetro no puede incluir caracteres comodín.

Atributos de valor de parámetro

Obligatorio
- Si es true, el valor especificado debe usarse siempre que use el parámetro en un comando.
- Si es false, el valor del parámetro es opcional. Normalmente, un valor solo es opcional cuando es uno de varios valores válidos para un parámetro, como en un tipo enumerado.

El atributo Required de un valor de parámetro es diferente del atributo required de de un parámetro.

El atributo necesario de un parámetro indica si se debe incluir el parámetro (y su valor) al invocar el cmdlet. En cambio, el atributo necesario de un valor de parámetro solo se usa cuando el parámetro se incluye en el comando . Indica si ese valor concreto debe usarse con el parámetro .

Normalmente, los valores de parámetro que son marcadores de posición son obligatorios y los valores de parámetro que son literales no son necesarios, ya que son uno de los varios valores que se pueden usar con el parámetro .

Recopilación de información de sintaxis

Comience con el nombre del cmdlet.
```
SYNTAX
    Get-Tech
```
Enumere todos los parámetros del cmdlet. Escriba un guión (-) antes de cada nombre de parámetro. Separe los parámetros en conjuntos de parámetros (algunos cmdlets pueden tener solo un conjunto de parámetros). En este ejemplo, el cmdlet Get-Tech tiene dos conjuntos de parámetros.
```
SYNTAX
    Get-Tech -Name -Type
    Get-Tech -Id -List -Type
```
Inicie cada conjunto de parámetros con el nombre del cmdlet.

Enumere primero el parámetro predeterminado establecido. La clase de cmdlet especifica el parámetro predeterminado.

Para cada conjunto de parámetros, enumere primero su parámetro único, a menos que haya parámetros posicionales que deben aparecer primero. En el ejemplo anterior, los parámetros Name e Id son parámetros únicos para los dos conjuntos de parámetros (cada conjunto de parámetros debe tener un parámetro único para ese conjunto de parámetros). Esto facilita a los usuarios identificar qué parámetro necesitan proporcionar para el conjunto de parámetros.

Enumere los parámetros en el orden en que deben aparecer en el comando . Si el orden no importa, enumere los parámetros relacionados juntos o enumere primero los parámetros usados con más frecuencia.

Asegúrese de enumerar los parámetros WhatIf y Confirm si el cmdlet admite ShouldProcess.

No enumere los parámetros comunes (como Verbose, Debug y ErrorAction) en el diagrama de sintaxis. El cmdlet Get-Help agrega esa información cuando muestra el tema de Ayuda.
Agregue los valores de parámetro. En PowerShell, los valores de parámetro se representan mediante su tipo de .NET. Sin embargo, el nombre de tipo se puede abreviar, como "string" para System.String.
```
SYNTAX
    Get-Tech -Name string -Type Basic Advanced
    Get-Tech -Id int -List -Type Basic Advanced
```
Abreviar tipos siempre que su significado esté claro, como cadena para System.String y int para System.Int32.

Enumere todos los valores de enumeraciones, como el parámetro -Type en el ejemplo anterior, que se puede establecer en básico o avanzadas.

Los parámetros switch, como -List en el ejemplo anterior, no tienen valores.
Agregue corchetes angulares a los valores de parámetros que son marcador de posición, en comparación con los valores de parámetro que son literales.
```
SYNTAX
    Get-Tech -Name <string> -Type Basic Advanced
    Get-Tech -Id <int> -List -Type Basic Advanced
```

Incluya parámetros opcionales y sus vales entre corchetes.

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

Incluya nombres de parámetros opcionales (para parámetros posicionales) entre corchetes. El nombre de los parámetros que son posicionales, como el parámetro Name en el ejemplo siguiente, no es necesario incluirlo en el comando .
```
SYNTAX
    Get-Tech [-Name] <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]
```
Si un valor de parámetro puede contener varios valores, como una lista de nombres en el parámetro Name, agregue un par de corchetes directamente después del valor del parámetro.
```
SYNTAX
    Get-Tech [-Name] <string[]> [-Type Basic Advanced]
    Get-Tech -Id <int[]> [-List] [-Type Basic Advanced]
```
Si el usuario puede elegir entre parámetros o valores de parámetro, como el parámetro Type, incluya las opciones entre corchetes y separe con el símbolo OR exclusivo (;)).
```
SYNTAX
    Get-Tech [-Name] <string[]> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]
```

Si el valor del parámetro debe usar formato específico, como comillas o paréntesis, muestre el formato en la sintaxis.

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

Codificación del diagrama de sintaxis XML

El nodo de sintaxis del XML comienza inmediatamente después del nodo de descripción, que termina con la etiqueta </maml:description>. Para obtener información sobre cómo recopilar los datos usados en el diagrama de sintaxis, vea Recopilación de información de sintaxis.

Adición de un nodo de sintaxis

El diagrama de sintaxis que se muestra en el tema de ayuda del cmdlet se genera a partir de los datos del nodo de sintaxis del XML. El nodo de sintaxis se incluye en un par de etiquetas <command:syntax>. Con cada conjunto de parámetros del cmdlet incluido en un par de etiquetas <command:syntaxitem>. No hay límite para el número de etiquetas de <command:syntaxitem> que puede agregar.

En el ejemplo siguiente se muestra un nodo de sintaxis que tiene nodos de elemento de sintaxis para dos 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>

Adición del nombre del cmdlet a los datos del conjunto de parámetros

Cada conjunto de parámetros del cmdlet se especifica en un nodo de elemento de sintaxis. Cada nodo de elemento de sintaxis comienza con un par de etiquetas <maml:name> que incluyen el nombre del cmdlet.

En el ejemplo siguiente se incluye un nodo de sintaxis que tiene nodos de elemento de sintaxis para dos 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>

Adición de parámetros

Cada parámetro agregado al nodo de elemento de sintaxis se especifica dentro de un par de etiquetas de <command:parameter>. Necesita un par de etiquetas de <command:parameter> para cada parámetro incluido en el conjunto de parámetros, a excepción de los parámetros comunes proporcionados por PowerShell.

Los atributos de la etiqueta de apertura <command:parameter> determinan cómo aparece el parámetro en el diagrama de sintaxis. Para obtener información sobre los atributos de parámetro, vea Atributos de parámetro.

Nota:

La etiqueta <command:parameter> admite un elemento secundario <maml:description> cuyo contenido nunca se muestra. Las descripciones de parámetro se especifican en el nodo de parámetro del XML. Para evitar incoherencias entre la información del elemento de sintaxis bodes y el nodo de parámetros, omita (<maml:description> o déjela vacía.

En el ejemplo siguiente se incluye un nodo de elemento de sintaxis para un conjunto de parámetros con dos 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>

Compartir a través de