about_Comment_Based_Help

簡単な説明

関数とスクリプトのコメントベースのヘルプトピックを記述する方法について説明します。

長い説明

特別なヘルプコメントキーワードを使用して、関数およびスクリプトのコメントベースのヘルプトピックを記述できます。

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

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

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

Update-helpおよび update-help コマンドレットは、XML ファイルでのみ機能します。 更新可能なヘルプでは、コメントベースのヘルプトピックはサポートされていません。

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

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

# .<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
}

or

function Get-Function
{
   # function logic

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

or

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

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

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

  • スクリプトファイルの先頭にあります。 スクリプトのヘルプは、コメントと空白行によってのみスクリプトの先頭に配置できます。

    スクリプト本体の最初の項目 (ヘルプの後) が関数宣言の場合、スクリプトヘルプの末尾と関数宣言の間には、少なくとも2つの空白行が必要です。 それ以外の場合、ヘルプは、スクリプトのヘルプではなく、関数のヘルプとして解釈されます。

  • スクリプト ファイルの末尾。 ただし、スクリプトが署名されている場合は、スクリプトファイルの先頭にコメントベースのヘルプを配置します。 スクリプトの末尾は、signature ブロックによって占有されています。

次に例を示します。

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


function Get-Function { }

or

function Get-Function { }

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

スクリプトモジュールのコメントベースのヘルプの構文

スクリプトモジュール .psm1 では、コメントベースのヘルプは、スクリプトの構文ではなく、関数の構文を使用します。 スクリプトの構文を使用して、スクリプトモジュールで定義されているすべての関数のヘルプを提供することはできません。

たとえば、キーワードを使用して .ExternalHelp 、スクリプトモジュール内の関数の XML ベースのヘルプファイルを識別する場合は、各関数にコメントを追加 .ExternalHelp する必要があります。

# .ExternalHelp <XML-file-name>
function <function-name>
{
  ...
}

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

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

.SYNOPSIS

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

.DESCRIPTION

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

.PARAMETER

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

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

.PARAMETER  <Parameter-Name>

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

関数またはスクリプト構文のパラメーター変数名の直前にコメントを配置することで、パラメーターの説明を指定することもできます。 これを機能させるには、少なくとも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 キーワードを繰り返します。

このコンテンツは、ヘルプトピックの「関連リンク」セクションに表示されます。

.Linkキーワードの内容には、同じヘルプトピックのオンラインバージョンの Uniform Resource Identifier (URI) を含めることもできます。 の Get-Help online パラメーターを使用すると、オンラインバージョンが開きます。 URI は先頭に "http" または "https" を付ける必要があります。

.COMPONENT

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

.ROLE

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

.FUNCTIONALITY

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

.FORWARDHELPTARGETNAME

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

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

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

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE

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

# .REMOTEHELPRUNSPACE <PSSession-variable>

.EXTERNALHELP

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

# .EXTERNALHELP <XML Help File>

キーワード .ExternalHelp は、関数またはスクリプトが XML ファイルに文書化されている場合に必要です。 このキーワードを指定しない 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 セクションは、関数構文の関数名から作成されます。 スクリプト ヘルプ トピックの名前は、スクリプトファイル名から取得されます。 名前または大文字化を変更するには、関数の構文またはスクリプトファイル名を変更します。

構文

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

パラメーター リスト

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

共通パラメーター

Common パラメーターは 、効果がない場合でも、ヘルプ トピックの構文とパラメーター リストに追加されます。 共通パラメーターの詳細については、「一般的なパラメーター」を about_CommonParameters

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

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

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

注釈

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

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

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

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 cannot pipe objects to Add-Extension.

.OUTPUTS

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

.EXAMPLE

PS> extension -name "File"
File.txt

.EXAMPLE

PS> extension -name "File" -extension "doc"
File.doc

.EXAMPLE

PS> 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 cannot pipe objects to Add-Extension.

OUTPUTS

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

Example 1

PS> extension -name "File"
File.txt

Example 2

PS> extension -name "File" -extension "doc"
File.doc

Example 3

PS> 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 cannot pipe objects to Add-Extension.

.OUTPUTS

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

.EXAMPLE

PS> extension -name "File"
File.txt

.EXAMPLE

PS> extension -name "File" -extension "doc"
File.doc

.EXAMPLE

PS> 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 cannot pipe objects to Update-Month.ps1.

.OUTPUTS

None. Update-Month.ps1 does not 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 -Path .\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 cannot pipe objects to Update-Month.ps1.

# OUTPUTS

None. Update-Month.ps1 does not 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 { }
...

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

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.
...

関連項目