戻り値の型
「戻り値の型」はコマンドレットを実行して返される値の型についての説明を記述します。「戻り値の型」セクションを作成するには下記フォーマットを使用します。
<command:returnValues> <command:returnValue> <dev:type> <maml:name>型名</maml:name> <maml:uri/> <maml:description> <maml:para>説明</maml:para> </maml:description> </dev:typt> <maml:description></maml:description> </command:returnValue> </command:returnValues>
以上をふまえて下記のように作成します。
<command:returnValues> <command:returnValue> <dev:type> <maml:name>String</maml:name> <maml:uri/> <maml:description> <maml:para>書き込み成功可否のメッセージを表示します</maml:para> </maml:description> </dev:type> <maml:description></maml:description> </command:returnValue> </command:returnValues>
注釈
注釈はコマンドレットの詳細/技術情報の参照方法などを記述します。「注釈」セクションを作成するには下記フォーマットを使用します。
<maml:alertSet> <maml:title></maml:title> <maml:alert> <maml:para>メッセージ</maml:para> <maml:para></maml:para> </maml:alert> </maml:alertSet>
以上をふまえて下記のように作成します。
<maml:alertSet> <maml:title></maml:title> <maml:alert> <maml:para>詳細を参照するには、「Get-Help Add-EventEntry -detailed」と入力してください。 技術情報を参照するには、「Get-Help Add-EventEntry -full」と入力してください。</maml:para> </maml:alert> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet>
使用例
コマンドレットヘルプには使用例を含めることができます。
使用例に含めることができるのは、タイトル、プロンプト文字(PS >など)、実際のコマンド例、コマンドの説明、コマンドの出力です。
「使用例」セクションを作成するには下記フォーマットを使用します。
<command:examples> <command:example> <maml:title>タイトル</maml:title> <maml:introduction> <maml:para>プロンプト文字</maml:para> </maml:introduction> <dev:code>使用例</dev:code> <dev:remarks> <maml:para>説明</maml:para> </dev:remarks> </command:example> </command:examples>
「タイトル」は、他のコマンドレットヘルプに倣って、"-------------------------- 例 1 --------------------------" のように付けることをお勧めします。
「プロンプト文字」は、特別な意味を持たせる必要がないのであれば、他のコマンドレットヘルプ同様 "C:\PS>"とします。
「説明」は<maml:para>
~</maml:para>
が1段落を表します。複数の段落に分けて記述したい場合は、<dev:remarks>
~</dev:remarks>
の中に必要段落分の<maml:para>
~</maml:para>
を挿入します。
以上をふまえて下記のように作成します。
<command:examples> <command:example> <maml:title> -------------------------- 例 1 -------------------------- </maml:title> <maml:introduction> <maml:para>C:\PS></maml:para> </maml:introduction> <dev:code>Add-EventEntry -SourceName "MyCmdlet" -Message "自作コマンドレットのテスト"</dev:code> <dev:remarks> <maml:para>このコマンドは、イベントログへの書き込みを行います。</maml:para> <maml:para>SourceNameパラメータにはイベント発生元を</maml:para> <maml:para>Messageパラメータには書き込むメッセージを指定します。</maml:para> <maml:para></maml:para> </dev:remarks> </command:example> </command:examples>
関連リンク
関連リンクは、説明をしているコマンドレットと関連のあるコマンドレットの情報を提供します。「関連リンク」セクションを作成するには下記フォーマットを使用します。
<maml:relatedLinks> <maml:navigationLink> <maml:linkText>Get-EventLog</maml:linkText> </maml:navigationLink> </maml:relatedLinks>
以上をふまえて下記のように作成します。
<maml:relatedLinks> <maml:navigationLink> <maml:linkText>Get-EventLog</maml:linkText> </maml:navigationLink> </maml:relatedLinks >
作成したヘルプの使用
ヘルプの作成が完了したら、前回作成したスナップインと同一の場所へ保存します。次にPowerShellを起動し、スナップインの登録を行います(前回の記事を参照)。
作成したヘルプが正常に表示されるかを、
1.パラメータ無し
PS > Get-Help Add-EventEntry
2.パラメータあり(-Detailed)
PS > Get-Help Add-EventEntry -Detailed
3.パラメータあり(-Full)
PS > Get-Help Add-EventEntry -Full
の最低3パターンで試してください。
この際、赤字でエラーが表示された場合は、どこでエラーが発生しているかが記述されていますので、XMLファイルを開き修正を行ってください。
まとめ
今回解説したように、PowerShellコマンドレットのヘルプはXMLファイルで構成されています。ヘルプを構成する各セクションの記述方法さえ理解すれば、難しいものではありません。
この記事をもとに、独自のコマンドレットとそのヘルプ作成に挑戦してみていただければ幸いです。