Delen via

about_Comments

  • Artikel

Korte beschrijving

Hierin wordt beschreven hoe u PowerShell-opmerkingen en speciale use cases gebruikt.

Lange beschrijving

U kunt opmerkingen schrijven om aantekeningen te maken of uw PowerShell-code te structuren om te helpen bij de leesbaarheid. Wanneer uw code wordt uitgevoerd, wordt opmerkingstekst genegeerd door PowerShell.

Opmerkingen bieden belangrijke context aan lezers van de code. Gebruik opmerkingen voor de volgende doeleinden:

  • Complexe code uitleggen in eenvoudigere termen
  • Uitleggen waarom een bepaalde benadering is gekozen
  • Randgevallen van documenten om rekening mee te houden
  • Koppelingen naar ondersteunend referentiemateriaal opgeven

Sommige opmerkingen hebben een speciale betekenis in PowerShell. Zie Speciale opmerkingen.

PowerShell opmerkingstijlen

PowerShell ondersteunt twee opmerkingenstijlen:

  • opmerkingen met één regel beginnen met hashteken (#) en eindigen met een nieuwe regel. De # kan worden voorafgegaan door tekst die geen deel uitmaakt van de opmerking, inclusief witruimte. Opmerkingen met één regel die op dezelfde regel worden geplaatst als niet-gecommentarieerde broncode, worden opmerkingen aan het einde van de regel genoemd.

  • Blokopmerkingen beginnen met <# en eindigen met #>. Een blokopmerking kan een willekeurig aantal regels omvatten en kan worden opgenomen vóór, na of in het midden van niet-commentaar bij de broncode. Alle tekst in het blok wordt behandeld als onderdeel van dezelfde opmerking, inclusief witruimte.

    Belangrijk

    U kunt opmerkingen met één regel opnemen in een blokopmerking. U kunt echter geen blokopmerkingen nesten. Als u blokopmerkingen probeert te nesten, eindigt de buitenste blokopmerking op de eerste #> aangetroffen.

Voorbeelden

Voorbeeld 1: Opmerking met één regel

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

Voorbeeld 2: Opmerking blokkeren

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

Voorbeeld 3: Opmerking einde regel

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

Voorbeeld 4: Inline blokcommentaar

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

Voorbeeld 5: Volledig voorbeeld

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

Speciale opmerkingen

PowerShell bevat verschillende trefwoorden voor opmerkingen ter ondersteuning van specifieke toepassingen.

Help op basis van opmerkingen

U kunt help-inhoud op basis van opmerkingen schrijven voor functies en scripts met behulp van één regel of opmerkingen blokkeren. Gebruikers kunnen de cmdlet Get-Help gebruiken om hulp op basis van opmerkingen weer te geven voor een functie of script. PowerShell definieert 15 trefwoorden voor opmerkingen die kunnen worden gebruikt om informatie te verstrekken, zoals de beschrijving en het voorbeeldgebruik.

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

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

Zie voor meer informatie:

#Requires

De #Requires-instructie voorkomt dat een script wordt uitgevoerd, tenzij de huidige PowerShell-sessie voldoet aan de opgegeven vereisten. #Requires kan op elke regel in een script worden weergegeven, maar wordt op dezelfde manier verwerkt, ongeacht de positie.

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

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

Zie about_Requiresvoor meer informatie.

Handtekeningblok

Scripts kunnen worden ondertekend zodat ze voldoen aan het PowerShell-uitvoeringsbeleid. Zodra het is ondertekend, wordt er een handtekeningblok toegevoegd aan het einde van een script. Dit blok heeft de vorm van meerdere opmerkingen met één regel, die worden gelezen door PowerShell voordat het script wordt uitgevoerd.

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

Zie about_signingvoor meer informatie.

Shebang

Op Unix-achtige systemen is een shebang (#!) een instructie die aan het begin van een script wordt gebruikt om aan te geven welke shell moet worden gebruikt om het script uit te voeren. Shebang maakt geen deel uit van de PowerShell-taal. PowerShell interpreteert het als een normale opmerking. Shebang wordt geïnterpreteerd door het besturingssysteem.

In het volgende voorbeeld zorgt de shebang ervoor dat PowerShell het script uitvoert wanneer het script wordt aangeroepen vanuit een niet-PowerShell-context.

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

Regiomarkeringen voor code-editor

Sommige code-editors ondersteunen regiomarkeringen waarmee u secties met code kunt samenvouwen en uitvouwen. Voor PowerShell zijn de regiomarkeringen opmerkingen die beginnen met #region en eindigen met #endregion. De regiomarkeringen moeten zich aan het begin van een regel bevinden. De regiomarkeringen worden ondersteund in PowerShell ISE en in Visual Studio Code met de PowerShell-extensie. De regiomarkeringen maken geen deel uit van de PowerShell-taal. PowerShell interpreteert ze als normale opmerkingen.

Zie voor meer informatie de sectie Folding van de documentatie over basisbewerkingen in Visual Studio Code.

Opmerkingen in tekenreekstokens

# en <# #> hebben geen speciale betekenis binnen een uitbreidbare of tekenreeks. PowerShell interpreteert de tekens letterlijk.

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.

Bepaalde PowerShell-functies zijn echter ontworpen om te werken met tekenreeksen die opmerkingen bevatten. De interpretatie van de opmerking is afhankelijk van de specifieke functie.

Opmerkingen bij reguliere expressies

Reguliere expressies (regex) in PowerShell gebruiken de .NET regex engine, die ondersteuning biedt voor twee opmerkingenstijlen:

  • Inline-opmerking ((?#))
  • Opmerking einde van regel (#)

Regex-opmerkingen worden ondersteund door alle functies op basis van regex in PowerShell. Bijvoorbeeld:

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

Notitie

Voor een regex-opmerking aan het einde van de regel is de (?x) constructie of de optie IgnorePatternWhitespace vereist.

Zie voor meer informatie:

JSON-opmerkingen

Vanaf PowerShell 6.0 ondersteunt de cmdlet ConvertFrom-Json de volgende JSON-opmerkingenstijlen:

  • Opmerking met één regel (//)
  • Opmerking blokkeren (/* */)

Notitie

Met de cmdlet Invoke-RestMethod worden JSON-gegevens automatisch gedeserialiseerd. In PowerShell 6.0 zijn opmerkingen toegestaan in de JSON-gegevens.

Bijvoorbeeld:

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

Foo
---
Bar

Waarschuwing

Vanaf PowerShell 7.4 biedt de cmdlet Test-Json- geen ondersteuning meer voor JSON met opmerkingen. Er wordt een fout geretourneerd als de JSON opmerkingen bevat. In ondersteunde versies vóór 7.4 parseert Test-Json JSON met opmerkingen. In PowerShell 7.5 bevat Test-Json een optie om JSON-opmerkingen te negeren.

CSV-opmerkingen

Import-Csv- en ConvertFrom-Csv de W3C Extended Log-indeling ondersteunen. Regels die beginnen met het hash-teken (#) worden behandeld als opmerkingen en genegeerd, tenzij de opmerking begint met #Fields: en een lijst met kolomnamen bevat met scheidingstekens. In dat geval gebruikt de cmdlet deze kolomnamen. Dit is de standaardindeling voor Windows IIS en andere webserverlogboeken. Zie uitgebreide logboekbestandsindelingvoor meer informatie.

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

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

In Windows PowerShell 5.1 is het standaardgedrag Export-Csv- en ConvertTo-Csv typegegevens op te nemen in de vorm van een #TYPE opmerking. Vanaf PowerShell 6.0 is de standaardinstelling dat de opmerking niet wordt opgenomen, maar dit kan worden overschreven met de parameter IncludeTypeInformation.

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

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

Wanneer een #TYPE opmerking wordt opgenomen in CSV-gegevens, Import-Csv en ConvertFrom-Csv deze informatie gebruiken om de eigenschap pstypenames van de gedeserialiseerde objecten in te stellen.

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

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

Test
CSV:Test

ConvertFrom-StringData opmerkingen

De cmdlet ConvertFrom-StringData behandelt binnen de tekenreeksgegevens de regels die beginnen met # als opmerkingen. Zie voor meer informatie:

Notities

  • Blokopmerkingen kunnen niet genest worden. In het volgende voorbeeld maakt Baz geen deel uit van de opmerking.

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

  • <# #> heeft geen speciale betekenis binnen een opmerking met één regel. # heeft geen speciale betekenis binnen een blokcommentaar.

  • Als u als opmerking wilt worden behandeld, mag het opmerkingteken geen deel uitmaken van een token zonder opmerking. In het volgende voorbeeld maken #Bar en <#Bar#> deel uit van het Foo... token. Daarom worden ze niet behandeld als opmerkingen.

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