次の方法で共有

PowerShell モジュールのヘルプの作成

PowerShell モジュールには、モジュールに関するヘルプ トピックと、コマンドレット、プロバイダー、関数、スクリプトなどのモジュール メンバーに関するヘルプ トピックを含めることができます。 Get-Help コマンドレットは、他の PowerShell 項目のヘルプを表示するのと同じ形式でモジュールのヘルプ トピックを表示し、ユーザーは標準のGet-Help コマンドを使用してヘルプ トピックを取得します。

このドキュメントでは、モジュール ヘルプ トピックの形式と正しい配置について説明し、モジュール ヘルプ コンテンツのガイドラインを示します。

モジュール ヘルプの種類

モジュールには、次の種類のヘルプを含めることができます。

  • XML ベースのヘルプ

    • コマンドレットのヘルプ。 モジュール内のコマンドレットについて説明するヘルプ トピックは、コマンド ヘルプ スキーマを使用する XML ファイルです
    • プロバイダーのヘルプ。 モジュール内のプロバイダーについて説明するヘルプ トピックは、プロバイダー のヘルプ スキーマを使用する XML ファイルです。
    • 関数のヘルプ。 モジュール内の関数について説明するヘルプ トピックは、コマンド ヘルプ スキーマまたは関数内のコメント ベースのヘルプ トピックを使用する XML ファイル、またはスクリプトまたはスクリプト モジュールです。
    • スクリプト ヘルプ。 モジュール内のスクリプトについて説明するヘルプ トピックには、コマンド ヘルプ スキーマを使用する XML ファイルや、スクリプトまたはスクリプト モジュールのコメントベースのヘルプ トピックを使用できます。
    • $PSHOME\Schemas\PSMaml フォルダーには、XML 形式を定義するスキーマ ファイルが含まれています。

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

    概念 ("about") ヘルプ トピックを使用して、モジュールとそのメンバーについて説明し、メンバーを一緒に使用してタスクを実行する方法を説明できます。 既定では、PowerShell には 100 を超えるヘルプ トピックに関する概念が含まれています。 ファイル名には、about_<name>.help.txtなどのabout_MyModule.help.txt形式を使用する必要があります。

    注

    TOPIC セクション ヘッダーは、ファイルの最初の行の最初の列から開始する必要があります。 2 行目のセクションの内容は、 .help.txt サフィックスを付けずにファイル名と一致する必要があります。 コンテンツのインデントは 4 スペースにする必要があります。 3 行目は空白にする必要があります。 SYNOPSIS セクション ヘッダーは、4 行目の最初の列から始まる必要があります。 5 行目のコンテンツは、4 つのスペースにインデントする必要があります。 これらの要件は、 Get-Help コマンドレットがコンテンツを正しく認識するために必要です。

    TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.

    概念的なヘルプ トピックを記述するための開始点として、次のサンプル テンプレートを使用できます。 最初の 2 つのセクションを除き、概念的なヘルプ トピックの構造は任意です。 残りのセクション タイトルは、コンテンツに適した任意のタイトルにすることができます。

    TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.

LONG DESCRIPTION

A detailed, full description of the subject or purpose of the module.

EXAMPLES

Examples of how to use the module or how the subject feature works in
practice.

TROUBLESHOOTING

Instructions for resolving common problems.

SEE ALSO

Text-only references for further reading. Hyperlinks can't work in the
PowerShell console.

    任意のスタイルとマークアップを使用できますが、PowerShell ではプレーン テキストと見なされ、PowerShell コンソールにテキストの特別なレンダリングはありません。 次の推奨事項により、最適な表示結果と読みやすさが保証されます。

    • UTF-8 と BOM エンコードを使用して、特殊な (マルチバイト) 文字が正しく表示されるようにします。
    • セクション ヘッダーに下線を引くか、すべて大文字を使用して目立つようにします。これにより、コンテンツのスキャンが容易になります。
    • 各行の長さを 80 文字に制限します。
    • コード ブロックと出力例をインデントして、周囲の散文から分離します。

モジュール ヘルプの配置

Get-Help コマンドレットは、モジュール ディレクトリの言語固有のサブディレクトリにあるモジュール ヘルプ トピック ファイルを検索します。

たとえば、次のディレクトリ構造図は、SampleModule モジュールのヘルプ トピックの場所を示しています。

<ModulePath>
    \SampleModule
        \<en-US>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml
        \<fr-FR>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml

注

