about_Updatable_Help

  • [アーティクル]

簡単な説明

PowerShell の更新可能なヘルプ システムについて説明します。

詳細な説明

PowerShell には、PowerShell コマンドレットと概念に関する最新のヘルプ トピックにアクセスするためのさまざまな方法が用意されています。

PowerShell 3.0 で導入された更新可能なヘルプ システムは、コマンド ラインで読むことができるように、ローカル コンピューターに常に最新のヘルプ トピックがあることを保証するように設計されています。 これにより、ヘルプ ファイルをダウンロードしてインストールしたり、新しいヘルプ ファイルが利用可能になったときにいつでも更新したりできます。

企業内の複数のコンピューターとインターネットにアクセスできないコンピューターに対して更新されたヘルプを提供するために、更新可能なヘルプを使用すると、ヘルプ ファイルをファイル システム ディレクトリまたはファイル共有にダウンロードし、ファイル共有からヘルプ ファイルをインストールできます。

PowerShell 4.0 では、 HelpInfoUri プロパティは Windows PowerShell リモート処理を介して保持されます。これにより、リモート コンピューターにインストールされているが、必ずしもローカル コンピューターにインストールされていないモジュールに対して Save-Help を使用できます。 PSModuleInfo オブジェクトをディスクまたはリムーバブル メディア (USB ドライブなど) に保存するには、インターネットにアクセスできないコンピューターでExport-Clixmlを実行し、インターネットにアクセスできるコンピューターに PSModuleInfo オブジェクトをインポートしてから、PSModuleInfo オブジェクトでSave-Helpを実行します。 保存されたヘルプは、リムーバブル メディアを使用してリモートの切断されたコンピューターにコピーし、 Update-Help実行してインストールできます。 これらの Save-Help 機能の改善により、ネットワーク アクセスのないコンピューターにヘルプをインストールできます。 新しい Save-Help 機能の使用方法の例については、このトピックの「 ファイル共有からヘルプを更新する方法 を参照してください。

更新可能なヘルプは、コンピューターにヘルプ ファイルがない場合でも、最新のヘルプ トピックとコマンドレットの基本的なヘルプへのオンライン アクセスもサポートします。

PowerShell にはヘルプ ファイルは付属していません。 更新可能なヘルプ機能を使用すると、PowerShell とすべての Windows モジュールに既定で含まれるすべてのコマンドのヘルプ ファイルをインストールできます。

更新可能なヘルプ コマンドレット

  • Update-Help: 最新のヘルプ ファイルをインターネットまたはファイル共有からダウンロードし、ローカル コンピューターにインストールします。

  • Save-Help: インターネットから最新のヘルプ ファイルをダウンロードし、ファイル システム ディレクトリまたはファイル共有に保存します。 コンピューターにヘルプ ファイルをインストールするには、 Update-Helpを使用します。

  • Get-Help: コマンド ラインにヘルプ トピックを表示します。 コンピューター上のヘルプ ファイルからヘルプを取得します。 ヘルプ ファイルがないコマンドレットと関数の自動生成されたヘルプを表示します。 既定のインターネット ブラウザーで、コマンドレット、関数、スクリプト、ワークフローのオンライン ヘルプ トピックを開きます。

自動生成されたヘルプ: ヘルプ ファイルのないヘルプ

コンピューターにコマンドレット、関数、またはワークフローのヘルプ ファイルがない場合は、 Get-Help コマンドレットによって自動生成されたヘルプが表示され、ヘルプ ファイルをダウンロードするかオンラインで読み取るように求められます。

自動生成されたヘルプには、構文とエイリアス、および更新可能なヘルプ コマンドレットの使用方法とオンライン ヘルプ トピックへのアクセス方法を説明する解説が含まれています。

たとえば、次のコマンドは、 Get-Culture コマンドレットの基本的なヘルプを取得します。 出力には、コンピューターにヘルプ ファイルがない場合の Get-Help 表示が表示されます。

Get-Help Get-Culture

NAME
    Get-Culture

SYNTAX
    Get-Culture [<CommonParameters>]

ALIASES
    None

REMARKS
    To get the latest Help content including descriptions and examples
    type: Update-Help.

モジュールのヘルプ ファイル

更新可能なヘルプの最小単位は、モジュールのヘルプです。 モジュール ヘルプには、モジュール内のすべてのコマンドレット、関数、ワークフロー、プロバイダー、スクリプト、および概念に関するヘルプが含まれています。 現在のセッションにインポートされていない場合でも、コンピューターにインストールされているすべてのモジュールのヘルプを更新できます。

モジュール全体のヘルプを更新できますが、個々のコマンドレットのヘルプを更新することはできません。

特定のコマンドレットを含むモジュールを検索するには、次のコマンド形式を使用します。

