Compartir a través de

Guía de estilo de PowerShell y Docs

En este artículo se proporcionan instrucciones de estilo específicas del contenido de PowerShell-Docs. Se basa en la información que se describe en La información general.

Aplicar formato a los elementos de sintaxis de comandos

Use las reglas siguientes para dar formato a los elementos del lenguaje de PowerShell cuando los elementos se usan en una oración.

  • Use siempre el nombre completo para cmdlets y parámetros en el caso Pascal adecuado.

  • Usa solo un alias cuando estés demostrando específicamente el alias.

  • Las palabras clave y los operadores de PowerShell deben estar en minúsculas.

  • Se debe dar formato a los siguientes elementos mediante texto en negrita :

    • Nombres de tipo

    • Nombres de clase

    • Nombres de propiedad

    • Nombres de parámetros

      • Por defecto, use el parámetro sin el prefijo de guión.
      • Use el nombre del parámetro con el guion si está ilustrando la sintaxis. Envuelva el parámetro en comillas invertidas.

      Por ejemplo:

      The parameter's name is **Name**, but it's typed as `-Name` when used on the command
line as a parameter.

  • Se debe dar formato a los siguientes elementos mediante comillas invertidas (`):

    • Valores de propiedad y parámetros

    • Nombres de tipo que usan el estilo entre corchetes: por ejemplo: [System.Io.FileInfo]

    • Referirse a personajes por su nombre. Por ejemplo: use el carácter asterisco (*) como comodín.

    • Palabras clave y operadores de lenguaje

    • Nombres de cmdlets, funciones y scripts

    • Alias de comandos y parámetros

    • Nombres de método: por ejemplo: el ToString() método devuelve una representación de cadena del objeto

    • variables

    • Comandos nativos

    • Rutas de acceso de archivos y directorios

    • Ejemplos de sintaxis de comandos insertados: consulte Markdown para obtener ejemplos de código.

      En este ejemplo se muestran algunos ejemplos de retroceso:

      The following code uses `Get-ChildItem` to list the contents of `C:\Windows` and assigns
the output to the `$files` variable.

```powershell
$files = Get-ChildItem C:\Windows
```

      En este ejemplo se muestra la sintaxis de comandos en línea.

      To start the spooler service on a remote computer named DC01, you type:
`sc.exe \\DC01 start spooler`.

      La inclusión de la extensión de archivo garantiza que el comando correcto se ejecute según la precedencia de comandos de PowerShell.

Markdown para ejemplos de código

Markdown admite dos estilos de código diferentes:

  • Intervalos de código (insertados): marcados por un solo carácter de retroceso (`). Se usa dentro de un párrafo en lugar de como un bloque independiente.
  • Bloques de código - un bloque de varias líneas rodeado por cadenas de triple acento grave (```). Los bloques de código también pueden tener una etiqueta de lenguaje después de las operaciones inversas. La etiqueta de lenguaje habilita el resaltado de sintaxis para el contenido del bloque de código.

Todos los bloques de código deben estar contenidos en una barrera de código. Nunca use sangría para bloques de código. Markdown permite este patrón, pero puede ser problemático y debe evitarse.

Un bloque de código es una o varias líneas de código delimitadas por una triple comilla invertida (```). Los marcadores de barrera de código deben estar en su propia línea antes y después del ejemplo de código. El marcador de apertura puede tener una etiqueta de idioma opcional. La etiqueta de idioma habilita el resaltado de sintaxis en la página web representada.

Para obtener una lista completa de las etiquetas de idioma admitidas, consulte Bloques de código cercados en la guía de colaborador centralizado.

La publicación también agrega un botón Copiar que puede copiar el contenido del bloque de código en el Portapapeles. Esto le permite pegar el código en un script para probar el ejemplo de código. Sin embargo, no todos los ejemplos están diseñados para ejecutarse como escritos. Algunos bloques de código son ilustraciones básicas de los conceptos de PowerShell.

En nuestra documentación se usan tres tipos de bloques de código:

  1. Bloques de sintaxis
  2. Ejemplos ilustrativos
  3. Ejemplos ejecutables

Bloques de código de sintaxis

