Condividi tramite

informazioni_sui_commenti

  • Articolo

Breve descrizione

Descrive come usare i commenti di PowerShell ed elenca casi d'uso speciali.

Descrizione lunga

È possibile scrivere commenti per annotare o strutturare il codice di PowerShell per facilitare la leggibilità. Quando il codice viene eseguito, il testo del commento viene ignorato da PowerShell.

I commenti forniscono contesto importante ai lettori del codice. È consigliabile usare i commenti per gli scopi seguenti:

  • Spiegare codice complesso in termini più semplici
  • Spiegare perché è stato scelto un approccio specifico
  • Casi limite dei documenti da considerare
  • Fornire collegamenti al materiale di riferimento di supporto

Alcuni commenti hanno un significato speciale in PowerShell. Vedere Commenti speciali.

Stili di commento di PowerShell

PowerShell supporta due stili di commento:

  • i commenti a riga singola iniziano con il carattere hash (#) e terminano con una nuova riga. Il # può essere preceduto da testo che non fa parte del commento, incluso lo spazio vuoto. I commenti a riga singola posizionati sulla stessa riga del codice sorgente non commentato sono noti come commenti di fine riga.

  • Commenti di blocco iniziano con <# e terminano con #>. Un commento a blocchi può estendersi su un numero qualsiasi di righe e può essere incluso prima, dopo o al centro del codice sorgente non commentato. Tutto il testo all'interno del blocco viene considerato come parte dello stesso commento, incluso lo spazio vuoto.

    Importante

    È possibile includere commenti a riga singola all'interno di un commento a blocchi. Tuttavia, non è possibile annidare i commenti di blocco. Se si tenta di annidare i commenti di blocco, il commento di blocco esterno termina al primo #> rilevato.

Esempi

Esempio 1: commento a riga singola

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

Esempio 2: Blocco commento

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

Esempio 3: Commento di fine riga

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

Esempio 4: Commento in linea di blocco

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

Esempio 5: Esempio 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
)

Commenti speciali

PowerShell include diverse parole chiave di commento per supportare usi specifici.

Guida basata sui commenti

È possibile scrivere contenuto della guida basato su commenti per le funzioni e gli script utilizzando commenti su singola riga o blocchi. Gli utenti possono usare il cmdlet Get-Help per visualizzare la Guida basata su commenti per una funzione o uno script. PowerShell definisce 15 parole chiave di commento che possono essere usate per fornire informazioni quali la descrizione e l'utilizzo di esempio.

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

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

Per altre informazioni, vedere:

#Requires

L'istruzione #Requires impedisce l'esecuzione di uno script a meno che la sessione di PowerShell corrente non soddisfi i prerequisiti specificati. #Requires può essere visualizzato in qualsiasi riga di uno script, ma viene elaborato nello stesso modo indipendentemente dalla posizione.

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

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

Per altre informazioni, vedere about_Requires.

Blocco di firme

Gli script possono essere firmati in modo che siano conformi ai criteri di esecuzione di PowerShell. Una volta firmato, alla fine di uno script viene aggiunto un blocco di firma. Questo blocco ha la forma di più commenti a riga singola, letti da PowerShell prima dell'esecuzione dello script.

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

Per altre informazioni, vedere about_signing.

Baracca

Nei sistemi simili a Unix, un shebang (#!) è una direttiva usata all'inizio di uno script per indicare quale shell deve essere usata per eseguire lo script. Shebang non fa parte del linguaggio di PowerShell. PowerShell lo interpreta come un commento normale. Shebang viene interpretato dal sistema operativo.

Nell'esempio seguente, shebang garantisce che PowerShell esegua lo script quando lo script viene richiamato da un contesto non PowerShell.

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

Marcatori dell'area dell'editor di codice

Alcuni editor di codice supportano marcatori di area che consentono di comprimere ed espandere sezioni di codice. Per PowerShell, i marcatori di area sono commenti che iniziano con #region e terminano con #endregion. Gli indicatori di area devono trovarsi all'inizio di una linea. I marcatori di area sono supportati in PowerShell ISE e in Visual Studio Code con l'estensione PowerShell. I marcatori di area non fanno parte del linguaggio di PowerShell. PowerShell li interpreta come commenti regolari.

Per altre informazioni, vedere la sezione della Modifica di base in Visual Studio Code documentazione.

Commenti nella stringa di token

e non hanno un significato speciale all'interno di un espandibile o stringa verbatim. PowerShell interpreta letteralmente i caratteri.

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.

Tuttavia, alcune funzionalità di PowerShell sono progettate per funzionare con stringhe che contengono commenti. L'interpretazione del commento dipende dalla caratteristica specifica.

Commenti di espressioni regolari

Le espressioni regolari (regex) in PowerShell usano il motore di regex .NET , che supporta due stili di commento.

  • Commento in linea ((?#))
  • Commento di fine riga (#)

I commenti regex sono supportati da tutte le funzionalità basate su regex in PowerShell. Per esempio:

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

Un commento regex di fine riga richiede il costrutto (?x) o l'opzione IgnorePatternWhitespace.

Per altre informazioni, vedere:

Commenti JSON

A partire da PowerShell 6.0, il cmdlet ConvertFrom-Json supporta gli stili di commento JSON seguenti:

  • Commento a riga singola (//)
  • Blocca commento (/* */)

Nota

Il cmdlet Invoke-RestMethod deserializza automaticamente i dati JSON ricevuti. In PowerShell 6.0 in poi, i commenti sono consentiti nei dati JSON.

Per esempio:

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

Foo
---
Bar

Avvertimento

A partire da PowerShell 7.4, il cmdlet test-json non supporta più JSON con commenti. Se il codice JSON include commenti, viene restituito un errore. Nelle versioni supportate precedenti alla 7.4, Test-Json analizza correttamente JSON con commenti. In PowerShell 7.5 Test-Json include un'opzione per ignorare i commenti JSON.

Commenti CSV

Import-Csv e ConvertFrom-Csv supportano il formato di log esteso W3C. Le righe che iniziano con il carattere hash (#) vengono considerate come commenti e ignorate, a meno che il commento non inizi con #Fields: e contenga un elenco delimitato di nomi di colonna. In tal caso, il cmdlet usa questi nomi di colonna. Questo è il formato standard per Windows IIS e altri log del server Web. Per altre informazioni, vedere formato di file di log esteso.

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

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

In Windows PowerShell 5.1 il comportamento predefinito Export-Csv e ConvertTo-Csv consiste nell'includere informazioni sul tipo sotto forma di commento #TYPE. A partire da PowerShell 6.0, il valore predefinito è di non includere il commento, ma può essere modificato con il parametro IncludeTypeInformation.

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

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

Quando un commento #TYPE è incluso nei dati CSV, Import-Csv e ConvertFrom-Csv usano queste informazioni per impostare la proprietà pstypenames degli oggetti deserializzati.

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

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

Test
CSV:Test

ConvertFrom-StringData commenti

Nei dati di stringa, il cmdlet ConvertFrom-StringData considera le righe che iniziano con # come commenti. Per altre informazioni, vedere:

Note

  • I commenti di blocco non possono essere annidati. Nell'esempio seguente Baz non fa parte del commento.

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

  • <# #> non ha alcun significato speciale all'interno di un commento a riga singola. # non ha alcun significato speciale all'interno di un commento a blocco.

  • Per essere considerato come commento, il carattere di commento non deve far parte di un token non di commento. Nell'esempio seguente #Bar e <#Bar#> fanno parte del token di Foo.... Pertanto, non vengono trattati come commenti.

    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 [...]