PowerShell モジュールのヘルプの記述

2021-09-25

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

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

モジュールヘルプの種類

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

コマンドレットのヘルプ。モジュール内のコマンドレットについて説明するヘルプトピックは、コマンドヘルプスキーマを使用する XML ファイルです
プロバイダーヘルプ。モジュール内のプロバイダーについて説明するヘルプトピックは、プロバイダーヘルプスキーマを使用する XML ファイルです。
関数のヘルプ。モジュール内の関数を記述するヘルプトピックには、関数内のコマンドヘルプスキーマまたはコメントベースのヘルプトピックを使用する XML ファイル、またはスクリプトまたはスクリプトモジュールを指定できます。
スクリプトヘルプ。モジュール内のスクリプトを記述するヘルプトピックには、スクリプトまたはスクリプトモジュールのコマンドヘルプスキーマまたはコメントベースのヘルプトピックを使用する XML ファイルを指定できます。
概念 ("About") ヘルプ。概念 ("about") ヘルプトピックを使用して、モジュールとそのメンバーを説明し、メンバーを一緒に使用してタスクを実行する方法を説明できます。概念ヘルプトピックは、Unicode (UTF-8) エンコードを使用したテキストファイルです。ファイル名は、などの形式 about_<name>.help.txt を使用する必要があります about_MyModule.help.txt 。既定では、PowerShell には、これらの概念である About Help トピックの 100 を超える内容が含まれています。これらは次の例のように書式設定されています。
```
TOPIC
    about_<subject or module name>

SHORT DESCRIPTION
    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.

KEYWORDS
    Terms or titles on which you might expect your users to search for the information in this topic.

SEE ALSO
    Text-only references for further reading. Hyperlinks cannot work in the PowerShell console.
```

すべてのスキーマファイルは、フォルダーにあります $PSHOME\Schemas\PSMaml 。

モジュールヘルプの配置

コマンドレット 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 $HOME\Documents\Modules $PSHOME\Modules を表します。

モジュールのヘルプの取得

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

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

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

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

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

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

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

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

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

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

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

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

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

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