コメントベースのヘルプについて

2025-05-21

簡単な説明

関数とスクリプトのコマンドベースのヘルプコンテンツの記述方法について説明します。

詳細な説明

特別なヘルプコメントキーワードを使用するとx、関数とスクリプトのコメントベースのヘルプコンテンツを記述できます。

Get-Help コマンドレットは、XML ファイルから生成されたコマンドレットヘルプコンテンツを表示するのと同じ形式でコメントベースのヘルプを表示します。ユーザーは、Get-Help、Full、Examples、Online など、のすべてのパラメーターを使用して、コメントベースのヘルプの内容を表示できます。

関数やスクリプト用の XML ベースのヘルプファイルを記述することもできます。 Get-Help コマンドレットで関数またはスクリプトの XML ベースのヘルプファイルを検索できるようにするには、.EXTERNALHELP キーワードを使用します。このキーワードがないと、Get-Help は、関数またはスクリプトの XML ベースのヘルプコンテンツを見つけることはできません。

このトピックでは、関数とスクリプトのヘルプコンテンツを記述する方法について説明します。関数とスクリプトのヘルプコンテンツを表示する方法については、「Get-Help」を参照してください。

Update-Help コマンドレットと Save-Help コマンドレットは XML ファイルでのみ機能します。更新可能なヘルプは、コメントベースのヘルプコンテンツをサポートしていません。

コメントベースのヘルプの構文

コメントベースのヘルプコンテンツを作成するには、コメントのスタイル (1 行コメントまたはブロックコメント) を使用できます。

コメントベースのヘルプの構文は次のとおりです。

# .<help keyword>
# <help content>

または

<#
    .<help keyword>
    <help content>
#>

コメントベースのヘルプは、一連のコメントとして書かれています。コメントの各行の前にコメント記号 # を入力することも、 <# 記号と #> 記号を使用してコメントブロックを作成することもできます。コメントブロック内のすべての行はコメントとして解釈されます。

コメントベースのヘルプトピックのすべての行は連続している必要があります。コメントベースのヘルプトピックがヘルプトピックの一部ではないコメントの後に続く場合は、最後のヘルプ以外のコメント行とコメントベースのヘルプの先頭の間に少なくとも 1 行の空白が必要です。

キーワードは、コメントベースのヘルプの各セクションを定義します。各コメントベースのヘルプキーワードの前にはドット .が付きます。キーワードは任意の順序で表示できます。キーワード名は大文字と小文字を区別しません。

たとえば、 .DESCRIPTION キーワードは、関数またはスクリプトの説明の前に置きます。

<#
.DESCRIPTION
Get-Function displays the name and syntax of all functions in the session.
#>

コメントブロックには、少なくとも 1 つのキーワードが含まれている必要があります。 .EXAMPLEなどの一部のキーワードは、同じコメントブロックに何度も表示されることがあります。各キーワードのヘルプコンテンツは、キーワードの後の行から始まり、複数の行にまたがることができます。

関数でのコメントベースのヘルプの構文

関数のコメントベースのヘルプは、次の 3 つの場所のいずれかに表示できます。

関数本体の先頭。
関数本体の末尾。
function キーワードの前。関数ヘルプの最後の行と function キーワードの間に複数の空白行を指定することはできません。

次に例を示します。

function Get-Function {
    <#
        .<help keyword>
        <help content>
    #>

    # function logic
}

または

function Get-Function {
    # function logic

    <#
        .<help keyword>
        <help content>
    #>
}

または

<#
    .<help keyword>
    <help content>
#>
function Get-Function { }

スクリプトでのコメントベースのヘルプの構文

スクリプトのコメントベースのヘルプは、スクリプト内の次の 2 つの場所のいずれかに表示できます。

スクリプトファイルの先頭。スクリプトのヘルプの前には、コメントと空白行のみを指定できます。

スクリプト本体の最初の項目 (ヘルプの後) が関数宣言である場合は、スクリプトヘルプの末尾と関数宣言の間に少なくとも 2 つの空白行が必要です。それ以外の場合、ヘルプは、スクリプトのヘルプではなく、関数のヘルプとして解釈されます。
スクリプトファイルの末尾。ただし、スクリプトが署名されている場合は、スクリプトファイルの先頭にコメントベースのヘルプを配置します。スクリプトの末尾は、署名ブロックによって占有されます。

次に例を示します。

<#
.<help keyword>
<help content>
#>
function Get-Function { }

