コマンドレットのヘルプトピックに構文を追加する方法

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

コマンドレットのヘルプファイルで構文図の XML のコード化を開始する前に、このセクションを読んで、パラメーター属性などの指定する必要があるデータの種類と、構文図でのデータの表示方法を明確に確認してください。

パラメーター属性

必須
- true の場合は、パラメーターセットを使用するすべてのコマンドにパラメーターを指定する必要があります。
- false の場合、パラメーターセットを使用するすべてのコマンドでパラメーターは省略可能です。
[位置]
- という名前の場合は、パラメーター名が必要です。
- 位置指定の場合、パラメーター名は省略可能です。省略した場合、パラメーター値はコマンド内の指定した位置にある必要があります。たとえば、値が position="1" の場合、パラメーター値はコマンドの最初のパラメーター値または名前のないパラメーター値のみである必要があります。
パイプライン入力
- true (ByValue) の場合は、パイプ入力をパラメーターに渡します。プロパティ名とオブジェクト型が予期される型と一致しない場合でも、入力はパラメーターに関連付け ("バインド" されます)。 PowerShell パラメーターバインドコンポーネントは、入力を正しい型に変換しようとし、型を変換できない場合にのみコマンドを失敗します。パラメーターセット内の 1 つのパラメーターのみを値で関連付けできます。
- true (ByPropertyName) の場合は、パイプ入力をパラメーターに渡します。ただし、入力は、パラメーター名が入力オブジェクトのプロパティの名前と一致する場合にのみ、パラメーターに関連付けます。たとえば、パラメーター名がの場合、コマンドレットにパイプされたオブジェクトは、オブジェクトに path という名前のプロパティがある場合にのみ、そのパラメーター Path に関連付けます。
- true (ByValue、ByPropertyName) の場合は、パラメーターへのパイプ入力をプロパティ名または値でパイプできます。パラメーターセット内の 1 つのパラメーターのみを値で関連付けできます。
- false の場合、パイプ入力をこのパラメーターに渡す必要があります。
グロブ
- true の場合、ユーザーがパラメーター値に入力するテキストにワイルドカード文字を含めることができます。
- false の場合、ユーザーがパラメーター値に入力するテキストにワイルドカード文字を含めることはできません。

パラメーター値の属性

必須
- true の場合は、コマンドでパラメーターを使用するたびに、指定した値を使用する必要があります。
- false の場合、パラメーター値は省略可能です。通常、値は、列挙型など、パラメーターに対して有効ないくつかの値の 1 つである場合にのみ省略可能です。

パラメーター値の Required 属性は、パラメーターの Required 属性 とは異なります。

パラメーターの必須属性は、コマンドレットを呼び出す際にパラメーター (とその値) を含める必要があるかどうかを示します。これに対し、パラメーター値の必須属性は、パラメーターがコマンドに含まれている場合にのみ使用されます。特定の値をパラメーターと一緒に使用する必要があるかどうかを示します。

通常、プレースホルダーであるパラメーター値は必須であり、リテラルであるパラメーター値は必須ではありません。これは、パラメーターで使用できるいくつかの値の 1 つなのでです。

構文情報の収集

コマンドレット名で始める。
```
SYNTAX
    Get-Tech
```
コマンドレットのすべてのパラメーターを一覧表示します。各パラメーター名の前 - にハイフン ( ) (ASCII 45) を入力します。パラメーターをパラメーターセットに分割します (一部のコマンドレットでは、パラメーターセットが 1 つしか設定されている場合があります)。この例では、Get-Tech 2 つのパラメーターセットがあります。
```
SYNTAX
    Get-Tech -name -type
    Get-Tech -ID -list -type
```
コマンドレット名を使用して、各パラメーターセットを開始します。

最初に既定のパラメーターセットを一覧表示します。既定のパラメーターは、コマンドレットクラスによって指定されます。

パラメーターセットごとに、最初に指定する必要がある位置指定パラメーターがない限り、最初に一意のパラメーターを一覧表示します。前の例では、Name パラメーターと ID パラメーターは 2 つのパラメーターセットの一意のパラメーターです (各パラメーターセットには、そのパラメーターセットに固有のパラメーターが 1 つ必要です)。これにより、ユーザーはパラメーターセットに指定する必要があるパラメーターを簡単に識別できます。

コマンドに表示される順序でパラメーターを一覧表示します。順序が関係ない場合は、関連するパラメーターを一覧表示するか、最も頻繁に使用されるパラメーターを最初に一覧表示します。

コマンドレットで ShouldProcess がサポートされている場合は、WhatIf パラメーターと Confirm パラメーターを必ず一覧表示してください。

構文図では、共通パラメーター (Verbose、Debug、ErrorAction など) を一覧表示しません。コマンドレット Get-Help は、ヘルプトピックを表示するときに、その情報を追加します。
パラメーター値を追加します。 PowerShell では、パラメーター値は .NET 型で表されます。ただし、型名は省略できます (System.String の場合は "string" など)。
```
SYNTAX
    Get-Tech -name string -type basic advanced
    Get-Tech -ID int -list -type basic advanced
```
System.String の文字列や System.Int32 の int など、意味が明確な限り、型を省略します。

