about_Comments

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-Kommentarformatvorlagen

PowerShell unterstützt zwei Kommentarformatvorlagen:

  • Einzelzeilige Kommentare beginnen mit dem Hashtag-Zeichen (#) und enden mit einem Zeilenumbruch. Vor dem # kann Text stehen, der nicht Teil des Kommentars ist, einschließlich Leerraum. 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.

    Von Bedeutung

    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 beim ersten #> das getroffen wird.

Examples

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 Ende der Zeile

$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 Kommentar-Schlüsselwörter zur Unterstützung bestimmter Verwendungen.

Kommentarbasierte Hilfe

Sie können kommentarbasierte Hilfeinhalte für Funktionen und Skripte schreiben, indem Sie entweder einzeilige oder Blockkommentare verwenden. 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 findest du 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 erscheinen, wird 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

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-Region-Markierungen

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 Zeichenfolgentoken

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

Reguläre Ausdruckskommentare

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

Hinweis

Ein Kommentar am Ende der Zeile für reguläre Ausdrücke erfordert entweder den (?x) -Konstruktion oder die IgnorePatternWhitespace -Option.

Weitere Informationen findest du unter:

JSON-Kommentare

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

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

Hinweis

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

Beispiel:

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

Foo
---
Bar

Warnung

Ab PowerShell 7.4 unterstützt das Cmdlet Test-Json JSON-Dateien mit Kommentaren nicht mehr. 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 W3C Extended Log-Format. 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 ist es standardmäßig so, dass der Kommentar nicht eingeschlossen wird, aber dies kann 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 findest du unter:

Hinweise

  • 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 [...]
  • Zuletzt aktualisiert um