about_Comments

项目
01/16/2025

简短说明

介绍如何使用 PowerShell 注释并列出特殊用例。

详细说明

可以编写注释来批注或构建 PowerShell 代码，以帮助提高可读性。运行代码时，PowerShell 将忽略注释文本。

注释为代码的读取者提供重要的上下文。应将注释用于以下目的：

以更简单的术语解释复杂代码
解释为何选择了特定方法
要注意的文档边缘案例
提供指向支持参考材料的链接

某些注释在 PowerShell 中具有特殊意义。请参阅特别评论。

PowerShell 注释样式

PowerShell 支持两种注释样式：

单行注释以哈希字符 (#) 开头，并以换行符结尾。 # 前面可以有不是注释的一部分的文本，包括空格。与未注释源代码位于同一行的单行注释称为行尾注释。
块注释以 <# 开头并以 #> 结尾。块注释可以跨越任意数量的行，并且可以包含在未注释源代码之前、之后或中间。块中的所有文本都被视为同一批注释的一部分，包括空格。

重要

可以在块注释中包含单行注释。但是，不能嵌套块注释。如果尝试嵌套块注释，则外部块注释将在遇到的第一个 #> 处结束。

例子

示例 1：单行注释

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

示例 2：块注释

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

示例 3：行尾注释

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

示例 4：内联块注释

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

示例 5：完整示例

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

特殊注释

PowerShell 包含多个用于支持特定用途的注释关键字。

基于注释的帮助

可以使用单行注释或块注释来为函数和脚本编写注释式帮助内容。用户可以使用 Get-Help cmdlet 查看函数或脚本的基于注释的帮助。 PowerShell 定义了 15 个注释关键字，可用于提供说明和示例用法等信息。

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

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

有关详细信息，请参阅：

`#Requires`

除非当前 PowerShell 会话满足指定的先决条件，否则 #Requires 语句会阻止脚本运行。 #Requires 可以在脚本中的任何行上显示，但无论位置如何，都以相同的方式进行处理。

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

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

有关详细信息，请参阅 about_Requires。

签名块

可以对脚本进行签名，使其符合 PowerShell 执行策略。签名后，将签名块添加到脚本的末尾。此块采用多个单行注释的形式，在执行脚本之前由 PowerShell 读取。

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

有关详细信息，请参阅 about_signing。

Shebang

在类似 Unix 的系统上，shebang (#!) 是脚本开头使用的指令，用于指示应使用哪个 shell 来运行脚本。 Shebang 不是 PowerShell 语言的一部分。 PowerShell 将其解释为常规注释。 Shebang 由操作系统解释。

在以下示例中，shebang 可确保在非 PowerShell 上下文中调用脚本时，PowerShell 会运行脚本。

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

代码编辑器区域标记

某些代码编辑器支持区域标记，允许折叠和展开代码部分。对于 PowerShell，区域标记是以 #region 开头的注释，以 #endregion结尾。区域标记必须位于行的开头。 PowerShell ISE 和具有 PowerShell 扩展的 Visual Studio Code 支持区域标记。区域标记不是 PowerShell 语言的一部分。 PowerShell 将它们解释为常规注释。

有关详细信息，请参阅 Visual Studio Code 中的基本编辑文档的折叠部分。

字符串令牌中的注释

# 和 <# #> 在可扩展或逐字字符串中没有特殊含义。 PowerShell 将这些字符按字面意思进行解释。

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.

但是，某些 PowerShell 功能旨在处理包含注释的字符串。注释的解释取决于特定功能。

正则表达式注释

PowerShell 中的正则表达式（regex）使用 .NET 正则表达式引擎，该引擎支持两种注释样式：

内联注释 ((?#))
行末注释（#）

PowerShell 中所有基于正则表达式的功能都支持正则表达式注释。例如：

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

注意

行尾正则表达式注释需要 (?x) 构造或 IgnorePatternWhitespace 选项。

有关详细信息，请参阅：

JSON 注释

从 PowerShell 6.0 开始，ConvertFrom-Json cmdlet 支持以下 JSON 注释样式：

单行注释 (//)
块注释 (/* */)

注意

Invoke-RestMethod cmdlet 会自动反序列化收到的 JSON 数据。在 PowerShell 6.0 及更高版本，JSON 数据中允许注释。

例如：

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

Foo
---
Bar

警告

从 PowerShell 7.4 开始，Test-Json cmdlet 不再支持带有注释的 JSON。如果 JSON 包含注释，则返回错误。在 7.4 之前的受支持版本中，Test-Json 使用注释成功分析 JSON。在 PowerShell 7.5 中，Test-Json 包含忽略 JSON 注释的选项。

CSV 注释

Import-Csv 和 ConvertFrom-Csv 支持 W3C 扩展日志格式。以哈希字符（#）开头的行被视为注释并被忽略，除非注释以 #Fields: 开头，并且包含列名的分隔列表。在这种情况下，cmdlet 使用这些列名称。这是 Windows IIS 和其他 Web 服务器日志的标准格式。有关详细信息，请参阅扩展日志文件格式。

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

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

在 Windows PowerShell 5.1 中，默认 Export-Csv 和 ConvertTo-Csv 行为是以 #TYPE 注释的形式包含类型信息。从 PowerShell 6.0 开始，默认情况下不包含注释，但可以通过 IncludeTypeInformation 参数来覆盖默认设置。

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

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

CSV 数据中包含 #TYPE 注释时，Import-Csv 和 ConvertFrom-Csv 使用此信息设置反序列化对象的 pstypenames 属性。

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

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

Test
CSV:Test

`ConvertFrom-StringData` 注释

在其字符串数据中，ConvertFrom-StringData cmdlet 将以 # 开头的行视为注释。有关详细信息，请参阅：

示例 3：转换包含注释的 here-string

备注

无法嵌套块注释。在以下示例中，Baz 不是注释的一部分。
```
<#
'Foo'
<# 'Bar' #>
'Baz'
#>
```
在单行注释中，"<# #>" 没有任何特殊含义。 # 在代码块注释中没有特殊含义。
若要被视为注释，注释字符不得是非注释标记的一部分。在以下示例中，#Bar 和 <#Bar#> 是 Foo... 令牌的一部分。因此，它们不会被视为注释。
```
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 [...]
```

通过