コメントについて
簡単な説明
PowerShell のコメントとリストの特殊なユース ケースの使用方法について説明します。
長い説明
読みやすくするために、PowerShell コードに注釈を付けたり、構造化したりするためのコメントを記述できます。 コードを実行すると、PowerShell ではコメント テキストは無視されます。
コメントは、コードの閲覧者に重要なコンテキストを提供します。 コメントは、次の目的に使用する必要があります。
- 複雑なコードを簡単な用語で説明する
- 特定のアプローチが選択された理由を説明する
- 注意する必要がある特異ケースを文書化する
- サポート参照資料へのリンクを提供する
一部のコメントは、PowerShell で特別な意味を持ちます。 特別なコメントを参照してください。
PowerShell のコメント スタイル
PowerShell では、次の 2 つのコメント スタイルがサポートされています。
1 行のコメント ハッシュ文字 (
#) で始まり、改行で終わる必要があります。#の前には、コメントの一部ではないテキスト (空白を含む) を付けることができます。 コメントなしのソース コードと同じ行に配置された 1 行のコメントは、行末コメントと呼ばれます。コメントをブロック
<#で始まり、#>で終わる。 ブロック コメントは任意の数の行にまたがることができ、コメントされていないソース コードの前、後、または途中に含めることができます。 ブロック内のすべてのテキストは、空白を含め、同じコメントの一部として扱われます。重要
ブロック コメント内に 1 行のコメントを含めることができます。 ただし、ブロック コメントを入れ子にすることはできません。 ブロックコメントをネストしようとすると、外側のブロックコメントは最初に現れた
#>で終了します。
例の一覧
例 1: 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 には、特定の用途をサポートするいくつかのコメント キーワードが含まれています。
コメントベースのヘルプ
1 行またはブロックのコメントを使用して、関数とスクリプトのコメントベースのヘルプ コンテンツを記述できます。 ユーザーは、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 { }
詳細については、以下を参照してください。
#Requires
#Requires ステートメントは、現在の PowerShell セッションが指定された前提条件を満たしていない限り、スクリプトを実行できないようにします。
#Requires はスクリプト内の任意の行に表示できますが、位置に関係なく同じ方法で処理されます。
#Requires -Modules AzureRM.Netcore
#Requires -Version 6.0
param (
[Parameter(Mandatory)]
[string[]] $Path
)
詳しくは、「about_Requires」をご覧ください。
署名ブロック
スクリプトは、PowerShell 実行ポリシーに準拠するように署名できます。 署名されると、署名ブロックがスクリプトの末尾に追加されます。 このブロックは、スクリプトを実行する前に PowerShell によって読み取られた複数の 1 行のコメントの形式をとります。
# SIG # Begin signature block
# ...
# SIG # End signature block
詳細については、「about_signing」を参照してください。
シバン
Unix に似たシステムでは、shebang (#!) はスクリプトの先頭で使用されるディレクティブで、スクリプトの実行に使用するシェルを示します。
Shebang は PowerShell 言語の一部ではありません。 PowerShell では、通常のコメントとして解釈されます。 Shebang はオペレーティング システムによって解釈されます。
次の例では、スクリプトが PowerShell 以外のコンテキストから呼び出されたときに、shebang によって PowerShell によってスクリプトが実行されます。
#!/usr/bin/env pwsh
Write-Host 'Begin script'
コード エディター領域マーカー
一部のコード エディターでは、コードのセクションを折りたたんで展開できる領域マーカーがサポートされています。 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 機能は、コメントを含む文字列を操作するように設計されています。 コメントの解釈は、特定の機能によって異なります。
正規表現のコメント
PowerShell の正規表現 (正規表現) では、2 つのコメント スタイルをサポートする .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 コメント スタイルがサポートされています。
- 1 行コメント (
//) - コメントをブロックする (
/* */)
手記
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: で始まり、列名の区切りリストが含まれている場合を除き、無視されます。 その場合、コマンドレットはこれらの列名を使用します。 これは、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"
#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 コマンドレットは、文字列データ内で、# で始まる行をコメントとして扱います。 詳細については、以下を参照してください。
メモ
ブロック コメントを入れ子にすることはできません。 次の例では、
Bazはコメントの一部ではありません。<# 'Foo' <# 'Bar' #> 'Baz' #><# #>は、1 行のコメント内で特別な意味を持つ必要はありません。#はブロック コメント内で特別な意味を持っていません。コメントとして扱うには、コメント文字をコメント以外のトークンの一部にすることはできません。 次の例では、
#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 [...]
PowerShell