Los bloques de código de sintaxis se usan para describir la estructura sintáctica de un comando. No use una etiqueta de idioma en la barrera de código. En este ejemplo se muestran todos los parámetros posibles del Get-Command cmdlet.

```
Get-Command [-Verb <String[]>] [-Noun <String[]>] [-Module <String[]>]
  [-FullyQualifiedModule <ModuleSpecification[]>] [-TotalCount <Int32>] [-Syntax]
  [-ShowCommandInfo] [[-ArgumentList] <Object[]>] [-All] [-ListImported]
  [-ParameterName <String[]>] [-ParameterType <PSTypeName[]>] [<CommonParameters>]
```

En este ejemplo se describe la for instrucción en términos generalizados:

```
for (<init>; <condition>; <repeat>)
{<statement list>}
```

Ejemplos ilustrativos

Se usan ejemplos ilustrativos para explicar un concepto de PowerShell. Yo'u debe evitar el uso de mensajes de PowerShell en ejemplos siempre que sea posible. Sin embargo, los ejemplos ilustrativos no están diseñados para copiarse y pegarse para su ejecución. Se usan con más frecuencia para ejemplos sencillos que son fáciles de entender. Puede incluir el símbolo del sistema de PowerShell y la salida de ejemplo.

Este es un ejemplo sencillo que ilustra los operadores de comparación de PowerShell. En este caso, no pretendemos que el lector copie y ejecute este ejemplo. Tenga en cuenta que en este ejemplo se usa PS> como una cadena de solicitud simplificada.

```powershell
PS> 2 -eq 2
True

PS> 2 -eq 3
False

PS> 1,2,3 -eq 2
2

PS> "abc" -eq "abc"
True

PS> "abc" -eq "abc", "def"
False

PS> "abc", "def" -eq "abc"
abc
```

Ejemplos ejecutables

Ejemplos complejos, o ejemplos que están diseñados para copiarse y ejecutarse, deben usar el siguiente marcado de estilo de bloque:

```powershell
<Your PowerShell code goes here>
```

La salida mostrada por los comandos de PowerShell debe incluirse en un bloque de código de salida para evitar el resaltado de sintaxis. Por ejemplo:

```powershell
Get-Command -Module Microsoft.PowerShell.Security
```

```Output
CommandType  Name                        Version    Source
-----------  ----                        -------    ------
Cmdlet       ConvertFrom-SecureString    3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       ConvertTo-SecureString      3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-Acl                     3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-AuthenticodeSignature   3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-CmsMessage              3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-Credential              3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-ExecutionPolicy         3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-PfxCertificate          3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       New-FileCatalog             3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Protect-CmsMessage          3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-Acl                     3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-AuthenticodeSignature   3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-ExecutionPolicy         3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Test-FileCatalog            3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Unprotect-CmsMessage        3.0.0.0    Microsoft.PowerShell.Security
```

La Output etiqueta de código no es un lenguaje oficial compatible con el sistema de resaltado de sintaxis. Sin embargo, esta etiqueta es útil porque nuestro sistema de publicación agrega la etiqueta Salida al marco del cuadro de código de la página web. El cuadro Código de salida no tiene ningún resaltado de sintaxis.

Reglas de estilo de codificación

Evitar la continuación de línea en ejemplos de código

