Partilhar via

PowerShell-Docs style guide (Guia de estilo da Documentação do PowerShell)

Este artigo fornece orientações de estilo específicas para o conteúdo PowerShell-Docs. Baseia-se nas informações descritas na visão geral.

Formatando elementos de sintaxe de comando

Use as regras a seguir para formatar elementos da linguagem PowerShell quando os elementos forem usados em uma frase.

  • Sempre use o nome completo para cmdlets e parâmetros no caso Pascal adequado

  • Use um alias apenas quando estiver demonstrando especificamente o alias

  • As palavras-chave e os operadores do PowerShell devem ser todos minúsculos

  • Os seguintes itens devem ser formatados em negrito :

    • Tipos de nomes

    • Nomes de classe

    • Nomes de propriedade

    • Nomes de parâmetros

      • Por padrão, use o parâmetro sem o prefixo do hífen.
      • Use o nome do parâmetro com o hífen se estiver ilustrando a sintaxe. Envolva o parâmetro em backticks.

      Por exemplo:

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

  • Os seguintes itens devem ser formatados usando backticks (`):

    • Valores de propriedades e parâmetros

    • Digite nomes que usam o estilo entre colchetes - Por exemplo: [System.Io.FileInfo]

    • Referindo-se a personagens pelo nome. Por exemplo: Use o caractere de asterisco (*) como curinga.

    • Palavras-chave e operadores linguísticos

    • Nomes de cmdlet, função e script

    • Aliases de comando e parâmetro

    • Nomes de método - Por exemplo: O ToString() método retorna uma representação de cadeia de caracteres do objeto

    • Variáveis

    • Comandos nativos

    • Caminhos de arquivo e diretório

    • Exemplos de sintaxe de comando embutido - Consulte Markdown para obter exemplos de código

      Este exemplo mostra alguns exemplos de backtick:

      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 exemplo mostra a sintaxe do comando embutida:

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

      Incluir a extensão de arquivo garante que o comando correto seja executado de acordo com a precedência de comando do PowerShell.

Markdown para exemplos de código

Markdown suporta dois estilos de código diferentes:

  • Segmentos de código (embutidos) - marcados por um único caractere de acentuador invertido (`). Usado dentro de um parágrafo em vez de como um bloco autônomo.
  • Blocos de código - um bloco de várias linhas cercado por cadeias de caracteres triple-backtick (```). Os blocos de código também podem ter um rótulo de idioma seguindo os backticks. O rótulo de idioma permite o realce de sintaxe para o conteúdo do bloco de código.

Todos os blocos de código devem estar contidos em uma cerca de código. Nunca use recuo para blocos de código. Markdown permite este padrão, mas pode ser problemático e deve ser evitado.

Um bloco de código é uma ou mais linhas de código cercadas por uma cerca de código triplo backtick (```). Os marcadores de cerca de código devem estar em sua própria linha antes e depois do exemplo de código. O marcador de abertura pode ter um rótulo de idioma opcional. O rótulo de idioma permite o realce de sintaxe na página da Web renderizada.

Para obter uma lista completa das tags de idioma suportadas, consulte Blocos de código vedados no guia do colaborador centralizado.

A publicação também adiciona um botão Copiar que pode copiar para a área de transferência o conteúdo do bloco de código. Isso permite que você cole o código em um script para testar o exemplo de código. No entanto, nem todos os exemplos devem ser executados como escritos. Alguns blocos de código são ilustrações básicas dos conceitos do PowerShell.

Existem três tipos de blocos de código usados em nossa documentação:

  1. Blocos de sintaxe
  2. Exemplos ilustrativos
  3. Exemplos executáveis

Blocos de código de sintaxe

Os blocos de código de sintaxe são usados para descrever a estrutura sintática de um comando. Não use uma marca de idioma na cerca de código. Este exemplo ilustra todos os parâmetros possíveis do 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>]
```

Este exemplo descreve a for instrução em termos generalizados:

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

Exemplos ilustrativos

Exemplos ilustrativos são usados para explicar um conceito do PowerShell. Você deve evitar usar prompts do PowerShell em exemplos sempre que possível. No entanto, exemplos ilustrativos não devem ser copiados e colados para execução. Eles são mais comumente usados para exemplos simples que são fáceis de entender. Você pode incluir o prompt do PowerShell e a saída de exemplo.

Aqui está um exemplo simples que ilustra os operadores de comparação do PowerShell. Neste caso, não pretendemos que o leitor copie e execute este exemplo. Observe que este exemplo usa PS> como uma cadeia de caracteres de prompt 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
```

Exemplos executáveis

Exemplos complexos, ou exemplos que se destinam a ser copiados e executados, devem usar a seguinte marcação de estilo de bloco:

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

