about_Comments

Kurzbeschreibung

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

Lange Beschreibung

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

Kommentare liefern den Lesern des Codes wichtigen Kontext. Sie sollten Kommentare für die folgenden Zwecke verwenden:

• Komplexen Code in einfacheren Begriffen erklären
• Erläutern, warum ein bestimmter Ansatz gewählt wurde
• Zu beachtende Dokumentrandfälle
• Bereitstellung von Links zu unterstützendem Referenzmaterial

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

PowerShell-Kommentarformatvorlagen

Die PowerShell unterstützt zwei Arten von Kommentaren:

• 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 unkommentierte Quellcode stehen, werden als End-of-Line-Kommentare bezeichnet.

• Blockkommentare beginnen mit <# und enden mit #>. Ein Blockkommentar kann sich über eine beliebige Anzahl von Zeilen erstrecken und kann vor, nach oder in der Mitte von unkommentiertem Quellcode eingefügt werden. Der gesamte Text innerhalb des Blocks wird als Element desselben Kommentars behandelt, einschließlich Leerzeichen.

  Wichtig

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

Examples

Beispiel 1: Einzeiliger Kommentar

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

Beispiel 2: Blockkommentar

<#
    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 Kommentarschlüsselwörter, um bestimmte Anwendungen zu unterstützen.

Kommentarbasierte Hilfe

Sie können Hilfeinhalte für Funktionen und Skripte entweder in Form einzelner Kommentare oder als Blockkommentare schreiben. Mit dem Cmdlet Get-Help können Benutzer die kommentargestützte Hilfe für eine Funktion oder ein Skript anzeigen. PowerShell definiert 15 Kommentarschlüsselwörter, die verwendet werden können, um Informationen wie z. B. die Beschreibung und ein Verwendungsbeispiel 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:

• Über kommentarbasierte Hilfe
• Schreiben von kommentarbasierten Hilfethemen

#Requires

Die #Requires-Anweisung verhindert, dass ein Skript ausgeführt wird, es sei denn, die aktuelle PowerShell-Sitzung erfüllt die angegebenen Voraussetzungen. #Requires können in jeder Zeile in einem Skript angezeigt werden, werden jedoch unabhängig von der Position auf die gleiche Weise verarbeitet.

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

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

Weitere Informationen finden Sie unter about_Requires.

Signaturblock

Skripte können signiert werden, damit sie den Richtlinien der PowerShell-Ausführung entsprechen. Nach dem Signieren wird am Ende eines Skripts ein Signaturblock angefügt. Dieser Block hat die Form von mehreren einzeiligen Kommentaren, die von PowerShell vor der Ausführung des Skripts gelesen werden.

# 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 Element der PowerShell-Sprache. PowerShell interpretiert ihn 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 bieten Unterstützung für Region-Marker, die Ihnen die Möglichkeit bieten, Abschnitte des Codes zu komprimieren und zu erweitern. In der PowerShell sind die Region-Marken Kommentare, die mit #region beginnen und mit #endregion enden. Die Region-Marker müssen am Anfang einer Zeile stehen. Die Region-Marker werden in der PowerShell ISE und in Visual Studio Code mit der PowerShell Erweiterung unterstützt. Die Region-Marker sind nicht 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 Zeichenfolgentoken

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

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 Funktionen der PowerShell sind jedoch darauf ausgelegt, mit Zeichenfolgen zu 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 Funktionen 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

Weitere Informationen finden Sie unter:

• about_Regular_Expressions
• Verschiedene Konstrukte in regulären Ausdrücken

JSON Kommentare

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

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

Zum Beispiel:

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

Foo
---
Bar

CSV Kommentare

Import-Csv und ConvertFrom-Csv unterstützen das erweiterte W3C-Protokollformat. Zeilen, die mit dem Hash-Zeichen (#) beginnen, werden als Kommentare behandelt und ignoriert, es sei denn, der Kommentar beginnt mit #Fields: und enthält eine abgegrenzte Liste von Spaltennamen. In diesem Fall verwendet das Cmdlet diese Spaltennamen. Dies ist das Standardformat für Windows IIS und andere Webserverprotokolle. 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 den CSV-Daten enthalten ist, verwenden Import-Csv und ConvertFrom-Csv diese Informationen, um die pstypenames-Eigenschaft der deserialisierten 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:

• Beispiel 3: Konvertieren einer here-Zeichenfolge mit einem Kommentar

Hinweise

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

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

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

• Um als Kommentar behandelt zu werden, darf das Kommentarzeichen kein Teil eines Nichtkommentartokens sein. Im folgenden Beispiel sind #Bar und <#Bar#> ein Element des Tokens Foo.... Sie werden daher 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 [...]