Freigeben über

about_Comments

  • Artikel

Kurzbeschreibung

Beschreibt, wie man PowerShell-Kommentare verwendet und listet spezielle Anwendungsfälle auf.

Lange Beschreibung

Sie können Kommentare schreiben, um Ihren PowerShell-Code zu kommentieren oder zu strukturieren, um die Lesbarkeit zu verbessern. Wenn Ihr Code ausgeführt wird, wird Kommentartext von PowerShell ignoriert.

Kommentare stellen den Lesern des Codes einen wichtigen Kontext zur Verfügung. Sie sollten Kommentare für die folgenden Zwecke verwenden:

  • Erläutern von komplexem Code in einfacheren Ausdrücken
  • Erläutern, warum ein bestimmter Ansatz ausgewählt wurde
  • Zu beachtende Dokumentrandfälle
  • Bereitstellen von Links zu unterstützendem Referenzmaterial

Einige Kommentare haben in PowerShell eine besondere Bedeutung. Siehe Sonderkommentare.

PowerShell-Kommentarstile

PowerShell unterstützt zwei Kommentarformatvorlagen:

  • Einzeilige Kommentare beginnen mit einem Hash-Zeichen (#) und enden mit einer neuen Zeile. Dem # kann Text vorangestellt sein, der nicht Teil des Kommentars ist, einschließlich Leerzeichen. Einzeilige Kommentare, die in derselben Zeile wie der nicht kommentierte Quellcode platziert werden, werden als End-of-Line-Kommentare bezeichnet.

  • Blockkommentare beginnen mit <# und enden mit #>. Ein Blockkommentar kann eine beliebige Anzahl von Zeilen umfassen und vor, nach oder in der Mitte des nicht kommentierten Quellcodes eingeschlossen werden. Der gesamte Text innerhalb des Blocks wird als Teil desselben Kommentars behandelt, einschließlich Leerzeichen.

    Wichtig

    Sie können einzeilige Kommentare in einen Blockkommentar einschließen. Sie können jedoch keine Blockkommentare verschachteln. Wenn Sie versuchen, Blockkommentare zu verschachteln, endet der äußere Blockkommentar am ersten gefundenen #>.

Beispiele

Beispiel 1: Einzelzeilenkommentar

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

Beispiel 2: Blockieren eines Kommentars

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

Beispiel 3: Kommentar am Zeilenende

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

Beispiel 4: Inline-Blockkommentar

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

Beispiel 5: Vollständiges Beispiel

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

Spezielle Kommentare

PowerShell enthält mehrere Kommentarstichwörter zur Unterstützung bestimmter Anwendungsfälle.

Kommentarbasierte Hilfe

Sie können kommentarbasierte Hilfeinhalte für Funktionen und Skripts mithilfe von einzeiligen oder Blockkommentaren schreiben. Benutzer können das Cmdlet Get-Help verwenden, um kommentarbasierte Hilfe für eine Funktion oder ein Skript anzuzeigen. PowerShell definiert 15 Kommentarstichwörter, die verwendet werden können, um Informationen wie beschreibung und Beispielverwendung bereitzustellen.

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

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

Weitere Informationen finden Sie unter:

#Requires

Die #Requires-Anweisung verhindert, dass ein Skript ausgeführt wird, es sei denn, die aktuelle PowerShell-Sitzung erfüllt die angegebenen Voraussetzungen. #Requires kann in jeder Zeile eines Skripts vorkommen, wird jedoch unabhängig von der Position gleich verarbeitet.

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

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

Weitere Informationen finden Sie unter about_Requires.

Signaturblock

Skripts können signiert werden, damit sie Den PowerShell-Ausführungsrichtlinien entsprechen. Nach dem Signieren wird am Ende eines Skripts ein Signaturblock hinzugefügt. Dieser Block verwendet die Form mehrerer einzeiligen Kommentare, die von PowerShell gelesen werden, bevor das Skript ausgeführt wird.

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

Weitere Informationen finden Sie unter about_signing.

Shebang

Auf Unix-ähnlichen Systemen ist shebang (#!) eine Direktive, die am Anfang eines Skripts verwendet wird, um anzugeben, welche Shell das Skript ausführen soll. Shebang ist kein Bestandteil der PowerShell-Sprache. PowerShell interpretiert sie als regulären Kommentar. Shebang wird vom Betriebssystem interpretiert.

Im folgenden Beispiel sorgt der Shebang dafür, dass PowerShell das Skript ausführt, wenn das Skript aus einem Nicht-PowerShell-Kontext aufgerufen wird.

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

Code-Editor-Bereichsmarkierungen

Einige Code-Editoren unterstützen Regionsmarkierungen, mit denen Sie Abschnitte von Code reduzieren und erweitern können. Bei PowerShell sind die Bereichsmarkierungen Kommentare, die mit #region beginnen und mit #endregionenden. Die Bereichsmarkierungen müssen sich am Anfang einer Zeile befinden. Die Regionsmarkierungen werden in PowerShell ISE und in Visual Studio Code mit der PowerShell-Erweiterung unterstützt. Die Regionsmarkierungen sind kein Bestandteil der PowerShell-Sprache. PowerShell interpretiert sie als normale Kommentare.

Weitere Informationen finden Sie im Abschnitt Faltung der Dokumentation Grundlegende Bearbeitung in Visual Studio Code.

Kommentare in Zeichenfolgetoken

# und <# #> haben keine besondere Bedeutung innerhalb einer erweiterbaren oder wörtlichen Zeichenfolge. PowerShell interpretiert die Zeichen buchstäblich.

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.

Bestimmte PowerShell-Features sind jedoch so konzipiert, dass sie mit Zeichenfolgen arbeiten, die Kommentare enthalten. Die Interpretation des Kommentars hängt von der jeweiligen Funktion ab.

Kommentare für reguläre Ausdrücke

Reguläre Ausdrücke (regex) in PowerShell verwenden das .NET regex-Modul, das zwei Kommentarformatvorlagen unterstützt:

  • Inlinekommentar ((?#))
  • Zeilenendekommentar (#)

Regex-Kommentare werden von allen regex-basierten Features in PowerShell unterstützt. Zum Beispiel:

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

Anmerkung

Ein Regex-Zeilenendekommentar erfordert entweder das (?x)-Konstrukt oder die IgnorePatternWhitespace-Option.

Weitere Informationen finden Sie unter:

JSON-Kommentare

Ab PowerShell 6.0 unterstützt das Cmdlet ConvertFrom-Json die folgenden JSON-Kommentarstile:

  • Einzeiliger Kommentar (//)
  • Blockkommentar (/* */)

Anmerkung

Das Cmdlet Invoke-RestMethod deserialisiert automatisch empfangene JSON-Daten. In PowerShell 6.0 sind Kommentare in den JSON-Daten zulässig.

Zum Beispiel:

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

Foo
---
Bar

Warnung

Ab PowerShell 7.4 unterstützt der Cmdlet Test-Json kein JSON mehr mit Kommentaren. Wenn der JSON Kommentare enthält, wird ein Fehler zurückgegeben. In unterstützten Versionen vor 7.4 analysiert Test-Json JSON erfolgreich mit Kommentaren. In PowerShell 7.5 enthält Test-Json eine Option zum Ignorieren von JSON-Kommentaren.

CSV-Kommentare

Import-Csv und ConvertFrom-Csv unterstützen das erweiterte W3C-Protokollformat. Zeilen beginnend mit dem Hashzeichen (#) werden als Kommentare behandelt und ignoriert, es sei denn, der Kommentar beginnt mit #Fields: und enthält eine durch Trennzeichen getrennte Liste von Spaltennamen. In diesem Fall verwendet das Cmdlet diese Spaltennamen. Dies ist das Standardformat für Windows IIS und andere Webserverprotokolldateien. Weitere Informationen finden Sie unter Erweitertes Protokolldateiformat.

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

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

In Windows PowerShell 5.1 besteht das standardmäßige Export-CSV-- und ConvertTo-CSV--Verhalten darin, Typinformationen in Form eines #TYPE Kommentars einzuschließen. Ab PowerShell 6.0 wird der Kommentar standardmäßig nicht mehr eingeschlossen, dies kann jedoch mit dem Parameter IncludeTypeInformation überschrieben werden.

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

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

Wenn ein #TYPE-Kommentar in CSV-Daten enthalten ist, verwenden Import-Csv und ConvertFrom-Csv diese Informationen, um die pstypenames-Eigenschaft des/der deserialisierten Objekts/Objekte festzulegen.

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

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

Test
CSV:Test

ConvertFrom-StringData-Kommentare

Innerhalb seiner Zeichenfolgendaten behandelt das Cmdlet ConvertFrom-StringData Zeilen, die mit # beginnen, als Kommentare. Weitere Informationen finden Sie unter:

Notizen

  • Blockkommentare können nicht geschachtelt werden. Im folgenden Beispiel ist Baz kein Teil des Kommentars.

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

  • <# #> hat keine besondere Bedeutung innerhalb eines einzeiligen Kommentars. # hat keine besondere Bedeutung innerhalb eines Blockkommentars.

  • Um als Kommentar behandelt zu werden, darf das Kommentarzeichen kein Teil eines Nichtkommentartokens sein. Im folgenden Beispiel sind #Bar und <#Bar#> Teil des Foo... Tokens. Daher werden sie nicht als Kommentare behandelt.

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