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

2025-03-25

注

XML ベースのヘルプの手動作成は非常に困難です。 PlatyPS モジュールを使用すると、Markdown でヘルプを記述し、それを XML ベースのヘルプに変換できます。これにより、ヘルプの記述と保守がはるかに簡単になります。 PlatyPS では、更新可能なヘルプパッケージを作成することもできます。詳細については、「PlatyPS を使用して XML ベースのヘルプを作成するを参照してください。

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

パラメーター属性

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

パラメーター値の属性

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

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

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

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

構文情報の収集

コマンドレット名から始めます。
```
SYNTAX
    Get-Tech
```
コマンドレットのすべてのパラメーターを一覧表示します。各パラメーター名の前にハイフン (-) を入力します。パラメーターをパラメーターセットに分割します (一部のコマンドレットでは、パラメーターセットが 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 パラメーターなど、列挙のすべての値を一覧表示します。これは、基本 または高度な 設定できます。

前の例の -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>

次の方法で共有

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