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
  • Dokumentieren Sie Randfälle, die beachtet werden sollten
  • Bereitstellen von Links zu unterstützendem Referenzmaterial

Einige Kommentare haben in PowerShell eine besondere Bedeutung. Sehen Sie spezielle Kommentare.

PowerShell-Kommentierstile

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.

    Wichtig

    Sie können einzeilige Kommentare in einen Blockkommentar einschließen. Blockkommentare können jedoch nicht verschachtelt werden. Wenn Sie versuchen, Blockkommentare zu verschachteln, endet der äußere Blockkommentar beim ersten #> das getroffen wird.

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

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 Folding der Dokumentation zu Grundlegendes Bearbeiten in Visual Studio Code.

Kommentare in String-Token

# und <# #> haben keine besondere Bedeutung innerhalb eines erweiterbaren oder wörtlichen Strings. 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 die .NET Regex -Engine, die zwei Kommentierstile unterstützt:

  • Inline-Kommentar ((?#))
  • Kommentar am Ende der Zeile (#)

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 Kommentar am Ende der Zeile für reguläre Ausdrücke erfordert entweder den (?x) -Konstruktion oder die IgnorePatternWhitespace -Option.

Weitere Informationen finden Sie unter:

JSON-Kommentare

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

  • Einzelzeiliger Kommentar (//)
  • Blockkommentar (/* */)

Anmerkung

Das Cmdlet Invoke-RestMethod deserialisiert empfangene JSON-Daten automatisch. 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 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, Test-Json wird JSON mit Kommentaren erfolgreich geparst. 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 Webserver-Logs. Weitere Informationen finden Sie im Abschnitt Erweitertes Logdateiformat.

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

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

In Windows PowerShell 5.1 besteht das Standardverhalten von Export-Csv und ConvertTo-Csv 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/des deserialisierten Objekts/Objekte zu setzen.

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

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

Test
CSV:Test

ConvertFrom-StringData Kommentare

Innerhalb seiner Zeichenkettendaten 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 Kommentarsymbol kein Teil eines Nicht-Kommentar-Tokens 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 [...]