(Get-Command <cmdlet-name>).ModuleName

たとえば、 Set-ExecutionPolicy コマンドレットを含むモジュールを検索するには、次のように入力します。

(Get-Command Set-ExecutionPolicy).ModuleName

特定のモジュールのヘルプを更新するには、次のように入力します。

Update-Help -Module <ModuleName>

たとえば、Set-ExecutionPolicy コマンドレットを含むモジュールのヘルプを更新するには、次のように入力します。

Update-Help -Module Microsoft.PowerShell.Security

更新可能なヘルプのアクセス許可

ディレクトリ $pshome/Modules内のモジュールのヘルプを更新するには、コンピューターの Administrators グループのメンバーである必要があります。

Administrators グループのメンバーでない場合は、これらのモジュールのヘルプを更新できません。インターネットにアクセスできる場合は、オンラインでヘルプを表示できます。

ディレクトリ内のモジュール $HOME/Documents/PowerShell/Modules または $HOME ディレクトリの他のサブディレクトリにあるモジュールのヘルプを更新する場合、特別なアクセス許可は必要ありません。

Update-Help および Save-Help コマンドレットには、現在のユーザーの明示的な資格情報を提供する UseDefaultCredentials パラメーターがあります。 このパラメーターは、セキュリティで保護されたインターネットの場所にアクセスするために設計されています。

Update-Helpコマンドレットと Save-Help コマンドレットには、リモート コンピューターでコマンドを実行し、3 番目のコンピューター上のファイル共有にアクセスできる Credential パラメーターもあります。 Credential パラメーターは、Update-Helpの SourcePath または LiteralPath パラメーターと、Save-Helpの DestinationPath または LiteralPath パラメーターを使用する場合にのみ有効です。

ヘルプ ファイルをインストールして更新する方法

ヘルプ ファイルを初めてダウンロードしてインストールしたり、コンピューター上のヘルプ ファイルを更新したりするには、 Update-Help コマンドレットを使用します。

Update-Help コマンドレットは、次のタスクを含むすべてのハードワークを実行します。

  • 更新可能なヘルプをサポートするモジュールを決定します。
  • 各モジュールが更新可能なヘルプ ファイルを格納するインターネット上の場所を検索します。
  • コンピューター上の各モジュールのヘルプ ファイルと、各モジュールで使用できる最新のヘルプ ファイルを比較します。
  • インターネットから新しいファイルをダウンロードします。
  • ヘルプ ファイル パッケージのラップを解除します。
  • ファイルが有効なヘルプ ファイルであることを確認します。
  • モジュール ディレクトリの言語固有のサブディレクトリにヘルプ ファイルをインストールします。

新しいヘルプ トピックにアクセスするには、 Get-Help コマンドレットを使用します。 PowerShell を再起動する必要はありません。

更新可能なヘルプをサポートするコンピューター上のすべてのモジュールのヘルプをインストールまたは更新するには、次のように入力します。

Update-Help

特定のモジュールのヘルプを更新するには、Update-Helpの Module パラメーターを追加します。 モジュール名にはワイルドカード文字を使用できます。

たとえば、ServerManager モジュールのヘルプを更新するには、次のように入力します。

Update-Help -Module ServerManager

パラメーターを指定しない場合、 Update-Help 更新プログラムは、セッション内のすべてのモジュールと、更新可能なヘルプをサポートするすべてのインストール済みモジュールに対して役立ちます。 モジュールを含めるためには、PSModulePath 環境変数の値にリストされているディレクトリにモジュールをインストールする必要があります。 これらは、 Get-Module -ListAvailable コマンドによって返されるモジュールでもあります。

Module パラメーターの値が* (すべて) の場合、Update-Helpは更新可能なヘルプをサポートしていないモジュールを含め、インストールされているすべてのモジュールのヘルプの更新を試みます。 このコマンドは、通常、コマンドレットが更新可能なヘルプをサポートしていないモジュールを検出すると、多くのエラーを生成します。

ファイル共有からヘルプを更新する方法

インターネットに接続されていないコンピューターをサポートしたり、企業でのヘルプの更新を制御または合理化したりするには、 Save-Help コマンドレットを使用します。 Save-Help コマンドレットは、インターネットからヘルプ ファイルをダウンロードし、指定したファイル システム ディレクトリに保存します。

Save-Help は、指定されたディレクトリ内のヘルプ ファイルを、各モジュールで使用できる最新のヘルプ ファイルと比較します。 ディレクトリにヘルプ ファイルがない場合、またはモジュールで使用できる新しいヘルプ ファイルがある場合、 Save-Help コマンドレットは新しいファイルをインターネットからダウンロードします。 ただし、ヘルプ ファイルのラップを解除したり、インストールしたりすることはありません。

