次の方法で共有

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

  • [アーティクル]

注

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

PowerShell 3.0 以降では、PowerShell コマンドの Get-Help Online 機能をサポートする 2 つの方法があります。 このトピックでは、さまざまなコマンドの種類に対してこの機能を実装する方法について説明します。

オンライン ヘルプについて

オンライン ヘルプは、常に PowerShell の重要な部分です。 Get-Help コマンドレットはコマンド プロンプトにヘルプ トピックを表示しますが、多くのユーザーは、色分け、ハイパーリンク、コミュニティ コンテンツや Wiki ベースのドキュメントでのアイデアの共有など、オンラインで読むエクスペリエンスを好みます。 最も重要なのは、更新可能なヘルプが登場する前に、オンライン ヘルプによって、ヘルプ ファイルの最新バージョン up-to提供されました。

PowerShell 3.0 で更新可能なヘルプが登場しても、オンライン ヘルプは依然として重要な役割を果たします。 柔軟なユーザー エクスペリエンスに加えて、オンライン ヘルプは、更新可能なヘルプを使用してヘルプ トピックをダウンロードしない、または使用できないユーザーにヘルプを提供します。

Get-Help -Online のしくみ

ユーザーがコマンドのオンライン ヘルプ トピックを見つけられるように、Get-Help コマンドには、ユーザーの既定のインターネット ブラウザーでコマンドのオンライン バージョンのヘルプ トピックを開く Online パラメーターがあります。

たとえば、次のコマンドは、Invoke-Command コマンドレットのオンライン ヘルプ トピックを開きます。

Get-Help Invoke-Command -Online

Get-Help -Onlineを実装するために、Get-Help コマンドレットは、次の場所にあるオンライン バージョンのヘルプ トピックの URI (Uniform Resource Identifier) を検索します。

  • コマンドのヘルプ トピックの 関連リンク セクションの最初のリンク。 ヘルプ トピックは、ユーザーのコンピューターにインストールする必要があります。 この機能は PowerShell 2.0 で導入されました。

  • HelpUri 任意のコマンドのプロパティです。 HelpUri プロパティは、コマンドのヘルプ トピックがユーザーのコンピューターにインストールされていない場合でもアクセスできます。 この機能は、PowerShell 3.0 で導入されました。

    Get-Help、HelpUri プロパティ値を取得する前に、関連リンク セクションの最初のエントリで URI を検索します。 プロパティ値が正しくない場合、または変更された場合は、最初の関連リンクに別の値を入力してオーバーライドできます。 ただし、最初の関連リンクは、ヘルプ トピックがユーザーのコンピューターにインストールされている場合にのみ機能します。

コマンドの XML ベースのヘルプ トピックの 関連リンク セクションの最初のエントリに有効な URI を追加することで、任意のコマンドの Get-Help -Online をサポートできます。 このオプションは XML ベースのヘルプ トピックでのみ有効であり、ヘルプ トピックがユーザーのコンピューターにインストールされている場合にのみ機能します。 ヘルプ トピックがインストールされ、URI が設定されている場合、この値はコマンドの HelpUri プロパティよりも優先されます。

この機能をサポートするには、uri は、maml:relatedLinks 要素の最初の maml:relatedLinks/maml:navigationLink 要素の下の maml:uri 要素に表示する必要があります。

次の XML は、URI の正しい配置を示しています。 maml:linkText 要素の Online version: テキストはベスト プラクティスですが、必須ではありません。

<maml:relatedLinks>
    <maml:navigationLink>
        <maml:linkText>Online version:</maml:linkText>
        <maml:uri>https://go.microsoft.com/fwlink/?LinkID=113279</maml:uri>
    </maml:navigationLink>
    <maml:navigationLink>
        <maml:linkText>about_History</maml:linkText>
        <maml:uri/>
    </maml:navigationLink>
</maml:relatedLinks>

HelpUri プロパティをコマンドに追加する

このセクションでは、HelpUri プロパティをさまざまな種類のコマンドに追加する方法について説明します。

コマンドレットへの HelpUri プロパティの追加

C# で記述されたコマンドレットの場合は、HelpUri 属性を Cmdlet クラスに追加します。 属性の値は、http または httpsで始まる URI である必要があります。

次のコードは、Get-History コマンドレット クラスの HelpUri 属性を示しています。

[Cmdlet(VerbsCommon.Get, "History", HelpUri = "https://go.microsoft.com/fwlink/?LinkID=001122")]

HelpUri プロパティを高度な関数に追加する

高度な関数の場合は、HelpUri プロパティを CmdletBinding 属性に追加します。 プロパティの値は、"http" または "https" で始まる URI である必要があります。

次のコードは、New-Calendar 関数の HelpUri 属性を示しています

function New-Calendar {
    [CmdletBinding(SupportsShouldProcess=$true,
    HelpUri="https://go.microsoft.com/fwlink/?LinkID=01122")]

cim コマンドへの HelpUri 属性の追加

CIM コマンドの場合は、CDXML ファイルの CmdletMetadata 要素に HelpUri 属性を追加します。 属性の値は、http または httpsで始まる URI である必要があります。

次のコードは、Start-Debug CIM コマンドの HelpUri 属性を示しています

<CmdletMetadata Verb="Debug" HelpUri="https://go.microsoft.com/fwlink/?LinkID=001122"/>

ワークフローへの HelpUri 属性の追加

PowerShell 言語で記述されたワークフローの場合は、ワークフロー コードに .EXTERNALHELP コメント キーワードを追加します。 キーワードの値は、http または httpsで始まる URI である必要があります。

注

HelpUri プロパティは、PowerShell の XAML ベースのワークフローではサポートされていません。

次のコードは、ワークフロー ファイル内の .EXTERNALHELP キーワードを示しています。

# .EXTERNALHELP "https://go.microsoft.com/fwlink/?LinkID=138338"