SHOEISHA iD

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

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

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

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

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

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

ヘルプの各項目の作成

 基本となるXMLファイルを作成したら、ヘルプの各項目を作成します。

コマンドレット名と概要

 「コマンドレット名と概要」では独自コマンドレット名と概要についての説明を記述します。「コマンドレット名と概要」セクションを作成するには下記フォーマットで作成します。

「コマンドレット名と概要」セクションのフォーマット
<command:details>
  <command:name>コマンドレット動詞部-コマンドレット名詞部</command:name>
  <command:verb>コマンドレット動詞部</command:verb>
  <command:noun>コマンドレット名詞部</command:noun>
  <maml:description>
    <maml:para>概要</maml:para>
  </maml:description>
</command:details>

 Add-EventEntryコマンドレットは動詞部がAdd、名詞部がEventEntry、コマンドレットの説明は「指定したメッセージをイベントログに書き込む」なので、下記のように作成します。

<command:details>
  <command:name>Add-EventEntry</command:name>
  <command:verb>Add</command:verb>
  <command:noun>EventEntry</command:noun>
  <maml:description>
    <maml:para>指定したメッセージをイベントログに書き込む</maml:para>
  </maml:description>
</command:details>

詳細説明

 「詳細説明」では、コマンドレットの詳細説明を記述します。「詳細説明」セクションを作成するには、下記フォーマットを使用します。

「詳細説明」セクションのフォーマット
<maml:description>
  <maml:para>コマンドレット詳細説明</maml:para>
</maml:description>

 詳細説明は「イベント発生元とメッセージを指定してイベントログへの書き込みを行います」とするので、下記のようになります。

<maml:description>
  <maml:para>イベント発生元とメッセージを指定してイベントログへの書き込みを行います</maml:para>
</maml:description>

構文 

 「構文」セクションではコマンドレットの構文を作成します。「構文」セクションを作成するには、下記フォーマットを使用します。

「構文」セクションのフォーマット
<command:syntaxItem>
  <maml:name>Cmdlet-Name</maml:name>
  <command:parameter>
    <maml:name>パラメータ名</maml:name>
    <command:parameterValue>パラメータの型</command:parameterValue>
  </command:parameter>
</command:syntaxItem>

 パラメータを複数持つコマンドレットの場合は、<command:parameter></command:parameter>をコマンドレットの数だけ記述します。
また、<command:parameter><command:parameterValue>には属性が必要です。

<command:parameter>の属性
属性 説明
required trueは省略できないパラメータであることを示します。falseをセットした場合は省略可能なパラメータであることを示します。
globbing パラメータに指定する値にワイルドカードを含めることができる場合はtrueとします。一般的にパラメータの方がStringである場合はtrueを、Int32やSwitchParameter、Enumeration Typeなどはfalseとなります。
pipelineInput パイプラインに値を渡せるパラメータの場合はtrueを、渡せない場合はfalseをセットします。
position 値にnamedを指定した場合には、パラメータ名称を指定する必要があります。数値を指定した場合には、パラメータ名称を入力せずに値だけをコマンドレットに渡すことが可能です。複数のパラメータを指定する場合は、ここで指定した順番にパラメータと値がマッピングされます。
<command:parameterValue>の属性
属性 説明
required trueは省略できないパラメータであることを示します。falseをセットした場合は省略可能なパラメータであることを示します。

 以上をふまえて

Add-EventEntry [-SourceName<String>] [-Message <String>]

 という構文を表示させるためには、

<command:syntax>
  <command:syntaxItem>
    <maml:name>Add-EventEntry</maml:name>
    <command:parameter required="true" globbing="false" pipelineInput="true" position="1">
      <maml:name>SourceName</maml:name>
      <command:parameterValue required="true">string</command:parameterValue>
    </command:parameter>
    <command:parameter required="true" globbing="false" pipelineInput="true" position="2">
      <maml:name>Message</maml:name>
      <command:parameterValue required="true">string</command:parameterValue>
    </command:parameter>
  </command:syntaxItem>
</command:syntax>

 となります。

パラメータ

 「パラメータ」セクションは、各パラメータの説明を記述します。「パラメータ」セクションを作成するには、下記フォーマットを使用します。

「パラメータ」セクションのフォーマット
<command:parameters>
  <command:parameter>
    <maml:name>パラメータ名 </maml:name>
    <maml:description>
      <maml:para>説明</maml:para>
    </maml:description>
    <command:parameterValue required="true"> 
      Value
    </command:parameterValue>
    <dev:defaultValue> Default parameter value </dev:defaultValue>
  </command:parameter>
</command:parameters>

 パラメータも、構文のときと同様にパラメータを複数持つコマンドレットの場合は、<command:parameter></command:parameter>をコマンドレットの数だけ記述します。

 また<command:parameter><command:parameterValue>にも属性が必要です。属性に関しては、「構文」の項を参照してください。

 以上をふまえ、下記のように作成します。

<command:parameters>
  <command:parameter required="true" globbing="false" pipelineInput="true" position="1">
    <maml:name>SourceName</maml:name>
    <maml:description>
      <maml:para>イベントソース名を指定します。</maml:para>  
    </maml:description>
    <command:parameterValue required="true" variableLength="true">string</command:parameterValue>
    <dev:type>
      <maml:name>string</maml:name>
      <maml:uri/>
    </dev:type>
    <dev:defaultValue>なし。イベントソース名を指定する必要があります。</dev:defaultValue>
  </command:parameter>
  <command:parameter required="true" globbing="false" pipelineInput="true" position="1">
    <maml:name>Meessage</maml:name>
    <maml:description>
      <maml:para>書き込むメッセージを指定します。</maml:para>  
    </maml:description>
    <command:parameterValue required="true" variableLength="true">string</command:parameterValue>
    <dev:type>
      <maml:name>string</maml:name>
      <maml:uri/>
    </dev:type>
    <dev:defaultValue>なし。書き込むメッセージを指定する必要があります。</dev:defaultValue>
  </command:parameter>
</command:parameters>

入力の種類

 「入力の種類」はコマンドレットがパイプラインを受け取る値の説明を記述します。「入力の種類」セクションを作成するには下記フォーマットを使用します。

「入力の種類」セクションのフォーマット
<command:inputTypes>
  <command:inputType>
    <dev:type>
      <maml:name>パイプラインで受け取ることが可能なデータの型</maml:name>
      <maml:uri/>
      <maml:description>
        <maml:para>受け取るデータの説明 <maml:para>
      </maml:description>
    </dev:type>
    <maml:description></maml:description>
  </command:inputType>
</command:inputTypes>

 以上をふまえ、下記のように作成します。

<command:inputTypes>
  <command:inputType>
    <dev:type>
      <maml:name>String</maml:name>
      <maml:uri/>
      <maml:description>
        <maml:para>
          <!-- description  -->
          String - コマンド ラインに文字列としてパラメータを入力するか、このコマンドレットにパイプライン経由でオブジェクトを渡すことができます。
        </maml:para>
      </maml:description>
    </dev:type>
    <maml:description></maml:description>
  </command:inputType>
</command:inputTypes>

次のページ
作成したヘルプの使用

修正履歴

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

  • 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」など、さまざまなカンファレンスを企画・運営しています。

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

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

メールバックナンバー

アクセスランキング

アクセスランキング