パラメーター情報を追加する方法

[アーティクル]
12/09/2021

このセクションでは、コマンドレットのヘルプトピックの PARAMETERS セクションに表示されるコンテンツを追加する方法について説明します。ヘルプ トピック の PARAMETERS セクションには、コマンドレットの各パラメーターの一覧と、各パラメーターの詳細な説明が記載されています。

PARAMETERS セクションの 内容は 、ヘルプトピックの SYNTAX セクションの内容と一致している必要があります。 [構文] ノードと [パラメーター] ノードの両方に同様のXML 要素が含まれているのは、ヘルプ作成者の責任です。

注意

ヘルプファイルの完全なビューを表示するには、PowerShell インストールディレクトリにある dll-Help.xml ファイルのいずれかを開きます。たとえば、ファイル Microsoft.PowerShell.Commands.Management.dll-Help.xml には、いくつかの PowerShell コマンドレットの内容が含まれているとします。

パラメーターを追加するには

コマンドレットのヘルプファイルを開き、 文書化するコマンドレット の [コマンド] ノードを探します。新しいコマンドレットを追加する場合は、新しいコマンドノードを作成する必要があります。ヘルプファイルには、ヘルプコンテンツを提供するコマンドレットごとにコマンドノードが含まれる。空のコマンドノードの例を次に示します。
```
<command:command>
</command:command>
```
[コマンド ] ノード 内で[説明] ノードを見 つけ、次に示すように [パラメーター ] ノードを追加します。 [パラメーター ] ノード は 1 つのみ許可され、[構文] ノードの直後に 続く必要 があります。
```
<command:command>
  <command:details></command:details>
  <maml:description></maml:description>
  <command:syntax></command:syntax>
  <command:parameters>
  </command:parameters>
</command:command>
```
[パラメーター] ノード内で、次に示すように、コマンドレットの各パラメーターにパラメーターノードを追加します。

この例では 、3 つのパラメーター に対してパラメーターノードが追加されています。
```
<command:parameters>
  <command:parameter></command:parameter>
  <command:parameter></command:parameter>
  <command:parameter></command:parameter>
</command:parameters>
```
これらは [構文] ノードで使用される XML タグと同じであり、ここで指定するパラメーターは [構文] ノードで指定されたパラメーターと一致する必要があります。ため、 [構文]ノードから [パラメーター] ノードをコピーし、 [パラメーター] ノードに貼り付けます。ただし、パラメーターが構文の複数のパラメーターセットで指定されている場合でも、 パラメーター ノードのインスタンスを必ず 1 つコピーしてください。

[パラメーター] ノードごとに、各パラメーターの特性を定義する属性値を設定します。これらの属性には、required、globbing、pipelineinput、および position が含 まれます。

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
  </command:parameter>
  <command:parameter required="false" globbing="false"
           pipelineInput="false" position="named">
  </command:parameter>
  <command:parameter required="false" globbing="false"
           pipelineInput="false" position="named" ></command:parameter>
</command:parameters>

[パラメーター ] ノード ごとに、パラメーターの名前を追加します。パラメーターノードに追加されるパラメーター名の例を次に示します。

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Add parameter name...  </maml:name>
  </command:parameter>
</command:parameters>

[パラメーター ] ノード ごとに、パラメーターの説明を追加します。パラメーターノードに追加されるパラメーターの説明の例を次に示します。

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Add parameter name...  </maml:name>
    <maml:description>
      <maml:para> Add parameter description... </maml:para>
    </maml:description>
  </command:parameter>
</command:parameters>

[パラメーター ] ノード ごとに、パラメーターの .NET 型を追加します。パラメーターの型は、パラメーター名と共に表示されます。

パラメーターノードに追加されたパラメーター .NET 型の例を次に示します。

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Add parameter name...  </maml:name>
    <maml:description>
      <maml:para> Add parameter description... </maml:para>
    </maml:description>
    <dev:type> Add .NET Framework type... </dev:type>
  </command:parameter>
</command:parameters>

[パラメーター ] ノード ごとに、パラメーターの既定値を追加します。コンテンツが表示される際に、パラメーターの説明に次の文が追加されます 。DefaultValue が既定値です。

パラメーターの既定値が [パラメーター] ノードに追加される例を次に示します。

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Add parameter name...  </maml:name>
    <maml:description>
      <maml:para> Add parameter description... </maml:para>
    </maml:description>
    <dev:type> Add .NET Framework type... </dev:type>
    <dev:defaultvalue> Add default value...</dev:defaultvalue>
  </command:parameter>
</command:parameters>

複数の値を持つパラメーターごとに 、possibleValues ノードを追加 します。

パラメーターの 2 つの可能な値を定義する possibleValues ノードのの例を次に示します。