または

function Get-Function { }
<#
.<help keyword>
<help content>
#>

コメントベースのヘルプキーワード

有効なコメントベースのヘルプキーワードを次に示します。これらのキーワードはコメントベースのヘルプで任意の順序で表示でき、大文字と小文字は区別されません。キーワードは、ヘルプトピックに通常表示される順序で、この記事に記載されています。

.SYNOPSIS

関数またはスクリプトの簡単な説明。このキーワードは、各トピックで 1 回だけ使用できます。

.DESCRIPTION

関数またはスクリプトの詳細な説明。このキーワードは、各トピックで 1 回だけ使用できます。

.PARAMETER

パラメーターの説明。関数またはスクリプト構文の各パラメーターに .PARAMETER キーワードを追加します。

.PARAMETER キーワードと同じ行にパラメーター名を入力します。 .PARAMETER キーワードの後の行にパラメーターの説明を入力します。 Windows PowerShell では、パラメーターの説明の一部として、 .PARAMETER 行と次のキーワードまたはコメントブロックの末尾の間のすべてのテキストが解釈されます。説明には、段落区切りを含めることができます。

.PARAMETER  <Parameter-Name>

Parameter キーワードはコメントブロック内の任意の順序で表示できますが、関数またはスクリプトの構文によって、ヘルプトピックにパラメーター (およびその説明) が表示される順序が決まります。順序を変更するには、構文を変更します。

パラメーター変数名の直前に関数またはスクリプト構文にコメントを配置して、パラメーターの説明を指定することもできます。これを機能させるには、少なくとも 1 つのキーワードを含むコメントブロックも必要です。

構文コメントと .PARAMETER キーワードの両方を使用する場合、 .PARAMETER キーワードに関連付けられている説明が使用され、構文コメントは無視されます。

<#
.SYNOPSIS
    Short description here
#>
function Verb-Noun {
    [CmdletBinding()]
    param (
        # This is the same as .PARAMETER
        [string]$ComputerName
    )
    # Verb the Noun on the computer
}

`.EXAMPLE`

関数またはスクリプトを使用するサンプルコマンド。必要に応じて、サンプル出力と説明が続きます。各例でこのキーワードを繰り返します。

`.INPUTS`

関数またはスクリプトにパイプ処理できる .NET 型のオブジェクト。入力オブジェクトの説明を含めることもできます。入力の種類ごとにこのキーワードを繰り返します。

`.OUTPUTS`

コマンドレットが返すオブジェクトの .NET 型。返されるオブジェクトの説明を含めることもできます。出力の種類ごとにこのキーワードを繰り返します。

`.NOTES`

関数またはスクリプトに関する追加情報。

`.LINK`

関連トピックの名前。関連トピックごとにこのキーワードを繰り返します。このコンテンツは、ヘルプトピックの [関連リンク] セクションに表示されます。

.LINKキーワードコンテンツには、同じヘルプトピックのオンラインバージョンへの Uri (Uniform Resource Identifier) を含めることもできます。オンラインバージョンは、の Get-Help パラメーターを使用すると開きます。 URI は、 http または httpsで始まる必要があります。

`.COMPONENT`

関数またはスクリプトが使用するテクノロジまたは機能の名前、または関連するテクノロジまたは機能の名前。の Get-Help パラメーターは、この値を使用して、Get-Helpによって返される検索結果をフィルター処理します。

`.ROLE`

ヘルプトピックのユーザーロールの名前。の Get-Help パラメーターは、この値を使用して、Get-Helpによって返される検索結果をフィルター処理します。

`.FUNCTIONALITY`

関数の使用目的を説明するキーワード。の Get-Help パラメーターは、この値を使用して、Get-Helpによって返される検索結果をフィルター処理します。

`.FORWARDHELPTARGETNAME <Command-Name>`

指定したコマンドのヘルプトピックにリダイレクトします。ユーザーは、関数、スクリプト、コマンドレット、プロバイダーのヘルプコンテンツなど、任意のヘルプトピックにリダイレクトできます。

# .FORWARDHELPTARGETNAME <Command-Name>

`.FORWARDHELPCATEGORY`

.FORWARDHELPTARGETNAMEの項目のヘルプカテゴリを指定します。有効な値は、 Alias、 Cmdlet、 HelpFile、 Function、 Provider、 General、 FAQ、 Glossary、 ScriptCommand、 ExternalScript、 Filter、または Allです。同じ名前のコマンドがある場合に競合を回避するには、このキーワードを使用します。

