о_Комментарии

Краткое описание

Описывает использование комментариев 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 для просмотра справки на основе комментариев для функции или скрипта. 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 { }

Дополнительные сведения см. в следующем разделе:

• about_Comment_Based_Help
• Написание Comment-Based Темы справки

#Requires

Оператор #Requires предотвращает выполнение скрипта, если текущий сеанс PowerShell не соответствует указанным требованиям. #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.

Маркеры областей редактора кода

Некоторые редакторы кода поддерживают маркеры регионов, которые позволяют свернуть и развернуть разделы кода. Для PowerShell маркеры региона — это комментарии, начинающиеся с #region и заканчивающиеся #endregion. Маркеры региона должны находиться в начале строки. Маркеры области поддерживаются в PowerShell ISE и Visual Studio Code с расширением PowerShell. Маркеры региона не являются частью языка 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 предназначены для работы со строками, содержащими примечания. Интерпретация комментария зависит от конкретной функции.

Комментарии регулярных выражений

Регулярные выражения (regex) в 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 поддерживает такие стили комментариев в JSON:

• Однострочный комментарий (//)
• Блокировать комментарий (/* */)

Заметка

Командлет Invoke-RestMethod автоматически десериализует полученные JSON данные. В PowerShell 6.0 комментарии разрешены в данных JSON.

Например:

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

Foo
---
Bar

Предупреждение

Начиная с PowerShell 7.4 командлет Test-Json больше не поддерживает JSON с комментариями. Ошибка возвращается, если JSON содержит примечания. В поддерживаемых версиях до 7.4 Test-Json успешно анализирует JSON с комментариями. В PowerShell 7.5 Test-Json включает возможность игнорировать комментарии JSON.

Примечания CSV

Import-Csv и ConvertFrom-Csv поддерживают формат расширенного журнала W3C. Строки, начиная с хэш-символа (#) рассматриваются как комментарии и игнорируются, если комментарий не начинается с #Fields: и содержит разделенный список имен столбцов. В этом случае командлет использует эти имена столбцов. Это стандартный формат для служб IIS Windows и других журналов веб-сервера. Дополнительные сведения см. в разделе Расширенный формат файла журнала.

@'
# 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"

Если комментарий #TYPE включен в данные CSV, 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 обрабатывает строки, начиная с # как примечания. Дополнительные сведения см. в следующем разделе:

• пример 3. Преобразование строки здесь, содержащей комментарий

Примечания.

• Блочные комментарии не могут быть вложенными. В следующем примере 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 [...]