Partilhar via

sobre_Comentários

  • Artigo

Breve descrição

Descreve como usar comentários do PowerShell e lista casos de uso especiais.

Descrição longa

Você pode escrever comentários para anotar ou estruturar seu código do PowerShell para ajudar na legibilidade. Quando o código é executado, o texto do comentário é ignorado pelo PowerShell.

Os comentários fornecem contexto importante para os leitores do código. Você deve usar os comentários para os seguintes fins:

  • Explicar código complexo em termos mais simples
  • Explicar por que razão foi escolhida uma determinada abordagem
  • Documente casos extremos a ter em conta
  • Fornecer ligações para material de referência de apoio

Alguns comentários têm um significado especial no PowerShell. Ver Comentários especiais.

Estilos de comentário do PowerShell

O PowerShell oferece suporte a dois estilos de comentário:

  • Comentários de linha única começam com o caractere de hash (#) e terminam com uma nova linha. O # pode ser precedido por texto que não faz parte do comentário, incluindo espaço em branco. Comentários de linha única colocados na mesma linha que o código-fonte não comentado são conhecidos como comentários de fim de linha.

  • Bloquear comentários começar com <# e terminar com #>. Um comentário de bloco pode abranger qualquer número de linhas e pode ser incluído antes, depois ou no meio do código-fonte não comentado. Todo o texto dentro do bloco é tratado como parte do mesmo comentário, incluindo espaços em branco.

    Importante

    Você pode incluir comentários de linha única em um comentário de bloco. No entanto, não é possível aninhar comentários de bloco. Se você tentar aninhar comentários de bloco, o comentário de bloco externo termina no primeiro #> encontrado.

Exemplos

Exemplo 1: Comentário de linha única

# This is a single-line comment.
# This is also a single-line comment.

Exemplo 2: Bloquear comentário

<#
    This is a block comment.
    Text within the block is a part of the same comment.
Whitespace is unimportant in a block comment.
#>

Exemplo 3: Comentário de fim de linha

$var = 4 # This is an end-of-line comment

Exemplo 4: Comentário de bloco embutido

'Foo'; <# This is an inline block comment #> 'Bar'

Exemplo 5: Exemplo completo

<#
    .DESCRIPTION
    Demonstrates PowerShell's different comment styles.
#>
param (
    [string] $Param1, # End-of-line comment
    <# Inline block comment #> $Param2
)

$var = 1, <# Inline block comment #> 2, 2

# Single-line comment.
# Another single-line comment.
$var.Where(
    <# Arg1 note #> { $_ -eq 2 },
    <# Arg2 note #> 'First',
    <# Arg3 note #> 1
)

Observações especiais

O PowerShell inclui várias palavras-chave de comentário para dar suporte a usos específicos.

Ajuda baseada em comentários

Você pode escrever conteúdo de ajuda baseado em comentários para funções e scripts usando comentários de linha única ou de bloco. Os usuários podem usar o cmdlet Get-Help para exibir a ajuda baseada em comentários para uma função ou script. O PowerShell define 15 palavras-chave de comentário que podem ser usadas para fornecer informações como a descrição e o uso de exemplo.

<#
    .DESCRIPTION
    Comment-based help using a block comment.
#>
function Get-Function { }

# .DESCRIPTION
# Comment-based help using multiple single-line comments.
function Get-Function { }

Para mais informações, consulte:

#Requires

A instrução #Requires impede que um script seja executado, a menos que a sessão atual do PowerShell atenda aos pré-requisitos especificados. #Requires pode aparecer em qualquer linha de um script, mas é processado da mesma maneira, independentemente da posição.

#Requires -Modules AzureRM.Netcore
#Requires -Version 6.0

param (
    [Parameter(Mandatory)]
    [string[]] $Path
)

Para obter mais informações, consulte about_Requires.

Bloco de assinatura

Os scripts podem ser assinados para que estejam em conformidade com as políticas de execução do PowerShell. Uma vez assinado, um bloco de assinatura é adicionado ao final de um script. Esse bloco assume a forma de vários comentários de linha única, que são lidos pelo PowerShell antes que o script seja executado.

# SIG # Begin signature block
# ...
# SIG # End signature block

Para obter mais informações, consulte sobre_assinatura.

Shebang

Em sistemas semelhantes ao Unix, um shebang (#!) é uma diretiva usada no início de um script para indicar qual shell deve ser usado para executar o script. Shebang não faz parte da linguagem PowerShell. O PowerShell interpreta-o como um comentário regular. Shebang é interpretado pelo sistema operativo.

No exemplo a seguir, o shebang garante que o PowerShell execute o script quando o script é invocado de um contexto que não seja do PowerShell.

#!/usr/bin/env pwsh
Write-Host 'Begin script'

Marcadores de região do editor de código

Alguns editores de código suportam delimitadores de região que permitem-lhe recolher e expandir secções de código. Para o PowerShell, os marcadores de região são comentários que começam com #region e terminam com #endregion. Os marcadores de região devem estar no início de uma linha. Os marcadores de região são suportados no ISE do PowerShell e no Visual Studio Code com a extensão do PowerShell. Os marcadores de região não fazem parte da linguagem do PowerShell. O PowerShell os interpreta como comentários regulares.

Para obter mais informações, consulte a seção Folding da edição básica na documentação do Visual Studio Code.

Comentários em tokens de cadeia de caracteres

# e <# #> não têm significado especial dentro de um expansível ou string literal . O PowerShell interpreta os caracteres literalmente.

PS> '# This is not interpreted as a comment.'
# This is not interpreted as a comment.

PS> "This is <# also not interpreted #> as a comment."
This is <# also not interpreted #> as a comment.

No entanto, alguns recursos do PowerShell são projetados para trabalhar com cadeias de caracteres que contêm comentários. A interpretação do comentário depende da característica específica.

Comentários sobre expressões regulares

As expressões regulares (regex) no PowerShell usam o motor de regex .NET , que oferece suporte a dois estilos de comentário:

  • Comentário embutido ((?#))
  • Comentário de fim de linha (#)

Os comentários Regex são suportados por todos os recursos baseados em regex no PowerShell. Por exemplo:

PS> 'book' -match '(?# This is an inline comment)oo'
True

PS> 'book' -match '(?x)oo# This is an end-of-line comment'
True

PS> $regex = 'oo # This is an end-of-line comment'
PS> 'book' -split $regex, 0, 'IgnorePatternWhitespace'
b
k

Observação

Um comentário regex de fim de linha requer a estrutura (?x) ou a opção IgnorePatternWhitespace.

Para mais informações, consulte:

Comentários JSON

A partir do PowerShell 6.0, o cmdlet ConvertFrom-Json oferece suporte aos seguintes estilos de comentário JSON:

  • Comentário de linha única (//)
  • Bloquear comentário (/* */)

Observação

O cmdlet Invoke-RestMethod desserializa automaticamente os dados JSON recebidos. No PowerShell 6.0 em diante, comentários são permitidos nos dados JSON.

Por exemplo:

'{
    "Foo": "Bar" // This is a single-line comment
}' | ConvertFrom-Json

Foo
---
Bar

Advertência

A partir do PowerShell 7.4, o cmdlet Test-Json não suporta mais JSON com comentários. Um erro será retornado se o JSON incluir comentários. Em versões suportadas anteriores à 7.4, Test-Json analisa JSON com comentários. No PowerShell 7.5, Test-Json inclui uma opção para ignorar comentários JSON.

Comentários CSV

Import-Csv e ConvertFrom-Csv suportam o formato W3C Extended Log. As linhas que começam com o caractere de hash (#) são tratadas como comentários e ignoradas, a menos que o comentário comece com #Fields: e contenha uma lista delimitada de nomes de colunas. Nesse caso, o cmdlet usa esses nomes de coluna. Este é o formato padrão para o Windows IIS e outros logs do servidor Web. Para obter mais informações, consulte Extended Log File Format.

@'
# This is a CSV comment
Col1,Col2
Val1,Val2
'@ | ConvertFrom-Csv

Col1 Col2
---- ----
Val1 Val2

No Windows PowerShell 5.1, o padrão Export-Csv e comportamento de ConvertTo-Csv é incluir informações de tipo na forma de um comentário . A partir do PowerShell 6.0, a predefinição não é incluir o comentário, mas isso pode ser substituído pelo parâmetro IncludeTypeInformation.

[pscustomobject] @{ Foo = 'Bar' } | ConvertTo-Csv -IncludeTypeInformation

#TYPE System.Management.Automation.PSCustomObject
"Foo"
"Bar"

Quando um comentário #TYPE é incluído em dados CSV, Import-Csv e ConvertFrom-Csv usam essas informações para definir a propriedade pstypenames do(s) objeto(s) desserializado(s).

class Test { $Foo = 'Bar' }
$test = [Test]::new()

$var = $test | ConvertTo-Csv -IncludeTypeInformation | ConvertFrom-Csv
$var.pstypenames

Test
CSV:Test

ConvertFrom-StringData comentários

Em seus dados de cadeia de caracteres, o cmdlet ConvertFrom-StringData trata linhas que começam com # como comentários. Para mais informações, consulte:

Observações

  • Os comentários de bloco não podem ser aninhados. No exemplo a seguir, Baz não faz parte do comentário.

    <#
'Foo'
<# 'Bar' #>
'Baz'
#>

  • <# #> não tem nenhum significado especial dentro de um comentário de linha única. # não tem nenhum significado especial dentro de um comentário de bloco.

  • Para ser tratado como um comentário, o caractere de comentário não deve fazer parte de um token que não seja de comentário. No exemplo a seguir, #Bar e <#Bar#> fazem parte do token Foo.... Portanto, eles não são tratados como comentários.

    PS> Foo#Bar
Foo#Bar: The term 'Foo#Bar' is not recognized as a name [...]

PS> Foo<#Bar#>
Foo<#Bar#>: The term 'Foo<#Bar#>' is not recognized as a name [...]