この例では、 <ModulePath> プレースホルダーは、 PSModulePath 環境変数のパスの 1 つ ( $HOME\Documents\Modules、 $PSHOME\Modules、ユーザーが指定するカスタム パスなど) を表しています。

モジュールのヘルプを取得する

ユーザーがモジュールをセッションにインポートすると、そのモジュールのヘルプ トピックがモジュールと共にセッションにインポートされます。 ヘルプ トピック ファイルはモジュール マニフェストの FileList キーの値で一覧表示できますが、ヘルプ トピックは Export-ModuleMember コマンドレットの影響を受けません。

モジュールのヘルプ トピックは、さまざまな言語で提供できます。 Get-Help コマンドレットは、コントロール パネルの [地域と言語のオプション] 項目で現在のユーザーに対して指定された言語で、モジュールのヘルプ トピックを自動的に表示します。 Windows Vista 以降のバージョンの Windows では、 Get-Help は、Windows 用に確立された言語フォールバック標準に従って、モジュール ディレクトリの言語固有のサブディレクトリでヘルプ トピックを検索します。

PowerShell 3.0 以降では、コマンドレットまたは関数に対して Get-Help コマンドを実行すると、モジュールの自動インポートがトリガーされます。 Get-Help コマンドレットは、モジュール内のヘルプ トピックの内容をすぐに表示します。

モジュールにヘルプ トピックが含まれていない場合、ユーザーのコンピューター上のモジュールにコマンドのヘルプ トピックがない場合、 Get-Help は自動生成されたヘルプを表示します。 自動生成されたヘルプには、コマンド構文、パラメーター、入力と出力の種類が含まれますが、説明は含まれません。 自動生成されたヘルプには、 Update-Help コマンドレットを使用してコマンドのヘルプをインターネットまたはファイル共有からダウンロードするようユーザーに指示するテキストが含まれています。 また、 コマンドレットの Get-Help パラメーターを使用して、ヘルプ トピックのオンライン バージョンを取得することもお勧めします。

更新可能なヘルプのサポート

PowerShell 3.0 以降のバージョンの PowerShell のユーザーは、インターネットまたはローカル ファイル共有からモジュールの更新されたヘルプ ファイルをダウンロードしてインストールできます。 Update-Helpコマンドレットと Save-Help コマンドレットでは、管理の詳細がユーザーに表示されなくなります。 ユーザーは Update-Help コマンドレットを実行し、 Get-Help コマンドレットを使用して、PowerShell コマンド プロンプトでモジュールの最新のヘルプ ファイルを読み取ります。 ユーザーは Windows または PowerShell を再起動する必要はありません。

ファイアウォールの背後にあるユーザーやインターネットにアクセスできないユーザーも、更新可能なヘルプを使用できます。 インターネット にアクセスできる管理者は、 Save-Help コマンドレットを使用して、最新のヘルプ ファイルをダウンロードし、ファイル共有にインストールします。 次に、ユーザーは コマンドレットの Update-Help パラメーターを使用して、ファイル共有から最新のヘルプ ファイルを取得します。

モジュール作成者は、モジュールにヘルプ ファイルを含めたり、更新可能なヘルプを使用してヘルプ ファイルを更新したり、モジュールからヘルプ ファイルを省略したり、更新可能なヘルプを使用してインストールと更新の両方を行うことができます。

更新可能なヘルプの詳細については、「更新可能なヘルプ のサポートを参照してください。

オンライン ヘルプのサポート

更新されたヘルプ ファイルをコンピューターにインストールできない、またはインストールできないユーザーは、多くの場合、オンライン バージョンのモジュール ヘルプ トピックに依存します。 コマンドレットの Get-Help パラメーターを使用すると、既定のインターネット ブラウザーで、ユーザーのオンライン バージョンのコマンドレットまたは高度な関数のヘルプ トピックが開きます。

Get-Help コマンドレットは、コマンドレットまたは関数の HelpUri プロパティの値を使用して、ヘルプ トピックのオンライン バージョンを検索します。

PowerShell 3.0 以降では、コマンドレット クラスの HelpUri 属性または CmdletBinding 属性の HelpUri プロパティを定義することで、ユーザーがコマンドレットと関数のヘルプ トピックのオンライン バージョンを見つけるのに役立ちます。 属性の値は、コマンドレットまたは関数の HelpUri プロパティの値です。

詳細については、「 オンライン ヘルプのサポート」を参照してください。

こちらもご覧ください

  • Last updated on