トピック
about_Comment_Based_Help
簡易説明
関数およびスクリプトに関するコメントベースのヘルプ トピックを記述する方法について説明します。
詳細説明
特別なヘルプのコメント キーワードを使用して、関数およびスクリプトに関するコメントベースのヘ
ルプ トピックを記述することができます。
Get-Help コマンドレットでは、XML ファイルから生成されるコマンドレットのヘルプ トピックを表
示する場合と同じ形式でコメントベースのヘルプが表示されます。ユーザーは、Get-Help の
Detailed、Full、Example、Online などのすべてのパラメーターを使用して、関数およびスクリ
プトのヘルプを表示することができます。
また、ヘルプのコメント キーワードを使用して、スクリプトおよび関数に関する XML ベースのヘル
プ ファイルを記述したり、別のヘルプ ファイルにユーザーをリダイレクトすることもできます。
このトピックでは、関数およびスクリプトに関するヘルプ トピックを記述する方法について説明しま
す。関数およびスクリプトに関するヘルプ トピックを表示する方法については、「Get-Help」を参
照してください。
コメントベースのヘルプの構文
コメントベースのヘルプの構文は次のとおりです。
# .< help keyword>
# <help content>
- または -
<#
.< help keyword>
< help content>
#>
コメントベースのヘルプは、一連のコメントとして記述されます。各コメント行の前にコメント記号
(#) を入力することも、"<#" と "#>" 記号を使用してコメント ブロックを作成することもできま
す。コメント ブロック内のすべての行はコメントとして解釈されます。
コメントベースのヘルプ トピックにある行はすべて、連続している必要があります。ヘルプ トピッ
クの一部ではないコメントに続けてコメントベースのヘルプ トピックを記述する場合は、ヘルプで
はないコメントの最終行とコメントベースのヘルプの先頭の間に、少なくとも 1 行の空白行が必要
です。
キーワードは、コメントベースのヘルプの各セクションを定義します。各コメントベースのヘルプ
キーワードの前にはドット (.) を付けます。キーワードは任意の順で記述することができます。キー
ワード名の大文字と小文字は区別されません。
たとえば、関数またはスクリプトの説明の前には、Description キーワードを記述します。
<#
.Description
Get-Function は、セッションにあるすべての関数の名前および構文を表示します。
#>
コメント ブロックには少なくとも 1 つのキーワードが含まれている必要があります。EXAMPLE な
どの一部のキーワードは、同じコメント ブロックに何度も指定することができます。各キーワードの
ヘルプの内容は、キーワードの次の行から開始して複数行に記述できます。
関数のコメントベースのヘルプの構文
関数に関するコメントベースのヘルプは、次に示す 3 つの位置のいずれかに指定することができます。
-- 関数本体の先頭。
-- 関数本体の末尾。
-- Function キーワードの前。関数のヘルプの最終行と Function キーワードとの間に複数の
空白行を挿入することはできません。
次にその例を示します。
function MyFunction
{
<#
.< help keyword>
< help content>
#>
<function commands>
}
- または -
function MyFunction
{
<function commands>
<#
.< help keyword>
< help content>
#>
}
- または -
<#
.< help keyword>
< help content>
#>
function MyFunction { }
スクリプトのコメントベースのヘルプの構文
スクリプトに関するコメントベースのヘルプは、次に示すスクリプト内の 2 つの位置のいずれかに指
定することができます。
-- スクリプト ファイルの先頭。スクリプト内でスクリプトのヘルプより前に配置できるのは、コメ
ントおよび空白行のみです。
-- (ヘルプの後の) スクリプト本文の最初の項目が関数宣言である場合は、スクリプトのヘルプの末
尾と関数宣言との間に、少なくとも 2 行の空白行が必要です。そうしないと、このヘルプがスク
リプトに関するヘルプではなく、関数に関するヘルプとして解釈されます。
-- スクリプト ファイルの末尾。
次にその例を示します。
<#
.< help keyword>
< help content>
#>
function MyFunction { }
- または -
function MyFunction { }
<#
.< help keyword>
< help content>
#>
コメントベースのヘルプ キーワード
有効なコメントベースのヘルプ キーワードを以下に示します。この一覧は、ヘルプ トピックでの
一般的な出現順に、各キーワードの使用目的を説明しています。これらのキーワードは、コメント
ベースのヘルプに任意の順序で記述することができます。大文字と小文字は区別されません。
.SYNOPSIS
関数またはスクリプトの簡単な説明です。このキーワードは、各トピックで 1 回のみ使用する
ことができます。
.DESCRIPTION
関数またはスクリプトの詳細な説明です。このキーワードは、各トピックで 1 回のみ使用する
ことができます。
.PARAMETER <Parameter-Name>
パラメーターの説明です。関数またはスクリプトの構文で、各パラメーターに対して Parameter
キーワードを入れることができます。
Parameter キーワードは、コメント ブロック内で任意の順序で記述することができますが、
パラメーター (およびその説明) がヘルプ トピックで表示される順序はその関数またはスクリプ
トの構文によって決定されます。順序を変更するには、構文を変更します。
また、関数またはスクリプトの構文で、パラメーター変数名の直前にコメントを配置することによって、
パラメーターの説明を記述することもできます。構文のコメントと Parameter キーワードの両方を使用
した場合、Parameter キーワードに関連付けられている説明が使用され、構文のコメントは無視されます。
.EXAMPLE
関数またはスクリプトを使用したサンプル コマンドです。オプションでサンプル出力および説
明を記述します。それぞれの例に対してこのキーワードを記述します。
.INPUTS
関数またはスクリプトにパイプすることができるオブジェクトの Microsoft .NET Framework 型
です。入力オブジェクトの説明を含めることもできます。
.OUTPUTS
コマンドレットによって返されるオブジェクトの .NET Framework 型です。返されるオブジェク
トの説明を含めることもできます。
.NOTES
関数またスクリプトに関する追加情報です。
.LINK
関連トピックの名前です。それぞれの関連トピックに対してこのキーワードを記述します。
この内容は、ヘルプ トピックの「関連するリンク」セクションに表示されます。
Link キーワードの内容には、同じヘルプ トピックのオンライン バージョンの URI (Uniform
Resource Identifier) を含めることもできます。オンライン バージョンは、Get-Help の
Online パラメーターを使用すると開きます。URI は、"http" または "https" から開始する
必要があります。
.COMPONENT
関数またはスクリプトで使用されているか、関数またはスクリプトに関連するテクノロジまたは
機能です。この内容は、Get-Help コマンドに Get-Help の Component パラメーターが含まれ
ている場合に表示されます。
.ROLE
ヘルプ トピックのユーザー ロールです。この内容は、Get-Help コマンドに Get-Help の
Role パラメーターが含まれている場合に表示されます。
.FUNCTIONALITY
関数の使用目的です。この内容は、Get-Help コマンドに Get-Help の Functionality パラメー
ターが含まれている場合に表示されます。
.FORWARDHELPTARGETNAME <Command-Name>
指定されたコマンドのヘルプ トピックにリダイレクトします。関数、スクリプト、コマンド
レット、プロバイダーに関するヘルプ トピックなど、任意のヘルプ トピックにユーザーをリ
ダイレクトすることができます。
.FORWARDHELPCATEGORY <Category>
ForwardHelpTargetName 内の項目のヘルプ カテゴリを指定します。
有効な値は、Alias、Cmdlet、HelpFile、Function、Provider、General、FAQ、Glossary、
ScriptCommand、ExternalScript、Filter、または All です。このキーワードを使用して、
同じ名前のコマンドがある場合の競合を回避します。
.REMOTEHELPRUNSPACE <PSSession-variable>
ヘルプ トピックが含まれているセッションを指定します。PSSession が含まれている変数を
入力します。このキーワードは、エクスポートされたコマンドのヘルプ トピックを検索する
ために、Export-PSSession コマンドレットによって使用されます。
.EXTERNALHELP <XML Help File Path>
スクリプトまたは関数に関する XML ベースのヘルプ ファイルのパスを指定します。
Windows Vista およびそれ以降の Windows では、指定された XML ファイルのパスに UI カル
チャ固有のサブディレクトリが含まれていると、Get-Help はそれらのサブディレクトリを再帰
的に検索し、スクリプトまたは関数の名前を持つ XML ファイルを探します。これは、Windows
Vista で導入された言語のフォールバック基準に従って、すべての XML ベースのヘルプ トピッ
クの場合と同じように行われます。
コマンドレット ヘルプの XML ベースのヘルプ ファイル形式の詳細については、MSDN
(Microsoft Developer Network) ライブラリの「コマンドレット ヘルプの記述方法 (英語
ページの可能性があります)」(https://go.microsoft.com/fwlink/?LinkID=123415) を参照
してください。
自動生成コンテンツ
名前、構文、パラメーター一覧、パラメーター属性テーブル、共通パラメーター、および注釈は、
Get-Help コマンドレットによって自動生成されます。
名前:
関数のヘルプ トピックの「名前」セクションは、関数構文の関数名から取得されます。
スクリプトのヘルプ トピックの名前は、スクリプト ファイル名から取得されます。名前
または大文字と小文字の区別を変更するには、関数構文またはスクリプト ファイル名を
変更します。
構文:
ヘルプ トピックの「構文」セクションは、関数またはスクリプトの構文から生成されます。
ヘルプ トピックの構文にパラメーターの .NET Framework 型などの詳細を追加するには、
構文に詳細を追加します。パラメーターの型を指定しない場合、"Object" 型が既定値とし
て挿入されます。
パラメーター一覧:
ヘルプ トピックのパラメーター一覧は、関数またはスクリプトの構文と、Parameter キー
ワードを使用して追加した説明から生成されます。関数パラメーターは、関数またはスクリ
プトの構文に出現するのと同じ順序で、ヘルプ トピックの「パラメーター」セクションに
表示されます。また、パラメーター名のスペルおよび大文字と小文字の区別も構文から取得
され、Parameter キーワードによって指定されたパラメーター名の影響は受けません。
共通パラメーター:
共通パラメーターは、効果がない場合でも、ヘルプ トピックの構文とパラメーター一覧に
追加されます。共通パラメーターの詳細については、「about_CommonParameters」を参照し
てください。
パラメーター属性テーブル:
Get-Help の Full または Parameter パラメーターを使用すると、Get-Help でパラメーター
属性のテーブルが生成され、表示されます。必須、位置、および既定値の属性の値は、関数
またはスクリプトの構文から取得されます。
注釈:
ヘルプ トピックの「注釈」セクションは、関数名またはスクリプト名から自動生成されま
す。内容を変更したり、内容に影響を与えることはできません。
例
例 1: 関数のコメントベースのヘルプ
次のサンプル関数には、コメントベースのヘルプが含まれます。
function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
$name = $name + "." + $extension
$name
<#
.SYNOPSIS
指定した名前にファイル名拡張子を追加します。
.DESCRIPTION
指定した名前にファイル名拡張子を追加します。ファイル名または拡張子に任意の文字列を
指定できます。
.PARAMETER Name
ファイル名を指定します。
.PARAMETER Extension
拡張子を指定します。既定値は "Txt" です。
.INPUTS
なし。オブジェクトを Add-Extension にパイプすることはできません。
.OUTPUTS
System.String。Add-Extension は、拡張子の付いた文字列 (ファイル名) を返します。
.EXAMPLE
C:\PS> extension -name "File"
File.txt
.EXAMPLE
C:\PS> extension -name "File" -extension "doc"
File.doc
.EXAMPLE
C:\PS> extension "File" "doc"
File.doc
.LINK
オンライン バージョン: http://www.fabrikam.com/extension.html
.LINK
Set-Item
#>
}
結果は次のとおりです。
C:\PS> get-help add-extension -full
名前
Add-Extension
概要
指定した名前にファイル名拡張子を追加します。
構文
Add-Extension [[-Name] <String>] [[-Extension] <String>]
[<CommonParameters>]
説明
指定した名前にファイル名拡張子を追加します。ファイル名または拡張子に任意の文字列を
指定できます。
パラメーター
-Name
ファイル名を指定します。
必須 false
位置 0
既定値
パイプライン入力を許可する false
ワイルドカード文字を許可する
-Extension
拡張子を指定します。既定値は "Txt" です。
必須 false
位置 1
既定値
パイプライン入力を許可する false
ワイルドカード文字を許可する
<CommonParameters>
このコマンドレットは、共通パラメーターとして、Verbose、Debug、ErrorAction、
ErrorVariable、WarningAction、WarningVariable、OutBuffer、および OutVariable
をサポートします。詳細については、「get-help about_commonparameters」と入力して
ヘルプを参照してください。
入力
なし。オブジェクトを Add-Extension にパイプすることはできません。
出力
System.String。Add-Extension は、拡張子の付いた文字列 (ファイル名) を返します。
-------------------------- 例 1 --------------------------
C:\PS> extension -name "File"
File.txt
-------------------------- 例 2 --------------------------
C:\PS> extension -name "File" -extension "doc"
File.doc
-------------------------- 例 3 --------------------------
C:\PS> extension "File" "doc"
File.doc
関連するリンク
オンライン バージョン: http://www.fabrikam.com/extension.html
Set-Item
例 2: 関数構文のパラメーターの説明
この例は、関数構文にパラメーターの説明が挿入されている点を除き、前の例と同じです。
この形式は、簡単な説明を記述する場合に最も便利です。
function Add-Extension
{
param
(
[string]
# ファイル名を指定します。
$name,
[string]
# ファイル名拡張子を指定します。既定値は "Txt" です。
$extension = "txt"
)
$name = $name + "."+ $extension
$name
<#
.SYNOPSIS
指定した名前にファイル名拡張子を追加します。
.DESCRIPTION
指定した名前にファイル名拡張子を追加します。ファイル名または拡張子に任意の文字列を指定できます。
.INPUTS
なし。オブジェクトを Add-Extension にパイプすることはできません。
.OUTPUTS
System.String。Add-Extension は、拡張子の付いた文字列 (ファイル名) を返します。
.EXAMPLE
C:\PS> extension -name "File"
File.txt
.EXAMPLE
C:\PS> extension -name "File" -extension "doc"
File.doc
.EXAMPLE
C:\PS> extension "File" "doc"
File.doc
.LINK
オンライン バージョン: http://www.fabrikam.com/extension.html
.LINK
Set-Item
#>
}
例 3: スクリプトのコメントベースのヘルプ
次のサンプル スクリプトには、コメントベースのヘルプが含まれます。
終わりの "#>" と Param ステートメントの間にある空白行に留意してください。Param ステー
トメントを持たないスクリプトでは、ヘルプ トピックの最後のコメントと最初の関数宣言との
間に少なくとも 2 行の空白行が必要です。それらの空白行がない場合、Get-Help はスクリプト
ではなく関数にヘルプ トピックを関連付けます。
<#
.SYNOPSIS
毎月のデータ更新を実行します。
.DESCRIPTION
Update-Month.ps1 スクリプトは、過去 1 か月に生成された新しいデータでレジストリを更新
し、レポートを生成します。
.PARAMETER InputPath
CSV ベースの入力ファイルのパスを指定します。
.PARAMETER OutputPath
CSV ベースの出力ファイルの名前およびパスを指定します。既定では、MonthlyUpdates.ps1
は実行された日付と時刻から名前を生成し、ローカル ディレクトリに出力を保存します。
.INPUTS
なし。オブジェクトを Update-Month.ps1 にパイプすることはできません。
.OUTPUTS
なし。Update-Month.ps1 は出力を生成しません。
.EXAMPLE
C:\PS> .\Update-Month.ps1
.EXAMPLE
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv
.EXAMPLE
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv
-outputPath C:\Reports\2009\January.csv
#>
param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...
次のコマンドはスクリプトのヘルプを取得します。スクリプトは Path 環境変数に指定されている
ディレクトリには格納されていないため、スクリプトのヘルプを取得する Get-Help コマンドで、
スクリプトのパスを指定する必要があります。
PS C:\ps-test> get-help .\update-month.ps1 -full
名前
C:\ps-test\Update-Month.ps1
概要
毎月のデータ更新を実行します。
構文
C:\ps-test\Update-Month.ps1 [-InputPath] <String> [[-
OutputPath] <String>] [<CommonParameters>]
説明
Update-Month.ps1 スクリプトは、過去 1 か月に生成された新しいデータでレジスト
リを更新し、レポートを生成します。
パラメーター
-InputPath
CSV ベースの入力ファイルのパスを指定します。
必須 true
位置 0
既定値
パイプライン入力を許可する false
ワイルドカード文字を許可する
-OutputPath
CSV ベースの出力ファイルの名前およびパスを指定します。既定では、
MonthlyUpdates.ps1 は実行された日付と時刻から名前を生成し、ローカル ディレクト
リに出力を保存します。
必須 false
位置 1
既定値
パイプライン入力を許可する false
ワイルドカード文字を許可する
<CommonParameters>
このコマンドレットは、共通パラメーターとして、Verbose、Debug、ErrorAction、
ErrorVariable、WarningAction、WarningVariable、OutBuffer、および OutVariable
をサポートします。詳細については、「get-help about_commonparameters」と入力して
ヘルプを参照してください。
入力
なし。オブジェクトを Update-Month.ps1 にパイプすることはできません。
出力
なし。Update-Month.ps1 は出力を生成しません。
-------------------------- 例 1 --------------------------
C:\PS> .\Update-Month.ps1
-------------------------- 例 2 --------------------------
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv
-------------------------- 例 3 --------------------------
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath
C:\Reports\2009\January.csv
関連するリンク
例 4: XML ファイルへのリダイレクト
関数およびスクリプトに関する XML ベースのヘルプ トピックを記述することができます。コメ
ントベースのヘルプは実装が簡単ですが、ヘルプの内容全体をより正確に制御する必要がある場
合や、ヘルプ トピックを複数の言語に翻訳する場合は、XML ベースのヘルプが必要になります。
次の例は、Update-Month.ps1 スクリプトの最初の数行を示しています。このスクリプトでは、
ExternalHelp キーワードを使用して、スクリプトに関する XML ベースのヘルプ トピックのパス
を指定します。
# .ExternalHelp C:\MyScripts\Update-Month-Help.xml
param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...
次の例は、関数で ExternalHelp キーワードを使用する方法を示しています。
function Add-Extension
{
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
# .ExternalHelp C:\ps-test\Add-Extension.xml
}
例 5: 別のヘルプ トピックへのリダイレクト
次のコードは、Windows PowerShell の組み込み Help 関数の冒頭からの抜粋です。この関数は、
一度に 1 画面ずつヘルプ テキストを表示します。Help 関数の説明は Get-Help コマンドレッ
トのヘルプ トピックに含まれているため、Help 関数では、ForwardHelpTargetName と
ForwardHelpCategory の各キーワードを使用して、ユーザーを Get-Help コマンドレットのヘル
プ トピックにリダイレクトします。
function help
{
<#
.FORWARDHELPTARGETNAME Get-Help
.FORWARDHELPCATEGORY Cmdlet
#>
[CmdletBinding(DefaultParameterSetName='AllUsersView')]
param(
[Parameter(Position=0, ValueFromPipelineByPropertyName
=$true)] [System.String]
${Name},
...
この機能は次のコマンドで使用されます。
C:\PS> get-help help
名前
Get-Help
概要
Windows PowerShell のコマンドレットと概念に関する情報を表示します。
...
関連項目
about_Functions
about_Functions_Advanced_Parameters
about_Scripts
「コマンドレット ヘルプの記述方法 (英語ページの可能性があります)」
(https://go.microsoft.com/fwlink/?LinkID=123415)