Evite usar caracteres de continuación de línea (`) en ejemplos de código de PowerShell. Los caracteres de comillas invertidas son difíciles de ver y pueden causar problemas si hay espacios adicionales al final de la línea.

  • Use PowerShell splatting para reducir la longitud de línea de los cmdlets que tienen varios parámetros.
  • Aproveche las oportunidades de salto de línea natural de PowerShell, como después de los caracteres de canalización (|), las llaves de apertura ({), los paréntesis (() y los corchetes ([).

Evitar el uso de mensajes de PowerShell en ejemplos

No se recomienda el uso de la cadena de solicitud y debe limitarse a escenarios diseñados para ilustrar el uso de la línea de comandos. Para la mayoría de estos ejemplos, la cadena de solicitud debe ser PS>. Este mensaje es independiente de los indicadores específicos del sistema operativo.

Las indicaciones son necesarias en ejemplos para ilustrar comandos que modifican el indicador o cuando la ruta mostrada es significativa para el escenario. En el ejemplo siguiente se muestra cómo cambia el indicador al usar el proveedor de Registro.

PS C:\> cd HKCU:\System\
PS HKCU:\System\> dir

    Hive: HKEY_CURRENT_USER\System

Name                   Property
----                   --------
CurrentControlSet
GameConfigStore        GameDVR_Enabled                       : 1
                       GameDVR_FSEBehaviorMode               : 2
                       Win32_AutoGameModeDefaultProfile      : {2, 0, 1, 0...}
                       Win32_GameModeRelatedProcesses        : {1, 0, 1, 0...}
                       GameDVR_HonorUserFSEBehaviorMode      : 0
                       GameDVR_DXGIHonorFSEWindowsCompatible : 0

No usar alias en ejemplos

Utiliza el nombre completo de todos los cmdlets y parámetros, a menos que se esté documentando específicamente el alias. Los nombres de cmdlet y de parámetro deben usar los nombres con formato Pascal adecuados.

Uso de parámetros en ejemplos

Evite usar parámetros posicionales. Para reducir la posibilidad de confusión, debe incluir el nombre del parámetro en un ejemplo, incluso si el parámetro es posicional.

Artículos de referencia sobre la formateación de cmdlets

Los artículos de referencia de cmdlets tienen una estructura específica. PlatyPS define esta estructura. PlatyPS es una herramienta que genera la documentación de ayuda para los cmdlets de los módulos de PowerShell en formato Markdown. Después de editar los archivos Markdown, PlatyPS puede crear los archivos de ayuda MAML usados por el cmdlet Get-Help.

PlatyPS tiene un esquema que espera una estructura específica para la referencia del cmdlet. En el documento de esquema PlatyPS se describe esta estructura. Las infracciones de esquema provocan errores de compilación que deben corregirse antes de que podamos aceptar su contribución.

  • No quite ninguna de las estructuras de encabezado ATX. PlatyPS espera un conjunto específico de encabezados en un orden específico.
  • Los encabezados H2 INPUTS y OUTPUTS deben tener un tipo H3. Si el cmdlet no toma datos o devuelve un valor, use el valor None para H3.
  • Los fragmentos de código en línea se pueden usar en cualquier párrafo.
  • Los bloques de código cercados solo se permiten en la sección EJEMPLOS .

En el esquema PlatyPS, EXAMPLES es un encabezado H2. Cada ejemplo es un encabezado H3. En un ejemplo, el esquema no permite que los bloques de código estén separados por párrafos. El esquema solo permite la estructura siguiente:

### Example X - Title sentence

0 or more paragraphs
1 or more code blocks
0 or more paragraphs.

Numera cada ejemplo y agrega un breve título.

Por ejemplo:

### Example 1: Get cmdlets, functions, and aliases

This command gets the PowerShell cmdlets, functions, and aliases that are installed on the
computer.

```powershell
Get-Command
```

### Example 2: Get commands in the current session

```powershell
Get-Command -ListImported
```

Aplicación de formato a archivos About_

About_* los archivos se escriben en Markdown, pero se envían como archivos de texto sin formato. Usamos Pandoc para convertir Markdown en texto sin formato. About_* los archivos están formateados para la mejor compatibilidad en todas las versiones de PowerShell y con las herramientas de publicación.

Directrices básicas de formato:

  • Limitar líneas de párrafo a 80 caracteres

  • Limitar los bloques de código a 76 caracteres

  • Limitar las comillas de bloque y las alertas a 78 caracteres

  • Al usar estos meta-caracteres especiales \, $ y <:

    • Dentro de un encabezado, estos caracteres se deben escapar mediante un carácter inicial \ o entre intervalos de código mediante comillas invertidas (`)

    • Dentro de un párrafo, estos caracteres deben colocarse en intervalos de código. Por ejemplo:

      ### The purpose of the \$foo variable

The `$foo` variable is used to store ...

  • Tablas de Markdown

    • En el caso About_* de los artículos, las tablas deben caber en 76 caracteres.
      • Si el contenido no se ajusta a un límite de 76 caracteres, use listas de viñetas en su lugar.
    • Usar caracteres de apertura y cierre | en cada línea

Pasos siguientes

Lista de comprobación editorial