PowerShell HelpFile - about_Comment_Based_Help
 記事記号:[me1520] 初版:2011/May/10

この文書は、Windows PowerShellのヘルプ機能で表示される内容を再構成したものです。

トピック
    about_Comment_Based_Help

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

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

    Get-Help コマンドレットでは、XML ファイルから生成されるコマンドレットのヘル
    プ トピックを表示する場合と同じ形式でコメントベースのヘルプが表示されます。
    ユーザーは、Get-Help の Detailed、Full、Example、Online などのすべてのパラメ
    ーターを使用して、関数およびスクリプトのヘルプを表示することができます。

    また、ヘルプのコメント キーワードを使用して、スクリプトおよび関数に関する XM
    L ベースのヘルプ ファイルを記述したり、別のヘルプ ファイルにユーザーをリダイ
    レクトすることもできます。

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

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

        # .< help keyword>
        # 
 
    - または -

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


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

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

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

    たとえば、関数またはスクリプトの説明の前には、Description キーワードを記述し
    ます。

        <#
	    .Description
            Get-Function は、セッションにあるすべての関数の名前および構文を表示
            します。
        #>

    コメント ブロックには少なくとも 1 つのキーワードが含まれている必要があります。
    EXAMPLE などの一部のキーワードは、同じコメント ブロックに何度も指定すること
    ができます。各キーワードのヘルプの内容は、キーワードの次の行から開始して複数
    行に記述できます。

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

    関数に関するコメントベースのヘルプは、次に示す 3 つの位置のいずれかに指定す
    ることができます。

        -- 関数本体の先頭。

        -- 関数本体の末尾。

        -- Function キーワードの前。関数のヘルプの最終行と Function キーワードと
           の間に複数の空白行を挿入することはできません。

    次にその例を示します。

        function MyFunction
        {
            <#
            .< help keyword>
            < help content>
            #>

            
        }

    - または -

        function MyFunction
        {
            

            <#
            .< 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 キーワードを入れることができます。

        Parameter キーワードは、コメント ブロック内で任意の順序で記述することが
        できますが、パラメーター (およびその説明) がヘルプ トピックで表示される
        順序はその関数またはスクリプトの構文によって決定されます。順序を変更する
        には、構文を変更します。
 
        また、関数またはスクリプトの構文で、パラメーター変数名の直前にコメントを
        配置することによって、パラメーターの説明を記述することもできます。構文の
        コメントと Parameter キーワードの両方を使用した場合、Parameter キーワー
        ドに関連付けられている説明が使用され、構文のコメントは無視されます。

    .EXAMPLE
        関数またはスクリプトを使用したサンプル コマンドです。オプションでサンプ
        ル出力および説明を記述します。それぞれの例に対してこのキーワードを記述し
        ます。

    .INPUTS
        関数またはスクリプトにパイプすることができるオブジェクトの Microsoft .NE
        T Framework 型です。入力オブジェクトの説明を含めることもできます。

    .OUTPUTS
        コマンドレットによって返されるオブジェクトの .NET Framework 型です。返さ
        れるオブジェクトの説明を含めることもできます。

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

    .LINK
        関連トピックの名前です。それぞれの関連トピックに対してこのキーワードを記
        述します。

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

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

    .COMPONENT
        関数またはスクリプトで使用されているか、関数またはスクリプトに関連するテ
        クノロジまたは機能です。この内容は、Get-Help コマンドに Get-Help の Comp
        onent パラメーターが含まれている場合に表示されます。

    .ROLE
        ヘルプ トピックのユーザー ロールです。この内容は、Get-Help コマンドに Ge
        t-Help の Role パラメーターが含まれている場合に表示されます。

    .FUNCTIONALITY
        関数の使用目的です。この内容は、Get-Help コマンドに Get-Help の Function
        ality パラメーターが含まれている場合に表示されます。

    .FORWARDHELPTARGETNAME 
        指定されたコマンドのヘルプ トピックにリダイレクトします。関数、スクリプト、
        コマンドレット、プロバイダーに関するヘルプ トピックなど、任意のヘルプ ト
        ピックにユーザーをリダイレクトすることができます。

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

    .REMOTEHELPRUNSPACE 
        ヘルプ トピックが含まれているセッションを指定します。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) ライブラリの「コマンドレット ヘルプの
        記述方法 (英語ページの可能性があります)」(http://go.microsoft.com/fwlink
        /?LinkID=123415) を参照してください。

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

        名前:
            関数のヘルプ トピックの「名前」セクションは、関数構文の関数名から取
            得されます。スクリプトのヘルプ トピックの名前は、スクリプト ファイル
            名から取得されます。名前または大文字と小文字の区別を変更するには、関
            数構文またはスクリプト ファイル名を変更します。
 
        構文:
            ヘルプ トピックの「構文」セクションは、関数またはスクリプトの構文か
            ら生成されます。ヘルプ トピックの構文にパラメーターの .NET Framework 
            型などの詳細を追加するには、構文に詳細を追加します。パラメーターの型
            を指定しない場合、"Object" 型が既定値として挿入されます。

        パラメーター一覧:
            ヘルプ トピックのパラメーター一覧は、関数またはスクリプトの構文と、P
            arameter キーワードを使用して追加した説明から生成されます。関数パラ
            メーターは、関数またはスクリプトの構文に出現するのと同じ順序で、ヘル
            プ トピックの「パラメーター」セクションに表示されます。また、パラメ
            ーター名のスペルおよび大文字と小文字の区別も構文から取得され、Parame
            ter キーワードによって指定されたパラメーター名の影響は受けません。

        共通パラメーター:
            共通パラメーターは、効果がない場合でも、ヘルプ トピックの構文とパラ
            メーター一覧に追加されます。共通パラメーターの詳細については、「abou
            t_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] ] [[-Extension] ] 
            []
    
        説明
            指定した名前にファイル名拡張子を追加します。ファイル名または拡張子に
            任意の文字列を指定できます。
    
        パラメーター
           -Name
               ファイル名を指定します。
        
               必須                         false
               位置                         0
               既定値                       
               パイプライン入力を許可する   false
               ワイルドカード文字を許可する 
        
           -Extension
               拡張子を指定します。既定値は "Txt" です。
        
               必須                         false
               位置                         1
               既定値                       
               パイプライン入力を許可する   false
               ワイルドカード文字を許可する 
        
            
               このコマンドレットは、共通パラメーターとして、Verbose、Debug、Err
               orAction、ErrorVariable、WarningAction、WarningVariable、OutBuffe
               r、および OutVariable をサポートします。詳細については、「get-hel
               p 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 ベースの出力ファイルの名前およびパスを指定します。既定では、Month
           lyUpdates.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]  [[-
                OutputPath] ] []
    
            説明
                Update-Month.ps1 スクリプトは、過去 1 か月に生成された新しいデー
                タでレジストリを更新し、レポートを生成します。
    
            パラメーター
               -InputPath
                   CSV ベースの入力ファイルのパスを指定します。
        
                   必須                         true
                   位置                         0
                   既定値                       
                   パイプライン入力を許可する   false
                   ワイルドカード文字を許可する 
        
               -OutputPath
                   CSV ベースの出力ファイルの名前およびパスを指定します。既定で
                   は、MonthlyUpdates.ps1 は実行された日付と時刻から名前を生成し、
                   ローカル ディレクトリに出力を保存します。
        
                   必須                         false
                   位置                         1
                   既定値                       
                   パイプライン入力を許可する   false
                   ワイルドカード文字を許可する 

               
                   このコマンドレットは、共通パラメーターとして、Verbose、Debug、
                   ErrorAction、ErrorVariable、WarningAction、WarningVariable、O
                   utBuffer、および 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 コマンドレットのヘルプ トピックに含まれているため、Hel
        p 関数では、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
    「コマンドレット ヘルプの記述方法 (英語ページの可能性があります)」
    (http://go.microsoft.com/fwlink/?LinkID=123415)
	
記事で解説しているパソコンの環境
 基本ソフト: Windows 7
 キーワード: Windows PowerShell、ヘルプ、HelpFile、about_Comment_Based_Help
ご利用数: 1861460
感想・要望・問い合わせは こちら