Muokkaa

Jaa

about_Comments

  • Artikkeli

Short description

Describes how to use PowerShell comments and lists special use cases.

Long description

You can write comments to annotate or structure your PowerShell code to help with readability. When your code is run, comment text is ignored by PowerShell.

Comments provide important context to readers of the code. You should use comments for the following purposes:

  • Explain complex code in simpler terms
  • Explain why a particular approach was chosen
  • Document edge cases to be aware
  • Provide links to supporting reference material

Some comments have special meaning in PowerShell. See Special comments.

PowerShell comment styles

PowerShell supports two comment styles:

  • Single-line comments begin with hash character (#) and end with a newline. The # can be preceded by text that's not a part of the comment, including whitespace. Single-line comments placed on the same line as uncommented source code are known as end-of-line comments.

  • Block comments begin with <# and end with #>. A block comment can span any number of lines, and can be included before, after or in the middle of uncommented source code. All text within the block is treated as part of the same comment, including whitespace.

    Important

    You can include single-line comments within a block comment. However, you can't nest block comments. If you attempt to nest block comments, the outer block comment ends at the first #> encountered.

Examples

Example 1: Single-line comment

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

Example 2: Block comment

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

Example 3: End-of-line comment

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

Example 4: Inline block comment

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

Example 5: Full example

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

Special comments

PowerShell includes several comment keywords to support specific uses.

Comment-based help

You can write comment-based help content for functions and scripts using either single-line or block comments. Users can use the Get-Help cmdlet to view comment-based help for a function or script. PowerShell defines 15 comment keywords that can be used to provide information such as the description and example usage.

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

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

For more information, see:

#Requires

The #Requires statement prevents a script from running unless the current PowerShell session meets the specified prerequisites. #Requires can appear on any line in a script, but is processed in the same manner regardless of position.

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

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

For more information, see about_Requires.

Signature block

Scripts can be signed so that they comply with PowerShell execution policies. Once signed, a signature block is added to the end of a script. This block takes the form of multiple single-line comments, which are read by PowerShell before the script is executed.

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

For more information, see about_signing.

Shebang

On Unix-like systems, a shebang (#!) is a directive used at the beginning of a script to indicate which shell should be used to run the script. Shebang isn't a part of the PowerShell language. PowerShell interprets it as a regular comment. Shebang is interpreted by the operating system.

In the following example, the shebang ensures PowerShell runs the script when the script is invoked from a non-PowerShell context.

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

Code editor region markers

Some code editors support region markers that allow you to collapse and expand sections of code. For PowerShell, the region markers are comments that begin with #region and end with #endregion. The region markers must be at the beginning of a line. The region markers are supported in the PowerShell ISE and in Visual Studio Code with the PowerShell extension. The region markers aren't a part of the PowerShell language. PowerShell interprets them as regular comments.

For more information, see the Folding section of the Basic editing in Visual Studio Code documentation.

Comments in string tokens

# and <# #> don't have special meaning within an expandable or verbatim string. PowerShell interprets the characters literally.

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.

However, certain PowerShell features are designed to work with strings that contain comments. Interpretation of the comment is dependant on the specific feature.

Regular expression comments

Regular expressions (regex) in PowerShell use the .NET regex engine, which supports two comment styles:

  • Inline comment ((?#))
  • End-of-line comment (#)

Regex comments are supported by all regex-based features in PowerShell. For example:

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

Note

An end-of-line regex comment requires either the (?x) construct or the IgnorePatternWhitespace option.

For more information, see:

JSON comments

Beginning in PowerShell 6.0, the ConvertFrom-Json cmdlet supports the following JSON comment styles:

  • Single-line comment (//)
  • Block comment (/* */)

Note

The Invoke-RestMethod cmdlet automatically deserializes received JSON data. In PowerShell 6.0 onwards, comments are permitted in the JSON data.

For example:

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

Foo
---
Bar

Warning

Beginning in PowerShell 7.4, the Test-Json cmdlet no longer supports JSON with comments. An error is returned if the JSON includes comments. In supported versions prior to 7.4, Test-Json successfully parses JSON with comments. In PowerShell 7.5, Test-Json includes an option to ignore JSON comments.

CSV comments

Import-Csv and ConvertFrom-Csv support the W3C Extended Log format. Lines starting with the hash character (#) are treated as comments and ignored unless the comment starts with #Fields: and contains delimited list of column names. In that case, the cmdlet uses those column names. This is the standard format for Windows IIS and other web server logs. For more information, see Extended Log File Format.

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

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

In Windows PowerShell 5.1, the default Export-Csv and ConvertTo-Csv behavior is to include type information in the form of a #TYPE comment. Beginning in PowerShell 6.0, the default is not to include the comment, but this can be overridden with the IncludeTypeInformation parameter.

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

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

When a #TYPE comment is included in CSV data, Import-Csv and ConvertFrom-Csv use this information to set the pstypenames property of the deserialized object(s).

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

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

Test
CSV:Test

ConvertFrom-StringData comments

Within its string data, the ConvertFrom-StringData cmdlet treats lines beginning with # as comments. For more information, see:

Notes

  • Block comments can't be nested. In the following example, Baz is not a part of the comment.

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

  • <# #> has no special meaning within a single-line comment. # has no special meaning within a block comment.

  • To be treated as a comment, the comment character must not be a part of a non-comment token. In the following example, #Bar and <#Bar#> are a part of the Foo... token. Therefore, they aren't treated as comments.

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