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

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

コマンドレットのヘルプの例について理解しておくべきこと

パラメーター名が省略可能な場合でも、コマンド内のすべてのパラメーター名を一覧表示します。これにより、ユーザーがコマンドを簡単に解釈できるようになります。
PowerShell で動作する場合でも、エイリアスと部分的なパラメーター名は避けてください。
この例では、コマンドの構築のための有理数について説明します。特定のパラメーターと値を選択した理由、および変数の使用方法について説明します。
コマンドで式を使用する場合は、詳細について説明します。
コマンドでオブジェクトのプロパティとメソッド (特に既定の表示に表示されないプロパティ) を使用する場合は、オブジェクトについてユーザーに通知する機会として例を使用します。

例を表示するヘルプビュー

例は、コマンドレットのヘルプの詳細ビューと完全ビューでのみ表示されます。

例ノードの追加

次の XML は、1つの例のノードを含む例ノードを追加する方法を示しています。トピックに含める例ごとに、その他の例のノードを追加します。

<command:examples>
  <command:example>
  </command:example>
</command:examples>

例のタイトルの追加

次の XML は、この例の タイトル を追加する方法を示しています。 タイトル は、例を他の例とは別に設定するために使用されます。 PowerShell では、連番のサンプル番号を含む標準ヘッダーが使用されます。

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
  </command:example>
</command:examples>

追加 (前の文字を)

次の XML は、Windows PowerShell プロンプトなどの文字を追加する方法を示しています。これは、例のコマンドの直前に表示されます (スペースは不要です)。 PowerShell では、Windows PowerShell プロンプトを使用 C:\PS> します。

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:Introduction>
      <maml:paragraph>C:\PS></maml:paragraph>
    </maml:Introduction>
</command:example>
</command:examples>

コマンドの追加

次の XML は、例の実際のコマンドを追加する方法を示しています。コマンドを追加するときに、コマンドレットとパラメーターの名前全体 (エイリアスを使用しない) を入力します。また、可能な限り小文字を使用します。

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:Introduction>
      <maml:paragraph>C:\PS></maml:paragraph>
    </maml:Introduction>
    <dev:code> command </dev:code>
</command:example>
</command:examples>

説明の追加

次の XML は、この例の説明を追加する方法を示しています。 PowerShell では、 <maml:para> 複数のタグを使用できる場合でも、説明のために1つのタグセットが使用され <maml:para> ます。

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:Introduction>
      <maml:paragraph>C:\PS></maml:paragraph>
    </maml:Introduction>
    <dev:code> command </dev:code>
    <dev:remarks>
      <maml:para> command description </maml:para>
    </dev:remarks>
</command:example>
</command:examples>

出力例の追加

次の XML は、コマンドの出力を追加する方法を示しています。コマンドの結果情報は省略可能ですが、場合によっては、特定のパラメーターを使用した場合の影響を示すのに役立ちます。 PowerShell では、コマンドの <maml:para> 出力をコマンドから分離するために、2つの空白タグのセットを使用します。

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:Introduction>
      <maml:paragraph>C:\PS></maml:paragraph>
    </maml:Introduction>
    <dev:code> command </dev:code>
    <dev:remarks>
      <maml:para> command description </maml:para>
      <maml:para></maml:para>
      <maml:para></maml:para>
      <maml:para> command output </maml:para>
</dev:remarks>
</command:example>
</command:examples>

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