コマンドレットの説明を追加する方法

Note

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

このセクションでは、コマンドレット ヘルプの DESCRIPTION セクションに表示されるコンテンツを追加する方法について説明します。 ヘルプ ファイルでは、このコンテンツが各コマンドレットの コマンド ノードに追加されます。

Note

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

説明を追加するには

<maml:description> ノードには、コマンドレットの詳細な説明が含まれています。 この要素には、1 つ以上の <maml:para> 要素が含まれています。 説明は、 <maml:para> 要素で囲まれています。 次の例は、XML の構造を示しています。

<maml:description>
  <maml:para>...</maml:para>
</maml:description>

ヒントの作成

  • まず、コマンドレットの基本的な機能について詳しく説明します。 多くの場合、コマンドレット名で使用される用語を説明し、例を使用して未知の概念を示すことができます。 たとえば、コマンドレットがファイルにデータを追加する場合は、既存のファイルの末尾にデータを追加することを説明します。

  • コマンドレットのすべての機能を見つけるには、パラメーターの一覧を確認します。 コマンドレットの主な関数について説明し、その他の関数と機能を含めます。 たとえば、コマンドレットの main 関数が 1 つのプロパティを変更する場合、コマンドレットはすべてのプロパティを変更できます。たとえば、詳細な説明を参照してください。 コマンドレット パラメーターを使用して、ユーザーがさまざまな方法で情報を要請できるようにする場合は、説明します。

  • 明確な使用方法に加えて、ユーザーがコマンドレットを使用する方法に関する情報を含めます。 たとえば、Get-Host コマンドレットが取得するオブジェクトを使用して、Windows PowerShell コマンド ウィンドウのテキストの色を変更できます。

    例: " Get-Acl コマンドレットは、ファイルまたはリソースのセキュリティ記述子を表すオブジェクトを取得します。 セキュリティ記述子には、リソースのアクセス制御リスト (ACL) が含まれています。 ACL は、ユーザーとユーザー グループがリソースにアクセスするために必要なアクセス許可を指定します。

  • 詳細な説明ではコマンドレットを記述する必要がありますが、コマンドレットで使用される概念については説明しないでください。 概念の定義を追加のメモに配置します。

こちらもご覧ください

Windows PowerShell SDK

  • Last updated on