# .FORWARDHELPCATEGORY <Category>

`.REMOTEHELPRUNSPACE <PSSession-variable>`

ヘルプトピックを含むセッションを指定します。 PSSession オブジェクトを含む変数を入力します。このキーワードは、エクスポートされたコマンドのヘルプコンテンツを検索するために、Export-PSSession コマンドレットが使用します。

# .REMOTEHELPRUNSPACE <PSSession-variable>

`.EXTERNALHELP`

スクリプトまたは関数の XML ベースのヘルプファイルを指定します。

# .EXTERNALHELP <XML Help File>

関数またはスクリプトが XML ファイルに記述されている場合は、 .EXTERNALHELP キーワードが必要です。このキーワードがないと、Get-Help は、関数またはスクリプトの XML ベースのヘルプファイルを見つけることはできません。

.EXTERNALHELP キーワードは、他のコメントベースのヘルプキーワードよりも優先されます。 .EXTERNALHELP が存在する場合、Get-Help は、.EXTERNALHELP キーワードの値と一致するヘルプトピックが見つからない場合でも、コメントベースのヘルプを表示しません。

関数がモジュールによってエクスポートされる場合は、 .EXTERNALHELP キーワードの値をパスのないファイル名に設定します。 Get-Help は、モジュールディレクトリの言語固有のサブディレクトリで、指定されたファイル名を検索します。関数の XML ベースのヘルプファイルの名前には要件はありませんが、次の形式を使用することをお勧めします。

<ScriptModule.psm1>-help.xml

関数がモジュールに含まれていない場合は、XML ベースのヘルプファイルへのパスを含めます。値にパスが含まれ、パスに UI カルチャ固有のサブディレクトリが含まれている場合、 Get-Help は、モジュールディレクトリと同様に、Windows 用に確立された言語フォールバック標準に従って、スクリプトまたは関数の名前を持つ XML ファイルを再帰的に検索します。

コマンドレットヘルプの XML ベースのヘルプファイル形式の詳細については、「コマンドレットヘルプ書き込み方法を参照してください。

自動生成されたコンテンツ

名前、構文、パラメーターリスト、パラメーター属性テーブル、共通パラメーター、および注釈は、 Get-Help コマンドレットによって自動的に生成されます。

名前

関数ヘルプトピックの Name セクションは、関数構文の関数名から取得されます。スクリプトヘルプトピックの Name は、スクリプトファイル名から取得されます。名前またはその大文字を変更するには、関数の構文またはスクリプトファイル名を変更します。

構文

ヘルプトピックの Syntax セクションは、関数またはスクリプト構文から生成されます。パラメーターの .NET 型など、ヘルプトピックの構文に詳細を追加するには、構文に詳細を追加します。パラメーター型を指定しない場合は、Object 型が既定値として挿入されます。

パラメーターリスト

ヘルプトピックのパラメーターリストは、関数またはスクリプトの構文と、 .PARAMETER キーワードを使用して追加した説明から生成されます。関数パラメーターは、ヘルプトピックの Parameters セクションに、関数構文またはスクリプト構文と同じ順序で表示されます。パラメーター名のスペルと大文字も構文から取得されます。 .PARAMETER キーワードが指定したパラメーター名の影響は受けません。

共通パラメーター

Common パラメーターは、効果がない場合でも、ヘルプトピックの構文とパラメーターの一覧に追加されます。共通パラメーターの詳細については、 about_CommonParametersを参照してください。

パラメーター属性テーブル

Get-Helpは、の Full または Get-Help パラメーターを使用するときに表示されるパラメーター属性のテーブルを生成します。 Required、Position、および Default 値属性の値は、関数またはスクリプト構文から取得されます。

[ワイルドカード文字を受け入れる] の既定値と値は、関数またはスクリプトで定義されている場合でも、パラメーター属性テーブルには表示されません。ユーザーを支援するには、パラメーターの説明でこの情報を指定します。

解説

ヘルプトピックの Remarks セクションは、関数またはスクリプト名から自動的に生成されます。コンテンツを変更したり、その内容に影響を与えることはできません。

例

関数のコメントベースのヘルプ

次のサンプル関数には、コメントベースのヘルプが含まれています。

function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
$Name = $Name + "." + $Extension
$Name

<#
.SYNOPSIS

Adds a file name extension to a supplied name.

