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

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

Описывает использование комментариев 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.

шебанг

В Unix-подобных системах shebang (#!) — это директива, используемая в начале скрипта, чтобы указать, какую командную оболочку следует использовать для запуска скрипта. Шебанг не является частью языка PowerShell. PowerShell интерпретирует его как обычный комментарий. Шебанг интерпретируется операционной системой.

В следующем примере она гарантирует, что PowerShell запускает сценарий при вызове скрипта из контекста, отличного от PowerShell.

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

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

Некоторые редакторы кода поддерживают маркеры регионов, которые позволяют свернуть и развернуть разделы кода. Для PowerShell маркеры региона — это комментарии, начинающиеся с #region и заканчивающиеся #endregion. Маркеры региона должны находиться в начале строки. Маркеры регионов поддерживаются в PowerShell ISE и Visual Studio Code с помощью расширения PowerShell. Маркеры региона не являются частью языка PowerShell. PowerShell интерпретирует их как обычные комментарии.

Дополнительные сведения см. в разделе редактирования Basic в документации по 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, который поддерживает два стиля комментариев:

• Встроенный комментарий ((?#))
• Комментарий в конце строки (#)

Комментарии regex поддерживаются всеми функциями, основанными на регулярных выражениях в 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 [...]