Windows PowerShell 独自コマンドレットの開発（2）

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

ヘルプの各項目の作成

　基本となる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>