.DESCRIPTION

Adds a file name extension to a supplied name.
Takes any strings for the file name or extension.

.PARAMETER Name
Specifies the file name.

.PARAMETER Extension
Specifies the extension. "Txt" is the default.

.INPUTS

None. You can't pipe objects to Add-Extension.

.OUTPUTS

System.String. Add-Extension returns a string with the extension
or file name.

.EXAMPLE

PS> Add-Extension -Name "File"
File.txt

.EXAMPLE

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

.EXAMPLE

PS> Add-Extension "File" "doc"
File.doc

.LINK

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

結果は次のとおりです。

Get-Help -Name "Add-Extension" -Full

NAME

Add-Extension

SYNOPSIS

Adds a file name extension to a supplied name.

SYNTAX

Add-Extension [[-Name] <String>] [[-Extension] <String>]
[<CommonParameters>]

DESCRIPTION

Adds a file name extension to a supplied name. Takes any strings for the
file name or extension.

PARAMETERS

-Name
Specifies the file name.

Required?                    false
Position?                    0
Default value
Accept pipeline input?       false
Accept wildcard characters?

-Extension
Specifies the extension. "Txt" is the default.

Required?                    false
Position?                    1
Default value
Accept pipeline input?       false
Accept wildcard characters?

<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type
"Get-Help about_CommonParameters".

INPUTS
None. You can't pipe objects to Add-Extension.

OUTPUTS

System.String. Add-Extension returns a string with the extension or
file name.

Example 1

PS> Add-Extension -Name "File"
File.txt

Example 2

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

Example 3

PS> Add-Extension "File" "doc"
File.doc

RELATED LINKS

http://www.fabrikam.com/extension.html
Set-Item

関数構文でのパラメーターの説明

この例は前の例と同じですが、パラメーターの説明が関数構文に挿入される点が異なります。この形式は、説明が簡潔な場合に最も役立ちます。