A saída exibida pelos comandos do PowerShell deve ser incluída em um bloco de código de saída para evitar o realce da sintaxe. Por exemplo:

```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
```

O Output rótulo de código não é um idioma oficial suportado pelo sistema de realce de sintaxe. No entanto, esse rótulo é útil porque nosso sistema de publicação adiciona o rótulo de saída ao quadro da caixa de código na página da Web. A caixa Código de saída não tem realce de sintaxe.

Regras de estilo de codificação

Evitar a continuação da linha em exemplos de código

Evite usar caracteres de continuação de linha (`) em exemplos de código do PowerShell. Os caracteres de backtick são difíceis de ver e podem causar problemas se houver espaços extras no final da linha.

  • Use o splatting do PowerShell para diminuir o comprimento das linhas em cmdlets com vários parâmetros.
  • Aproveite as oportunidades naturais de quebra de linha do PowerShell, como caracteres after pipe (|), chaves de abertura ({), parênteses (() e colchetes ([).

Evite usar prompts do PowerShell em exemplos

O uso da cadeia de caracteres de prompt é desencorajado e deve ser limitado a cenários destinados a ilustrar o uso da linha de comando. Para a maioria desses exemplos, a cadeia de caracteres de prompt deve ser PS>. Esse prompt é independente de indicadores específicos do sistema operacional.

Os prompts são necessários em exemplos para ilustrar comandos que alteram o prompt ou quando o caminho exibido é significativo para o cenário. O exemplo a seguir ilustra como o prompt muda ao usar o provedor do 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

Não use aliases em exemplos

Use o nome completo de todos os cmdlets e parâmetros, a menos que você esteja documentando especificamente o alias. Os nomes de cmdlet e de parâmetro devem usar o formato PascalCase adequado.

Usando parâmetros em exemplos

Evite usar parâmetros posicionais. Para reduzir a chance de confusão, você deve incluir o nome do parâmetro em um exemplo, mesmo que o parâmetro seja posicional.

Formatando artigos de referência do cmdlet

Os artigos de referência de cmdlet têm uma estrutura específica. PlatyPS define esta estrutura. O PlatyPS gera a ajuda do cmdlet para os módulos do PowerShell em Markdown. Depois de editar os arquivos Markdown, o PlatyPS pode criar os arquivos de ajuda MAML usados pelo Get-Help cmdlet.

PlatyPS tem um esquema que requer uma estrutura específica para referência de cmdlet. O documento do esquema PlatyPS descreve essa estrutura. As violações de esquema causam erros de compilação que devem ser corrigidos antes que possamos aceitar sua contribuição.

  • Não remova nenhuma das estruturas de cabeçalho ATX. PlatyPS espera um conjunto específico de cabeçalhos em uma ordem específica.
  • Os cabeçalhos H2 INPUTS e OUTPUTS devem ter um tipo H3. Se o cmdlet não receber entrada ou retornar um valor, use o valor None para o H3.
  • As sequências de código em linha podem ser usadas em qualquer parágrafo.
  • Blocos de código cercados só são permitidos na seção EXEMPLOS .

No esquema PlatyPS, EXAMPLES é um cabeçalho H2. Cada exemplo é um cabeçalho H3. Em um exemplo, o esquema não permite que os blocos de código sejam separados por parágrafos. O esquema só permite a seguinte estrutura:

### Example X - Title sentence

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

Numere cada exemplo e adicione um breve título.

Por exemplo:

### 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
```

Formatando arquivos About_

About_* os arquivos são escritos em Markdown, mas são enviados como arquivos de texto simples. Usamos o Pandoc para converter o Markdown em texto simples. About_* os arquivos são formatados para a melhor compatibilidade em todas as versões do PowerShell e com as ferramentas de publicação.

Diretrizes básicas de formatação:

  • Limitar linhas de parágrafo a 80 caracteres

  • Limitar blocos de código a 76 caracteres

  • Limitar citações de blocos e alertas a 78 caracteres

  • Ao usar esses meta-caracteres especiais \, $, e <:

    • Dentro de um cabeçalho, esses caracteres devem ser escapados usando um caractere principal \ ou incluídos em extensões de código usando backticks (`)

    • Dentro de um parágrafo, esses caracteres devem ser colocados em trechos de código. Por exemplo:

      ### The purpose of the \$foo variable

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

  • Tabelas de Markdown

    • Para About_* artigos, as tabelas devem caber dentro de 76 caracteres
      • Se o conteúdo não couber dentro do limite de 76 caracteres, use listas de marcadores
    • Usar caracteres de abertura e fechamento | em cada linha

Próximos passos

Lista de verificação editorial

  • Last updated on