SHOEISHA iD

※旧SEメンバーシップ会員の方は、同じ登録情報(メールアドレス&パスワード)でログインいただけます

CodeZine編集部では、現場で活躍するデベロッパーをスターにするためのカンファレンス「Developers Summit」や、エンジニアの生きざまをブーストするためのイベント「Developers Boost」など、さまざまなカンファレンスを企画・運営しています。

Power Shellを拡張するコマンドレットの作成

Windows PowerShell 独自コマンドレットの開発(2)

独自コマンドレット用ヘルプの作成

  • X ポスト
  • このエントリーをはてなブックマークに追加

戻り値の型

 「戻り値の型」はコマンドレットを実行して返される値の型についての説明を記述します。「戻り値の型」セクションを作成するには下記フォーマットを使用します。

「戻り値の型」セクションのフォーマット
<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ファイルで構成されています。ヘルプを構成する各セクションの記述方法さえ理解すれば、難しいものではありません。

 この記事をもとに、独自のコマンドレットとそのヘルプ作成に挑戦してみていただければ幸いです。

参考文献

修正履歴

この記事は参考になりましたか?

  • X ポスト
  • このエントリーをはてなブックマークに追加
Power Shellを拡張するコマンドレットの作成連載記事一覧
この記事の著者

HIRO(ヒロ)

HIRO's.NETのHIROです。とある半導体工場のSEです。VB.NET, C#, PowerShellによるプログラミングを楽しんでいます。最近はBlog でPowerShellについて書いています。2008/07/07にPowerShell from Japan!!というサイトを立ち上げまし...

※プロフィールは、執筆時点、または直近の記事の寄稿時点での内容です

この記事は参考になりましたか?

この記事をシェア

  • X ポスト
  • このエントリーをはてなブックマークに追加
CodeZine(コードジン)
https://codezine.jp/article/detail/3326 2008/12/15 14:00

おすすめ

アクセスランキング

アクセスランキング

イベント

CodeZine編集部では、現場で活躍するデベロッパーをスターにするためのカンファレンス「Developers Summit」や、エンジニアの生きざまをブーストするためのイベント「Developers Boost」など、さまざまなカンファレンスを企画・運営しています。

新規会員登録無料のご案内

  • ・全ての過去記事が閲覧できます
  • ・会員限定メルマガを受信できます

メールバックナンバー

アクセスランキング

アクセスランキング