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

[アーティクル]
09/25/2021

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

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

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

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

-Online Get-Helpのしくみ

ユーザーがコマンドのオンラインヘルプトピックを見つけるのを支援するために、コマンドには Online パラメーターがあります。このパラメーターを使用すると、ユーザーの既定のインターネットブラウザーでコマンドのオンラインバージョンのヘルプトピックが Get-Help 開きます。

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

Get-Help Invoke-Command -Online

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

コマンドのヘルプトピック の[関連リンク ] セクションの最初のリンク。ヘルプトピックは、ユーザーのコンピューターにインストールする必要があります。この機能は PowerShell 2.0 で導入されました。
任意 のコマンドの HelpUri プロパティ。 HelpUri プロパティ は、コマンドのヘルプトピックがユーザーのコンピューターにインストールされていない場合でもアクセスできます。この機能は PowerShell 3.0 で導入されました。

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

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

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

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

<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 クラスに追加します。属性の値は、またはで始まる URI である必要 http があります https 。

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

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

高度な関数への HelpUri プロパティの追加

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

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

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

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

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

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

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

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

PowerShell 言語で記述されたワークフローの場合は、を追加します 。ワークフローコードへの ExternalHelp コメントディレクティブ。ディレクティブの値は、またはで始まる URI である必要 http があります https 。

注意

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

次のコードは、を示しています。ワークフローファイル内の ExternalHelp ディレクティブ。

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

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

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