Dela via

om_kommentarer

  • Artikel

Kort beskrivning

Beskriver hur du använder PowerShell-kommentarer och visar särskilda användningsfall.

Lång beskrivning

Du kan skriva kommentarer för att kommentera eller strukturera din PowerShell-kod för att underlätta läsbarheten. När koden körs ignoreras kommentarstexten av PowerShell.

Kommentarer ger viktig kontext till läsare av koden. Du bör använda kommentarer i följande syfte:

  • Förklara komplex kod i enklare termer
  • Förklara varför en viss metod valdes
  • Dokumentera gränsfall att känna till
  • Ange länkar till stödreferensmaterial

Vissa kommentarer har särskild betydelse i PowerShell. Se Särskilda kommentarer.

PowerShell-kommentarsformat

PowerShell har stöd för två kommentarsformat:

  • kommentarer med en rad börja med hash-tecknet (#) och sluta med en ny rad. # kan föregås av text som inte är en del av kommentaren, inklusive blanksteg. Enradskommentarer som placeras på samma rad som okommenterad källkod kallas för kommentarer i slutet av raden.

  • Blockera kommentarer börja med <# och sluta med #>. En blockkommentare kan omfatta valfritt antal rader och kan inkluderas före, efter eller mitt i den okommenterade källkoden. All text i blocket behandlas som en del av samma kommentar, inklusive blanksteg.

    Viktig

    Du kan inkludera enradskommentarer i en blockkommentar. Du kan dock inte kapsla blockkommentarer. Om du försöker kapsla blockkommentarer slutar den yttre blockkommentaren vid den första #> som påträffas.

Exempel

Exempel 1: Kommentar med en rad

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

Exempel 2: Blockera kommentar

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

Exempel 3: Kommentar från radslut

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

Exempel 4: Infogad blockkommentering

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

Exempel 5: Fullständigt exempel

<#
    .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
)

Särskilda kommentarer

PowerShell innehåller flera kommentarsnyckelord som stöder specifika användningsområden.

Kommentarsbaserad hjälp

Du kan skriva kommentarsbaserat hjälpinnehåll för funktioner och skript med antingen enrads- eller blockkommentarer. Användare kan använda cmdleten Get-Help för att visa kommentarsbaserad hjälp för en funktion eller ett skript. PowerShell definierar 15 kommentarsnyckelord som kan användas för att ange information, till exempel beskrivning och exempelanvändning.

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

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

Mer information finns i:

#Requires

Instruktionen #Requires förhindrar att ett skript körs om inte den aktuella PowerShell-sessionen uppfyller de angivna kraven. #Requires kan visas på valfri rad i ett skript, men bearbetas på samma sätt oavsett position.

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

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

Mer information finns i about_Requires.

Signaturfält

Skript kan signeras så att de följer PowerShell-körningsprinciper. När det är signerat läggs ett signaturblock till i slutet av ett skript. Det här blocket består av flera enradskommentarer som läses av PowerShell innan skriptet körs.

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

Mer information finns i about_signing.

Shebang

På Unix-liknande system är ett shebang- (#!) ett direktiv som används i början av ett skript för att ange vilket gränssnitt som ska användas för att köra skriptet. Shebang är inte en del av PowerShell-språket. PowerShell tolkar det som en vanlig kommentar. Shebang tolkas av operativsystemet.

I följande exempel ser shebangen till att PowerShell kör skriptet när skriptet anropas från en icke-PowerShell-kontext.

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

Regionmarkörer för kodredigeraren

Vissa kodredigerare stöder regionmarkörer som gör att du kan komprimera och expandera kodavsnitt. För PowerShell är regionmarkörerna kommentarer som börjar med #region och slutar med #endregion. Regionmarkörerna måste vara i början av en rad. Regionmarkörerna stöds i PowerShell ISE och i Visual Studio Code med PowerShell-tillägget. Regionmarkörerna är inte en del av PowerShell-språket. PowerShell tolkar dem som vanliga kommentarer.

Mer information finns i avsnittet Folding i dokumentationen Basic-redigering i Visual Studio Code.

Kommentarer i strängtoken

# och <# #> har inte någon särskild betydelse i en expanderbar eller ordagrann sträng. PowerShell tolkar tecknen bokstavligen.

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.

Vissa PowerShell-funktioner är dock utformade för att fungera med strängar som innehåller kommentarer. Tolkningen av kommentaren är beroende av den specifika funktionen.

Kommentarer för reguljära uttryck

Reguljära uttryck (regex) i PowerShell använder motorn .NET regex, som stöder två kommentarsformat:

  • Kommentar i text ((?#))
  • Kommentar vid radslut (#)

Regex-kommentarer stöds av alla regex-baserade funktioner i PowerShell. Till exempel:

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

Not

En regexkommentar i slutet av raden kräver antingen (?x)-konstruktionen eller alternativet IgnorePatternWhitespace.

Mer information finns i:

JSON-kommentarer

Från och med PowerShell 6.0 stöder cmdleten ConvertFrom-Json följande JSON-kommentarsformat:

  • Kommentar med en rad (//)
  • Blockera kommentar (/* */)

Not

Cmdleten Invoke-RestMethod deserialiserar automatiskt mottagna JSON-data. I PowerShell 6.0 och senare tillåts kommentarer i JSON-data.

Till exempel:

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

Foo
---
Bar

Varning

Från och med PowerShell 7.4 stöder cmdleten Test-Json inte längre JSON med kommentarer. Ett fel returneras om JSON innehåller kommentarer. I versioner som stöds före 7.4 parsar Test-Json JSON med kommentarer. I PowerShell 7.5 innehåller Test-Json ett alternativ för att ignorera JSON-kommentarer.

CSV-kommentarer

Import-Csv och ConvertFrom-Csv har stöd för W3C Extended Log-formatet. Rader som börjar med hash-tecknet (#) behandlas som kommentarer och ignoreras om inte kommentaren börjar med #Fields: och innehåller avgränsad lista med kolumnnamn. I så fall använder cmdleten dessa kolumnnamn. Det här är standardformatet för Windows IIS och andra webbserverloggar. Mer information finns i utökat loggfilformat.

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

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

I Windows PowerShell 5.1 är standardbeteendet Export-Csv och ConvertTo-Csv att inkludera typinformation i form av en #TYPE kommentar. Från och med PowerShell 6.0 är standardvärdet inte att inkludera kommentaren, men detta kan åsidosättas med parametern IncludeTypeInformation.

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

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

När en #TYPE-kommentar ingår i CSV-data, använder Import-Csv och ConvertFrom-Csv denna information för att ställa in egenskapen pstypenames för de deserialiserade objekten.

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

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

Test
CSV:Test

ConvertFrom-StringData kommentarer

I dess strängdata behandlar cmdleten ConvertFrom-StringData rader som börjar med # som kommentarer. Mer information finns i:

Anteckningar

  • Blockkommentar kan inte kapslas. I följande exempel är Baz inte en del av kommentaren.

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

  • <# #> har ingen särskild betydelse i en kommentar med en enda rad. # har ingen särskild betydelse i en blockkommentare.

  • För att behandlas som en kommentar får kommentarstecknet inte vara en del av en token som inte är kommentar. I följande exempel är #Bar och <#Bar#> en del av Foo... token. Därför behandlas de inte som kommentarer.

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