Guía de estilo de PowerShell-Docs
Este artículo proporciona orientación de estilo específica para el contenido de PowerShell-Docs. Se basa en la información descrita en la descripción general.
Formatear elementos de sintaxis de comando
Utilice las siguientes reglas para formatear elementos del lenguaje PowerShell cuando se usan en una oración.
Utilice siempre el nombre completo para cmdlets y parámetros en el caso Pascal adecuado
Utilice un alias únicamente cuando esté demostrando específicamente el alias
Las palabras clave y los operadores de PowerShell deben estar todos en minúsculas.
-
Los siguientes elementos deben tener formato de texto en negrita:
Escriba nombres
Nombres de clase
Nombres de propiedades
Nombres de parámetros
- De forma predeterminada, utilice el parámetro sin el prefijo de guión.
- Al ilustrar el uso de un parámetro con el prefijo de guión, el parámetro debe estar entre 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.
Los siguientes elementos deben formatearse utilizando comillas invertidas (`):
Valores de propiedades y parámetros
Escriba nombres que utilicen el estilo entre corchetes; por ejemplo: [System.Io.FileInfo]
Refiriéndose a los personajes por su nombre. Por ejemplo: utilice el carácter de asterisco (*) como comodín.
Palabras clave y operadores del idioma
Nombres de cmdlets, funciones y scripts
Alias de comandos y parámetros
Nombres de métodos: por ejemplo: el método ToString() devuelve una representación de cadena del objeto.
variables
Comandos nativos
Rutas de archivos y directorios
Ejemplos de sintaxis de comandos en línea: consulte Markdown para ver ejemplos de código
Este ejemplo muestra algunos ejemplos de comillas invertidas:
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
```
Este ejemplo muestra la sintaxis del comando en línea:
To start the spooler service on a remote computer named DC01, you type:
`sc.exe \\DC01 start spooler`.
Incluir la extensión de archivo garantiza que se ejecute el comando correcto de acuerdo con la precedencia de comandos de PowerShell.
Rebajas para ejemplos de código
Markdown admite dos estilos de código diferentes:
- El código abarca (en línea): marcado por un solo carácter de comilla invertida (
`). Se utiliza 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 idioma después de las comillas invertidas. La etiqueta de idioma permite resaltar la sintaxis del contenido del bloque de código.
Todos los bloques de código deben estar contenidos en una valla de código. Nunca utilice 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 más líneas de código rodeadas por una valla de código de triple comilla invertida (```). Los marcadores de valla 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 permite resaltar la sintaxis en la página web representada.
Para obtener una lista completa de las etiquetas de idiomas admitidas, consulte Bloques de código delimitados en la guía centralizada para colaboradores.
La publicación también agrega un botón Copiar que puede copiar el contenido del bloque de código al portapapeles. Esto le permite pegar el código en un script para probar el código de muestra. Sin embargo, no todos los ejemplos están pensados para ejecutarse tal como están escritos. Algunos bloques de código son ilustraciones básicas de conceptos de PowerShell.
Hay tres tipos de bloques de código utilizados en nuestra documentación:
- Bloques de sintaxis
- Ejemplos ilustrativos
- Ejemplos ejecutables
Bloques de código de sintaxis
Los bloques de código de sintaxis se utilizan para describir la estructura sintáctica de un comando. No utilice una etiqueta de idioma en la barrera del código. Este ejemplo ilustra todos los parámetros posibles del cmdlet Get-Command.
```
Get-Command [-Verb <String[]>] [-Noun <String[]>] [-Module <String[]>]
[-FullyQualifiedModule <ModuleSpecification[]>] [-TotalCount <Int32>] [-Syntax]
[-ShowCommandInfo] [[-ArgumentList] <Object[]>] [-All] [-ListImported]
[-ParameterName <String[]>] [-ParameterType <PSTypeName[]>] [<CommonParameters>]
```
Este ejemplo describe la declaración for en términos generalizados:
```
for (<init>; <condition>; <repeat>)
{<statement list>}
```
Ejemplos ilustrativos
Se utilizan ejemplos ilustrativos para explicar un concepto de PowerShell. En general, debe evitar el uso de indicaciones de PowerShell en los ejemplos. Sin embargo, los ejemplos ilustrativos no deben copiarse y pegarse para su ejecución. Se utilizan más comúnmente para ejemplos simples que son fáciles de entender. El bloque de código puede incluir el mensaje de PowerShell y un resultado de ejemplo.
A continuación se muestra 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 este ejemplo utiliza PS> como una cadena de mensaje 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
Los ejemplos complejos, o los ejemplos que están destinados a ser copiados y ejecutados, deben utilizar el siguiente marcado de estilo de bloque:
```powershell
<Your PowerShell code goes here>
```
La salida que muestran los comandos de PowerShell debe estar encerrada en un bloque de código 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 etiqueta del código Salida no es un idioma oficial admitido por 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 en la página web. El cuadro de código Salida no tiene resaltado de sintaxis.
Reglas de estilo de codificación
Evite la continuación de línea en ejemplos de código
Evite el uso de caracteres de continuación de línea (`) en los ejemplos de código de PowerShell. Son difíciles de ver y pueden causar problemas si hay espacios adicionales al final de la línea.
- Utilice salpicaduras de PowerShell para reducir la longitud de la línea de los cmdlets que tienen varios parámetros.
- Aproveche las oportunidades naturales de salto de línea de PowerShell, como caracteres después de la barra vertical (
|), llaves de apertura ({), paréntesis (() y corchetes ([).
Evite el uso de indicaciones de PowerShell en ejemplos
Se desaconseja el uso de la cadena de solicitud y debe limitarse a escenarios destinados a ilustrar el uso de la línea de comandos. Para la mayoría de estos ejemplos, la cadena del mensaje debe ser PS>. Este mensaje es independiente de los indicadores específicos del sistema operativo.
Los mensajes son necesarios en los ejemplos para ilustrar los comandos que alteran el mensaje o cuando la ruta mostrada es importante para el escenario. El siguiente ejemplo ilustra cómo cambia el mensaje cuando se utiliza 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 utilice alias en los ejemplos
Utilice el nombre completo de todos los cmdlets y parámetros a menos que esté documentando específicamente el alias. Los nombres de cmdlets y parámetros deben utilizar los nombres adecuados en mayúsculas y minúsculas.
Usar parámetros en ejemplos
Evite el uso de parámetros posicionales. En general, siempre debes incluir el nombre del parámetro en un ejemplo, incluso si el parámetro es posicional. Esto reduce la posibilidad de confusión en sus ejemplos.
Formato de artículos de referencia de cmdlets
Los artículos de referencia de cmdlets tienen una estructura específica. Esta estructura está definida por PlatyPS. PlatyPS genera la ayuda del cmdlet para los módulos de PowerShell en Markdown. Después de editar los archivos Markdown, se utiliza PlatyPS para crear los archivos de ayuda MAML utilizados por el cmdlet Get-Help.
PlatyPS tiene un esquema que espera una estructura específica para la referencia de cmdlet. El documento de esquema PlatyPS describe esta estructura. Las infracciones del esquema provocan errores de compilación que deben corregirse antes de que podamos aceptar su contribución.
- No elimine ninguna de las estructuras de encabezado ATX. PlatyPS espera un conjunto específico de encabezados en un orden específico.
- Los encabezados INPUTS y OUTPUTS H2 deben ser de tipo H3. Si el cmdlet no recibe datos ni devuelve un valor, utilice el valor
Ningunopara H3. - Los intervalos de código en línea se pueden utilizar en cualquier párrafo.
- Los bloques de código delimitados solo se permiten en la sección EJEMPLOS.
En el esquema PlatyPS, EJEMPLOS 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 siguiente estructura:
### Example X - Title sentence
0 or more paragraphs
1 or more code blocks
0 or more paragraphs.
Numere cada ejemplo y agregue un título breve.
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
```
Formatear archivos About_
Los archivos About_* están escritos en Markdown pero se envían como archivos de texto sin formato. Usamos Pandoc para convertir Markdown a texto sin formato. Los archivos About_* están formateados para lograr la mejor compatibilidad entre todas las versiones de PowerShell y con las herramientas de publicación.
Pautas básicas de formato:
Limite las líneas de párrafo a 80 caracteres
Limite los bloques de código a 76 caracteres
Limite las citas en bloque y las alertas a 78 caracteres
Al utilizar estos metacaracteres especiales
\,$y<:Dentro de un encabezado, estos caracteres deben tener caracteres de escape usando un carácter
\inicial o encerrados en intervalos de código usando 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 rebajas
Para los temas
About_*, las tablas deben tener 76 caracteres como máximo.- Si el contenido no se ajusta al límite de 76 caracteres, utilice listas con viñetas en su lugar.
| de apertura y cierre en cada líneaPróximos pasos
Lista de verificación editorial