Compartilhar via

about_Comments

  • Artigo

Descrição curta

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 aos leitores do código. Você deve usar comentários para as seguintes finalidades:

  • Explicar código complexo em termos mais simples
  • Explicar por que uma abordagem específica foi escolhida
  • Casos extremos de documentos a serem considerados
  • Fornecer links para o material de referência de suporte

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

Estilos de comentário do PowerShell

O PowerShell dá 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. Os 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.

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

    Importante

    Você pode incluir comentários de linha única em um comentário em bloco. Porém, não é possível aninhar comentários de bloco. Se você tentar aninhar comentários de bloco, os comentários de bloco externos finalizarão 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
)

Comentários 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 em linha única ou em bloco. Os usuários podem usar o cmdlet Get-Help para exibir 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 obter 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 em 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 saber mais, 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 de o script ser executado.

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

Para obter mais informações, consulte about_signing.

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 do PowerShell. O PowerShell o interpreta como um comentário regular. O Shebang é interpretado pelo sistema operacional.

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 marcadores de região que permitem recolher e expandir seçõ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 têm suporte no ISE do PowerShell e no Visual Studio Code com a extensão do PowerShell. Os marcadores de região não fazem parte do idioma do PowerShell. O PowerShell os interpreta como comentários regulares.

Para obter mais informações, consulte a seção Dobramento da documentação Edição básica no Visual Studio Code.

Comentários em tokens de cadeias de caracteres

# e <# #> não têm um significado especial em uma cadeia de caracteres expansível ou textual. 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, determinados recursos do PowerShell foram projetados para funcionar com cadeias de caracteres que contêm comentários. A interpretação do comentário depende do recurso específico.

Comentários em expressões regulares

As expressões regulares (regex) no PowerShell usam o mecanismo .NET Regex, que é compatível com dois estilos de comentário:

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

Os comentários do Regex são compatíveis com 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

Nota

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

Para obter mais informações, consulte:

comentários JSON

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

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

Nota

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

Por exemplo:

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

Foo
---
Bar

Aviso

A partir do PowerShell 7.4, o cmdlet Test-Json não dá mais suporte a JSON com comentários. Um erro será retornado se o JSON incluir comentários. Em versões com suporte anteriores à 7.4, Test-Json analisa com êxito o 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 são compatíveis com o formato de arquivo de log estendido W3C. As linhas que começam com o caractere 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 coluna. Nesse caso, o cmdlet usa esses nomes de coluna. Esse é o formato padrão para o Windows IIS e outros logs de servidor Web. Para obter mais informações, consulte o formato de arquivo de log estendido .

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

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

No Windows PowerShell 5.1, o comportamento padrão de Export-Csv e ConvertTo-Csv é a inclusão de informações de tipo em forma de comentário #TYPE. A partir do PowerShell 6.0, o padrã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 dos objetos desserializados.

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

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

Test
CSV:Test

Comentários ConvertFrom-StringData

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

Anotações

  • 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 em um comentário de linha única. # não tem nenhum significado especial em um comentário em bloco.

  • Para ser tratado como um comentário, o caractere de comentário não deve fazer parte de um token sem comentários. 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 [...]