Compartilhar via

Guia de estilo do PowerShell no Docs

Este artigo fornece diretrizes de estilo específicas para o conteúdo do PowerShell-Docs. Ele se baseia nas informações descritas na Visão Geral.

Formatar elementos de sintaxe de comando

Use as regras a seguir para formatar elementos da linguagem do PowerShell quando os elementos são usados em uma frase.

  • Sempre use o nome completo para cmdlets e parâmetros na notação Pascal adequada

  • Use apenas um alias 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 usando texto em negrito :

    • Nomes de tipo

    • Nomes de classe

    • Nomes de propriedade

    • Nomes de parâmetro

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

      Por exemplo:

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

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

    • Valores de propriedade e parâmetros

    • Nomes de tipo que usam o estilo entre colchetes – por exemplo: [System.Io.FileInfo]

    • Referindo-se a personagens por nome. Por exemplo: use o caractere asterisco (*) como curinga.

    • Palavras-chave e operadores de linguagem

    • 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 de comando embutida:

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

      A inclusão da 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

O Markdown dá suporte a dois estilos de código diferentes:

  • Intervalos de código (em linha) - marcados por um único símbolo backtick (`). Usado em um parágrafo em vez de como um bloco autônomo.
  • Blocos de código – um bloco de várias linhas envolvido por cadeias de triplo backtick (```). Os blocos de código também podem ter um rótulo de idioma após os backticks. O rótulo de idioma habilita 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 esse padrão, mas pode ser problemático e deve ser evitado.

Um bloco de código consiste em uma ou mais linhas de código delimitadas por um cercado 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 habilita o realce de sintaxe na página da Web renderizada.

Para obter uma lista completa de marcas de idioma com suporte, consulte blocos de código cercados no guia do colaborador centralizado.

A publicação também adiciona um botão Copiar que pode copiar o conteúdo do bloco de código para a área de transferência. 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.

Há 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 sintactica 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 declaração em termos generalizados.

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

Exemplos ilustrativos

Exemplos ilustrativos são usados para explicar um conceito do PowerShell. Yo'u deve evitar o uso de 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 ilustrando os operadores de comparação do PowerShell. Nesse 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 devem 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 colocada em um bloco de código de saída para impedir 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 compatível com o 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 de código de saída não tem destaque de sintaxe.

Regras de estilo de codificação

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

Evite usar caracteres de continuação de linha (`) nos exemplos de código do PowerShell. 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 reduzir o comprimento da linha para cmdlets que têm vários parâmetros.
  • Aproveite as oportunidades de quebra de linha naturais do PowerShell, como caracteres após o 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 parâmetro devem usar os nomes com Pascal Case.

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.

Artigos de referência sobre cmdlets de formatação

Os artigos de referência do cmdlet têm uma estrutura específica. PlatyPS define essa estrutura. O PlatyPS gera a ajuda do cmdlet para 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.

O PlatyPS tem um esquema que espera uma estrutura específica para a referência de cmdlet. O documento do esquema PlatyPS descreve essa estrutura. As violações de esquema causam erros de build que devem ser corrigidos antes de aceitarmos 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 estar no formato H3. Se o cmdlet não receber entrada ou retornar um valor, use o valor None para o H3.
  • Trechos de código em linha podem ser usados em qualquer parágrafo.
  • Blocos de código cercados só são permitidos na seção EXAMPLES .

No esquema PlatyPS, EXAMPLES é um cabeçalho H2. Cada exemplo é um cabeçalho H3. Em um exemplo, o esquema não permite que 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.

Numerar cada exemplo e adicionar 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
```

Formatação de arquivos About_

About_* os arquivos são gravados no Markdown, mas são enviados como arquivos de texto sem formatação. Usamos o Pandoc para converter o Markdown em texto sem formatação. About_* os arquivos são formatados para obter 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 blocos de citação 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 entre intervalos de código usando backticks (`)

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

      ### The purpose of the \$foo variable

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

  • Tabelas markdown

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

Próximas etapas

Lista de verificação editorial

  • Last updated on