about_Comments

Kurzbeschreibung

Beschreibt die Verwendung von PowerShell-Kommentaren und Listen spezieller Anwendungsfälle.

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. Weitere Informationen finden Sie unter spezielle Kommentare.

PowerShell-Kommentarformatvorlagen

PowerShell unterstützt zwei Kommentarformatvorlagen:

• Einzeilige Kommentare mit Hashzeichen (#) beginnen und mit einer Neuen zeile enden. Der # kann Text vorangestellt werden, 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.

• Kommentare blockieren mit <# beginnen und mit #>enden. 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 #>.

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: End-of-Line-Kommentar

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

Beispiel 4: Inlineblockkommentar

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

Kommentarbasierte Hilfe

Sie können kommentarbasierte Hilfeinhalte für Funktionen und Skripts mithilfe von einzeiligen oder blockierenden Kommentaren 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:

• Über kommentarbasierte Hilfe
• Schreiben Comment-Based 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

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 eine shebang (#!) eine Direktive, die am Anfang eines Skripts verwendet wird, um anzugeben, welche Shell zum Ausführen des Skripts verwendet werden soll. Shebang ist kein Bestandteil der PowerShell-Sprache. PowerShell interpretiert sie als regulären Kommentar. Shebang wird vom Betriebssystem interpretiert.

Im folgenden Beispiel stellt die Shebang sicher, 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 abschnitt der Basic-Bearbeitung in der Dokumentation zu Visual Studio Code.

Kommentare in Zeichenfolgentoken

# und <# #> haben keine besondere Bedeutung innerhalb einer erweiterbaren oder 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 ((?#))
• End-of-Line-Kommentar (#)

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

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" "ConvertFrom-Json" die folgenden JSON-Kommentarstile:

• Einzeiligen Kommentar (//)
• Blockkommentar (/* */)

Zum Beispiel:

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

Foo
---
Bar

CSV-Kommentare

Import-CSV- und ConvertFrom-Csv- das erweiterte W3C-Protokollformat unterstützen. 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 Webserverprotokolle. Weitere Informationen finden Sie unter Extended Log File Format.

@'
# 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 der Standardwert nicht das Einschließen des Kommentars, 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, Import-Csv und ConvertFrom-Csv diese Informationen verwenden, um die pstypenames Eigenschaft deserialisierten Objekts(n) festzulegen.

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

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

Test
CSV:Test

ConvertFrom-StringData Kommentare

Innerhalb der Zeichenfolgendaten behandelt das cmdlet ConvertFrom-StringData Zeilen beginnend mit # als Kommentare. Weitere Informationen finden Sie unter:

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

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