PowerShell のヘルプの種類

PowerShell ヘルプ システムでは、2 種類のヘルプがサポートされています。

• 概念とユースケースシナリオを説明する概念的なヘルプ記事。
• コマンドレット、関数、およびスクリプトの構文と使用法を説明するコマンド ヘルプ記事。

PlatyPS モジュールは、モジュールの PowerShell ヘルプ ファイルを作成してパッケージ化するのに役立ちます。

概念 ("about") ヘルプテキストファイル

概念 ("概要") ヘルプ記事では、モジュールとそのメンバー (コマンドや変数など) について説明し、メンバーを一緒に使用してタスクを実行する方法について説明します。 ヘルプ記事 について はプレーンテキストファイルです。 PlatyPS モジュールはこれらのファイルの作成には役立ちませんが、更新可能なヘルプをサポートするモジュールのコマンド ヘルプ ファイルでパッケージ化できます。

概念的なヘルプ記事の作成の詳細については、「 PowerShell モジュールのヘルプの作成」を参照してください。

コマンドのヘルプ記事

コマンドのヘルプ記事では、コマンドレット、関数、およびスクリプトの構文と使用法について説明します。 コマンドヘルプは、次の 2 つの方法で実装できます。

• スクリプトまたは関数に埋め込まれたコメントベースのヘルプ。
• 外部 XML ファイルに格納された XML ベースのヘルプ。

コメントベースのコマンドヘルプ

PowerShell スクリプトと関数の場合は、スクリプトまたは関数のソース ファイルにコメント ベースのヘルプを直接記述できます。 コメント ベースのヘルプでは、PowerShell が認識する特別なコメント キーワードが使用されます。 PowerShell は、 Get-Help コマンドレットによるプレゼンテーションのために、スクリプトまたは関数からコメントベースのヘルプを抽出します。 コメントベースのヘルプ記事の作成の詳細については、次の記事を参照してください。

• about_Comment_Based_Help。
• ヘルプ Comment-Based 書く

XML ベースのコマンド ヘルプ

PowerShell ヘルプ システムは、Microsoft Assistance Markup Language (MAML) 形式で記述されたヘルプ ファイルもサポートしています。 MAML は、ヘルプ ドキュメントの作成に使用される XML ベースのスキーマです。 MAML は、バイナリ モジュールに実装されているコマンドレットのヘルプを作成する唯一の方法です。 また、これは、更新可能なヘルプをサポートするモジュールに必要な形式です。

MAML を使用して、スクリプトと関数のヘルプを作成できます。 ただし、コメント・ベースのヘルプは、 .EXTERNALHELP comment キーワードを使用しない限り、両方のタイプのヘルプが存在する場合、XML ベースのヘルプよりも優先されます。 .EXTERNALHELP comment キーワードが存在する場合、Get-Help コメントで指定されたヘルプ ファイルが見つからない場合でも、コメント ベースのヘルプよりも優先.EXTERNALHELP。 XML ベースのヘルプ記事の作成の詳細については、「 コマンドレット ヘルプ ファイルを作成する方法」を参照してください。

手書きの MAML は面倒でエラーが発生しやすいです。 PlatyPS モジュールを使用すると、コマンド ドキュメントを Markdown で記述し、MAML 形式にコンパイルできます。 PlatyPS の使用の詳細については、「 PlatyPS を使用して新しい Markdown ヘルプを作成する」を参照してください。