<dev:possibleValues>
  <dev:possibleValue>
    <dev:value>Unknown</dev:value>
    <maml:description>
      <maml:para></maml:para>
    </maml:description>
  </dev:possibleValue>
  <dev:possibleValue>
    <dev:value>String</dev:value>
    <maml:description>
      <maml:para></maml:para>
    </maml:description>
  </dev:possibleValue>
</dev:possibleValues>

パラメーターを追加するときに覚えておく必要があるいくつかのことを次に示します。

パラメーターの属性は、コマンドレットのヘルプトピックのすべてのビューには表示されません。ただし、ユーザーがトピックの完全 ( ) ビューまたはパラメーター ( ) ビューを求めるときに、パラメーターの説明の後の Get-Help <cmdletname> -Full Get-Help <cmdletname> -Parameter 表に表示されます。
パラメーターの説明は、コマンドレットのヘルプトピックの最も重要な部分の 1 つです。説明は簡単で、詳細である必要があります。また、2 つのパラメーターが相互に対話する場合など、パラメーターの説明が長すぎる場合は、コマンドレットのヘルプトピックの NOTES セクションでコンテンツを追加できます。

パラメーターの説明には、2 種類の情報があります。
パラメーターが使用される場合のコマンドレットの動作。
パラメーターの法的な値は何か。
パラメーター値は .NET オブジェクトとして表されます。そのため、ユーザーは、従来のコマンドラインヘルプよりもこれらの値に関するより多くの情報を必要とします。パラメーターが受け入れ可能に設計されているデータの種類をユーザーに伝え、例を含める。

パラメーターの既定値は、コマンドラインでパラメーターが指定されていない場合に使用される値です。既定値は省略可能であり、必須パラメーターなど、一部のパラメーターには必要ありません。ただし、ほとんどの省略可能なパラメーターには既定値を指定する必要があります。

既定値は、パラメーターを使用しない場合の影響をユーザーが理解するのに役立ちます。省略可能なパスの "現在のディレクトリ" や "PowerShell インストールディレクトリ ( )" など、既定値を具体的 $PSHOME に説明します。 PassThru パラメーターに使用される次の文など、既定値を記述する文を記述することもできます。"PassThru が指定されていない場合、コマンドレットはパイプラインの下にオブジェクトを渡しません。また、この値はフィールド名 Default value の逆に表示されます。この場合、エントリに "既定値" という用語を含める必要があります。

パラメーターの既定値は、コマンドレットのヘルプトピックのすべてのビューには表示されません。ただし、ユーザーがトピックの完全 ( ) ビューまたはパラメーター ( ) ビューを求めるときに、パラメーターの説明に従って(パラメーター属性と共に) テーブルに Get-Help <cmdletname> -Full Get-Help <cmdletname> -Parameter 表示されます。

次の XML は、ノードに <dev:defaultValue> 追加されたタグのペアを示 <command:parameter> しています。既定値は、終了タグ (パラメーター値が指定されている場合) またはパラメーターの説明の終了タグの直後 </command:parameterValue> </maml:description> に続きます。 name:

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Parameter name </maml:name>
    <maml:description>
      <maml:para> Parameter Description </maml:para>
    </maml:description>
    <command:parameterValue required="true">
      Value
    </command:parameterValue>
    <dev:defaultValue> Default parameter value </dev:defaultValue>
  </command:parameter>
</command:parameters>

列挙型の値を追加する

パラメーターに列挙型の複数の値または値がある場合は、省略可能なノードを使用 <dev:possibleValues> できます。このノードを使用すると、複数の値の名前と説明を指定できます。

列挙値の説明は、コマンドレットによって表示される既定のヘルプビューには表示されませんが、他のヘルプビューアーでは、このコンテンツがビューに表示される Get-Help 場合があります。

次の XML は、2 つの <dev:possibleValues> 値が指定されたノードを示しています。

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Parameter name </maml:name>
    <maml:description>
      <maml:para> Parameter Description </maml:para>
    </maml:description>
    <command:parameterValue required="true">
      Value
    </command:parameterValue>
    <dev:defaultValue> Default parameter value </dev:defaultValue>
    <dev:possibleValues>
      <dev:possibleValue>
        <dev:value> Value 1 </dev:value>
        <maml:description>
          <maml:para> Description 1 </maml:para>
        </maml:description>
      <dev:possibleValue>
      <dev:possibleValue>
        <dev:value> Value 2 </dev:value>
        <maml:description>
          <maml:para> Description 2 </maml:para>
        </maml:description>
      <dev:possibleValue>
    </dev:possibleValues>
  </command:parameter>
</command:parameters>

パラメーター情報を追加する方法

パラメーターを追加するには

フィードバック