function Add-Extension
{
param
(

[string]
#Specifies the file name.
$Name,

[string]
#Specifies the file name extension. "Txt" is the default.
$Extension = "txt"
)

$Name = $Name + "." + $Extension
$Name

<#
.SYNOPSIS

Adds a file name extension to a supplied name.

.DESCRIPTION

Adds a file name extension to a supplied name. Takes any strings for the
file name or extension.

.INPUTS

None. You can't pipe objects to Add-Extension.

.OUTPUTS

System.String. Add-Extension returns a string with the extension or
file name.

.EXAMPLE

PS> Add-Extension -Name "File"
File.txt

.EXAMPLE

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

.EXAMPLE

PS> Add-Extension "File" "doc"
File.doc

.LINK

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

スクリプトのコメントベースのヘルプ

次のサンプルスクリプトには、コメントベースのヘルプが含まれています。終了 #> と param ステートメントの間に空白行があることに注意してください。 param ステートメントがないスクリプトでは、ヘルプトピックの最後のコメントと最初の関数宣言の間に少なくとも 2 行の空白が必要です。これらの空白行がない場合、 Get-Help はスクリプトではなく、ヘルプトピックを関数に関連付けます。

<#
.SYNOPSIS

Performs monthly data updates.

.DESCRIPTION

The Update-Month.ps1 script updates the registry with new data generated
during the past month and generates a report.

.PARAMETER InputPath
Specifies the path to the CSV-based input file.

.PARAMETER OutputPath
Specifies the name and path for the CSV-based output file. By default,
MonthlyUpdates.ps1 generates a name from the date and time it runs, and
saves the output in the local directory.

.INPUTS

None. You can't pipe objects to Update-Month.ps1.

.OUTPUTS

None. Update-Month.ps1 doesn't generate any output.

.EXAMPLE

PS> .\Update-Month.ps1

.EXAMPLE

PS> .\Update-Month.ps1 -InputPath C:\Data\January.csv

.EXAMPLE

PS> .\Update-Month.ps1 -InputPath C:\Data\January.csv -OutputPath `
C:\Reports\2009\January.csv
#>

param ([string]$InputPath, [string]$OutputPath)

function Get-Data { }
...

次のコマンドは、スクリプトのヘルプを取得します。スクリプトは、$Env:PATH 環境変数に一覧表示されているディレクトリ内にないため、スクリプトヘルプを取得する Get-Help コマンドでスクリプトパスを指定する必要があります。

Get-Help -Name .\update-month.ps1 -Full

# NAME

C:\ps-test\Update-Month.ps1

# SYNOPSIS

Performs monthly data updates.

# SYNTAX

C:\ps-test\Update-Month.ps1 [-InputPath] <String> [[-OutputPath]
<String>] [<CommonParameters>]

# DESCRIPTION

The Update-Month.ps1 script updates the registry with new data
generated during the past month and generates a report.

# PARAMETERS

-InputPath
Specifies the path to the CSV-based input file.

Required?                    true
Position?                    0
Default value
Accept pipeline input?       false
Accept wildcard characters?

-OutputPath
Specifies the name and path for the CSV-based output file. By
default, MonthlyUpdates.ps1 generates a name from the date
and time it runs, and saves the output in the local directory.

Required?                    false
Position?                    1
Default value
Accept pipeline input?       false
Accept wildcard characters?

<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type,
"Get-Help about_CommonParameters".

# INPUTS

None. You can't pipe objects to Update-Month.ps1.

# OUTPUTS

None. Update-Month.ps1 doesn't generate any output.

Example 1

PS> .\Update-Month.ps1

Example 2

PS> .\Update-Month.ps1 -InputPath C:\Data\January.csv

Example 3

PS> .\Update-Month.ps1 -InputPath C:\Data\January.csv -OutputPath
C:\Reports\2009\January.csv

# RELATED LINKS

XML ファイルへのリダイレクト

関数とスクリプトの XML ベースのヘルプコンテンツを記述できます。コメントベースのヘルプの実装は簡単でも、XML ベースのヘルプには、更新可能なヘルプが必要であり、複数言語でヘルプコンテンツを提供する必要があります。

次の例は、Update-Month.ps1 スクリプトの最初の数行を示しています。スクリプトでは、 .EXTERNALHELP キーワードを使用して、スクリプトの XML ベースのヘルプトピックへのパスを指定します。

.EXTERNALHELP キーワードの値は、キーワードと同じ行に表示されることに注意してください。その他の配置は無効です。

# .EXTERNALHELP C:\MyScripts\Update-Month-Help.xml

param ([string]$InputPath, [string]$OutputPath)
function Get-Data { }
...

次の例は、関数内の .EXTERNALHELP キーワードの 3 つの有効な配置を示しています。

function Add-Extension {
    # .EXTERNALHELP C:\ps-test\Add-Extension.xml

    param ([string] $Name, [string]$Extension = "txt")
    $Name = $Name + "." + $Extension
    $Name
}

function Add-Extension {
    param ([string] $Name, [string]$Extension = "txt")
    $Name = $Name + "." + $Extension
    $Name

    # .EXTERNALHELP C:\ps-test\Add-Extension.xml
}

# .EXTERNALHELP C:\ps-test\Add-Extension.xml
function Add-Extension {
    param ([string] $Name, [string]$Extension = "txt")
    $Name = $Name + "." + $Extension
    $Name
}

別のヘルプトピックへのリダイレクト

次のコードは、PowerShell の組み込みヘルプ関数の先頭からの抜粋であり、一度に 1 つのヘルプテキスト画面が表示されます。 Get-Help コマンドレットのヘルプトピックにはヘルプ関数が記述されているため、ヘルプ関数は.FORWARDHELPTARGETNAMEキーワードと.FORWARDHELPCATEGORYキーワードを使用して、ユーザーを Get-Help コマンドレットのヘルプトピックにリダイレクトします。

function help {
    <#
    .FORWARDHELPTARGETNAME Get-Help
    .FORWARDHELPCATEGORY Cmdlet
    #>

    [CmdletBinding(DefaultParameterSetName='AllUsersView')]
    param(
        [Parameter(Position=0, ValueFromPipelineByPropertyName=$true)]
        [System.String]
        ${Name},
    ...

次のコマンドでは、この機能を使用します。

Get-Help -Name help

NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...

次の方法で共有

コメントベースのヘルプについて

簡単な説明

詳細な説明

コメントベースのヘルプの構文

関数でのコメント ベースのヘルプの構文

スクリプトでのコメント ベースのヘルプの構文

コメントベースのヘルプ キーワード

.SYNOPSIS

.DESCRIPTION

.PARAMETER

.EXAMPLE

.INPUTS

.OUTPUTS

.NOTES

.LINK

.COMPONENT

.ROLE

.FUNCTIONALITY

.FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

.REMOTEHELPRUNSPACE <PSSession-variable>

.EXTERNALHELP