ファイル システム ディレクトリに保存されたヘルプ ファイルからコンピューターにヘルプ ファイルをインストールまたは更新するには、Update-Help コマンドレットの SourcePath パラメーターを使用します。 Update-Help コマンドレットは、最新のヘルプ ファイルを識別し、ラップを解除して検証し、モジュール ディレクトリの言語固有のサブディレクトリにインストールします。

たとえば、インストールされているすべてのモジュールのヘルプを \\Server\Share ディレクトリに保存するには、次のように入力します。

Save-Help -DestinationPath \\Server\Share

次に、 \\Server\Share ディレクトリからヘルプを更新するには、次のように入力します。

Update-Help -SourcePath \\Server\Share

次の例は、 Save-Help を使用して、ローカル コンピューターにインストールされていないモジュールのヘルプを保存する方法を示しています。 この例では、管理者は Save-Help を実行して、DhcpServer モジュールまたは DHCP サーバーの役割をローカル コンピューターにインストールせずに、インターネットに接続されたクライアント コンピューターから DhcpServer モジュールのヘルプを保存します。

オプション 1: Invoke-Commandを実行してリモート モジュールのPSModuleInfo オブジェクトを取得し、変数に保存して$mし、モジュール名として変数$mを指定して、PSModuleInfo オブジェクトにSave-Helpを実行します。

$invokeCommandSplat = @{
    ComputerName = 'RemoteServer'
    ScriptBlock = { Get-Module -Name DhcpServer -ListAvailable }
}
$m = Invoke-Command @invokeCommandSplat
Save-Help -Module $m -DestinationPath C:\SavedHelp

オプション 2: DHCP サーバー モジュールを実行しているコンピューターを対象とする PSSession を開き、モジュールの PSModuleInfo オブジェクトを取得し、変数$mに保存してから、$m変数に保存されているオブジェクトに対してSave-Helpを実行します。

$s = New-PSSession -ComputerName RemoteServer
$m = Get-Module -PSSession $s -Name DhcpServer -ListAvailable
Save-Help -Module $m -DestinationPath C:\SavedHelp

オプション 3: DHCP サーバー モジュールを実行しているコンピューターを対象とする CIM セッションを開き、モジュールの PSModuleInfo オブジェクトを取得し、それを変数$mに保存し、$m変数に保存されているオブジェクトに対してSave-Helpを実行します。

$c = New-CimSession -ComputerName RemoteServer
$m = Get-Module -CimSession $c -Name DhcpServer -ListAvailable
Save-Help -Module $m -DestinationPath C:\SavedHelp

次の例では、管理者は、ネットワーク アクセス権のないコンピューターに DHCP サーバー モジュールのヘルプをインストールします。

まず、 Export-Clixml を実行して、 PSModuleInfo オブジェクトを共有フォルダーまたはリムーバブル メディアにエクスポートします。

$m = Get-Module -Name DhcpServer -ListAvailable
Export-Clixml -Path E:\UsbDrive\DhcpModule.xml -InputObject $m

次に、リムーバブル メディアをインターネットにアクセスできるコンピューターに転送し、Import-Clixmlを使用して PSModuleInfo オブジェクトをインポートします。 Save-Helpを実行して、インポートされた DhcpServer モジュールのヘルプPSModuleInfo オブジェクトを保存します。

$deserialized_m = Import-Clixml E:\UsbDrive\DhcpModule.xml
Save-Help -Module $deserialized_m -DestinationPath E:\UsbDrive\SavedHelp

最後に、ネットワーク アクセス権のないコンピューターにリムーバブル メディアを返送し、 Update-Helpを実行してヘルプをインストールします。

Update-Help -Module DhcpServer -SourcePath E:\UsbDrive\SavedHelp

パラメーターがない場合、 Save-Help は、セッション内のすべてのモジュールと、更新可能なヘルプをサポートするすべてのインストール済みモジュールのヘルプをダウンロードします。 モジュールを含めるためには、ローカル コンピューターまたはヘルプを保存するリモート コンピューター上の、 $env:PSModulePath 環境変数の値に一覧表示されているディレクトリにモジュールをインストールする必要があります。 これらは、 Get-Help -ListAvailable コマンドを実行して返されるモジュールでもあります。

さまざまな言語でヘルプ ファイルを更新する方法

既定では、 Update-Help コマンドレットと Save-Help コマンドレットは、ローカル コンピューター上の Windows 用に設定されている UI カルチャと言語でヘルプをダウンロードします。 指定したモジュールのヘルプ ファイルがローカル UI カルチャで使用できない場合は、 Update-Help および Save-Help Windows 言語フォールバック 規則を使用して、サポートされている最適な言語を見つけます。