前の例のパラメーターなど、列挙型のすべての値を一覧表示します。これは -type 、basic または advanced****に設定 できます。

前の例のようなスイッチ -list パラメーターには値はありません。
リテラルであるパラメーター値と比較して、プレースホルダーであるパラメーター値に角かっこを追加します。
```
SYNTAX
    Get-Tech -name <string> -type basic advanced
    Get-Tech -ID <int> -list -type basic advanced
```

省略可能なパラメーターとその値を角かっこで囲みます。

SYNTAX
    Get-Tech -name <string> [-type basic advanced]
    Get-Tech -ID <int> [-list] [-type basic advanced]

省略可能なパラメーター名 (位置指定パラメーターの場合) は角かっこで囲みます。位置指定パラメーターの名前 (次の例の Name パラメーターなど) は、コマンドに含める必要はありません。
```
SYNTAX
    Get-Tech [-name] <string> [-type basic advanced]
    Get-Tech -ID <int> [-list] [-type basic advanced]
```
パラメーター値に Name パラメーターの名前のリストなど、複数の値を含めできる場合は、パラメーター値の後に角かっこのペアを直接追加します。
```
SYNTAX
    Get-Tech [-name] <string[]> [-type basic advanced]
    Get-Tech -ID <int[]> [-list] [-type basic advanced]
```
ユーザーがパラメーターまたはパラメーター値 (Type パラメーターなど) から選択できる場合は、選択肢を中かっこで囲み、排他的 OR 記号 (;)) で分離します。
```
SYNTAX
    Get-Tech [-name] <string[]> [-type {basic | advanced}]
    Get-Tech -ID <int[]> [-list] [-type {basic | advanced}]
```
パラメーター値で引用符やかっこなどの特定の書式を使用する必要がある場合は、構文で形式を表示します。
```
SYNTAX
    Get-Tech [-name] <"string[]"> [-type {basic | advanced}]
    Get-Tech -ID <int[]> [-list] [-type {basic | advanced}]
```

構文図 XML のコーディング

XML の構文ノードは、説明ノードの直後から始まり、タグで終 </maml:description> わります。構文図で使用されるデータの収集については、「構文情報の収集」を参照してください。

構文ノードの追加

コマンドレットのヘルプトピックに表示される構文図は、XML の構文ノードのデータから生成されます。構文ノードは、タグのペアで囲 <command:syntax> まれます。コマンドレットの各パラメーターセットをタグのペアで囲 <command:syntaxitem> みます。追加できるタグの数 <command:syntaxitem> に制限はありません。

次の例は、2 つのパラメーターセットの構文項目ノードを持つ構文ノードを示しています。

<command:syntax>
  <command:syntaxItem>
    ...
    <!--Parameter Set 1 (default parameter set) parameters go here-->
    ...
  </command:syntaxItem>
  <command:syntaxItem>
    ...
    <!--Parameter Set 2 parameters go here-->
    ...
  </command:syntaxItem>
</command:syntax>

パラメーターセットデータへのコマンドレット名の追加

コマンドレットの各パラメーターセットは、構文項目ノードで指定されます。各構文項目ノードは、コマンドレットの名前を含 <maml:name> むタグのペアで始まります。

次の例には、2 つのパラメーターセットの構文項目ノードを含む構文ノードが含まれています。

<command:syntax>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
</command:syntax>

パラメーターの追加

構文項目ノードに追加される各パラメーターは、タグのペア内で指定 <command:parameter> されます。 PowerShell によって提供される共通パラメーターを除き、パラメーターセットに含まれる各パラメーターのタグ <command:parameter> のペアが必要です。

開始タグの属性によって <command:parameter> 、構文図でのパラメーターの表示方法が決まれます。パラメーター属性の詳細については、「パラメーター属性」を参照してください。

注意

タグ <command:parameter> は、コンテンツが表示 <maml:description> されない子要素をサポートします。パラメーターの説明は、XML のパラメーターノードで指定します。構文項目の情報とパラメーターノードの間の不整合を回避するには、 ( を省略するか <maml:description> 、空のままにします。

次の例には、2 つのパラメーターを持つパラメーターセットの構文項目ノードが含まれています。

<command:syntaxItem>
  <maml:name>Cmdlet-Name</maml:name>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByValue)" position="1">
    <maml:name>ParameterName1</maml:name>
    <command:parameterValue required="true">
      string[]
    </command:parameterValue>
  </command:parameter>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByPropertyName)">
    <maml:name>ParameterName2</maml:name>
    <command:parameterValue required="true">
      int32[]
    </command:parameterValue>
  </command:parameter>
</command:syntaxItem>

コマンドレットのヘルプ トピックに構文を追加する方法