ただし、Update-HelpコマンドレットとSave-Help コマンドレットの UICulture パラメーターを使用して、ヘルプ ファイルを使用できる任意の UI カルチャにヘルプ ファイルをダウンロードしてインストールできます。

たとえば、セッション上のすべてのモジュールの最新のヘルプ ファイルを日本語 (ja-Jp) とフランス語 (fr-FR) で保存するには、次のように入力します。

Save-Help -Path \Server\Share -UICulture ja-jp, fr-fr

指定した言語でモジュールのヘルプ ファイルを使用できない場合、 Update-Help コマンドレットと Save-Help コマンドレットは、各モジュールのヘルプが使用可能な言語を一覧表示するエラー メッセージを返します。そのため、ニーズに最も適した代替手段を選択できます。

Note

現在、更新可能なヘルプ コンテンツは英語 (en-US) でのみ公開されています。

オンライン ヘルプの使用方法

ローカル コンピューター上のヘルプ ファイルを更新できない場合、または更新しない場合でも、最新のヘルプ ファイルをオンラインで入手できます。

任意のコマンドレットまたは関数のオンライン ヘルプ トピックを開くには、Get-Help コマンドレットの Online パラメーターを使用します。

たとえば、次のコマンドを実行すると、既定のインターネット ブラウザーで Get-Job コマンドレットのオンライン ヘルプ トピックが開きます。

Get-Help Get-Job -Online

スクリプトのオンライン ヘルプを取得するには、 Online パラメーターとスクリプトの完全なパスを使用します。

Online パラメーターは About トピックでは機能しません。 PowerShell 言語に関するヘルプ トピックなど、PowerShell のトピックについては、「 PowerShell のトピックについてを参照してください。

インターネットのダウンロードを最小限に抑える方法または防止する方法

インターネットのダウンロードを最小限に抑え、インターネットに接続していないユーザーに更新可能なヘルプを提供するには、 Save-Help コマンドレットを使用します。 インターネットからヘルプをダウンロードし、ネットワーク共有に保存します。 次に、すべてのコンピューターで Update-Help コマンドを実行するグループ ポリシー設定またはスケジュールされたジョブを作成します。 Update-Help コマンドレットの SourcePath パラメーターの値をネットワーク共有に設定します。

インターネットにアクセスできるユーザーがインターネットから更新可能なヘルプをダウンロードできないようにするには、 Update-Help グループ ポリシー設定の既定のソース パスを設定します。

このグループ ポリシー設定は、 SourcePath パラメーターを、指定したファイルシステムの場所と共に、影響を受けるすべてのコンピューター上のすべての Update-Help コマンドに暗黙的に追加します。 ユーザーは、 SourcePath パラメーターを明示的に使用して別のファイルシステムの場所を指定できますが、 SourcePath パラメーターを除外してインターネットからヘルプをダウンロードすることはできません。

Note

Update-Help の既定のソース パスを設定しますグループ ポリシー設定は、Computer 構成および User Configuration の下に表示されます。 ただし、 Computer Configuration のポリシー設定のみが有効です。 User Configuration のポリシー設定は無視されます。

詳細については、「about_Group_Policy_Settings」をご覧ください。

標準以外のモジュールのヘルプを更新する方法

Get-Module コマンドレットの ListAvailable パラメーターによって返されないモジュールのヘルプを更新または保存するには、Update-Helpまたは Save-Help コマンドを実行する前に、モジュールを現在のセッションにインポートします。 リモート コンピューターで、 Save-Help コマンドを実行する前に、リモート コンピューターに接続されている現在のセッションまたは Invoke-Command スクリプト ブロックにモジュールをインポートします。

モジュールが現在のセッションにある場合は、パラメーターを指定せずに Update-Help または Save-Help コマンドレットを実行するか、 Module パラメーターを使用してモジュール名を指定します。

Update-HelpおよびSave-Helpコマンドレットの Module パラメーターは、モジュール名のみを受け入れます。 モジュール ファイルへのパスは受け入れられません。

この手法を使用して、Get-Module コマンドレットの ListAvailable パラメーターによって返されないモジュール ($env:PSModulePath環境変数にリストされていない場所にインストールされているモジュール、または整形式ではないモジュール (モジュール ディレクトリに、ディレクトリ名と同じ名前のファイルが少なくとも 1 つ含まれていない) のヘルプを更新または保存します。

更新可能なヘルプをサポートする方法

モジュールを作成する場合は、モジュールのオンライン ヘルプと更新可能なヘルプをサポートできます。 詳細については、「 更新可能なヘルプのサポート と オンライン ヘルプのサポートを参照してください。

更新可能なヘルプは、PowerShell スナップインまたはコメント ベースのヘルプでは使用できません。

解説

Update-HelpコマンドレットとSave-Help コマンドレットは、Windows プレインストール環境 (Windows PE) ではサポートされていません。

関連項目