更新可能なヘルプについて
概要
PowerShell の更新可能なヘルプシステムについて説明します。
詳細説明
Powershell には、PowerShell コマンドレットと概念に関する最新のヘルプトピックにアクセスするためのさまざまな方法が用意されています。
PowerShell 3.0 で導入された更新可能なヘルプシステムは、コマンドラインから読み取ることができるように、ローカルコンピューターに常に最新のヘルプトピックがあることを保証するように設計されています。 これにより、ヘルプファイルをダウンロードしてインストールしたり、新しいヘルプファイルが使用可能になるたびに更新したりすることが簡単になります。
企業内の複数のコンピューター、およびインターネットにアクセスできないコンピューターの更新されたヘルプを提供するために、更新可能なヘルプを使用して、ファイルシステムディレクトリまたはファイル共有にヘルプファイルをダウンロードし、ファイル共有からヘルプファイルをインストールすることができます。
PowerShell 4.0 では、HelpInfoUri プロパティが Windows PowerShell リモート処理を介して保持されます。これにより、リモートコンピューターにインストールされているモジュールでは、ローカルコンピューターにインストールされているとは限らないモジュールに対して、保存ヘルプを使用できます。 PSModuleInfo オブジェクトをディスクまたはリムーバブルメディア (USB ドライブなど) に保存するには、インターネットにアクセスできないコンピューターで Export-clixml を実行し、インターネットにアクセスできるコンピューターに PSModuleInfo オブジェクトをインポートしてから、PSModuleInfo オブジェクトで [保存-ヘルプ] を実行します。 保存されているヘルプは、リムーバブルメディアを使用してリモートの切断されたコンピューターにコピーしてから、Update-help を実行してインストールすることができます。 これらの機能強化により、ネットワークアクセスのないコンピューターにヘルプをインストールできるようになりました。 新しい保存ヘルプ機能を使用する方法の例については、このトピックの「ファイル共有からヘルプを更新する方法: 保存-ヘルプ」を参照してください。
更新可能なヘルプは、コンピューター上にヘルプファイルがない場合でも、最新のヘルプトピックへのオンラインアクセスとコマンドレットの基本的なヘルプをサポートします。
PowerShell 3.0 にはヘルプファイルが付属していません。 更新可能なヘルプ機能を使用して、PowerShell およびすべての Windows モジュールに既定で含まれているすべてのコマンドのヘルプファイルをインストールすることができます。
更新可能なヘルプコマンドレット
Update-help: 最新のヘルプファイルをインターネットまたはファイル共有からダウンロードし、ローカルコンピューターにインストールします。
保存-ヘルプ: 最新のヘルプファイルをインターネットからダウンロードし、ファイルシステムディレクトリまたはファイル共有に保存します。 ヘルプファイルをコンピューターにインストールするには、update-help を使用します。
Get-help: コマンドラインにヘルプトピックを表示します。 コンピューター上のヘルプファイルからヘルプを取得します。 ヘルプファイルのないコマンドレットと関数の自動生成されたヘルプを表示します。 既定のインターネットブラウザーでコマンドレット、関数、スクリプト、およびワークフローのオンラインヘルプトピックを開きます。
PowerShell ISE のヘルプを更新する
PowerShell Integrated Scripting Environment (ISE) の [ヘルプ] メニューにある [PowerShell ヘルプの更新] 項目を使用して、ヘルプを更新することもできます。
"PowerShell ヘルプの更新" 項目は、パラメーターを指定せずに update-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 グループのメンバーでない場合は、これらのモジュールのヘルプを更新することはできません。しかし、インターネットにアクセスできる場合は、TechNet ライブラリのヘルプをオンラインで表示できます。
$ホーム \ ドキュメント \ windowspowershell \ modules ディレクトリまたはホームディレクトリの他のサブディレクトリにあるモジュールのヘルプを更新するには、 $ 特別なアクセス許可は必要ありません。
Update-help および UseDefaultCredentials コマンドレットには、現在のユーザーの明示的な資格情報を提供するパラメーターがあります。 このパラメーターは、セキュリティで保護されたインターネット上の場所にアクセスするために設計されて
Update-help コマンドレットと update-help コマンドレットには、リモートコンピューターでコマンドを実行し、3番目のコンピューターのファイル共有にアクセスできる Credential パラメーターもあります。 Credential パラメーターは、Update-help の SourcePath パラメーターまたは LiteralPath パラメーター、または DestinationPath のパラメーターまたは LiteralPath パラメーターを使用する場合にのみ有効です。
ヘルプファイルをインストールおよび更新する方法
ヘルプファイルを初めてダウンロードしてインストールする場合、またはコンピューター上のヘルプファイルを更新する場合は、update-help コマンドレットを使用します。
Update-help コマンドレットは、次のタスクを含むすべてのハードな作業を実行します。
- 更新可能なヘルプをサポートするモジュールを指定します。
- 各モジュールが更新可能なヘルプファイルを格納するインターネット上の場所を検索します。
- コンピューター上の各モジュールのヘルプファイルを、各モジュールで使用可能な最新のヘルプファイルと比較します。
- インターネットから新しいファイルをダウンロードします。
- ヘルプファイルパッケージのラップを解除します。
- ファイルが有効なヘルプファイルであることを確認します。
- モジュールディレクトリの言語固有のサブディレクトリにヘルプファイルをインストールします。
新しいヘルプトピックにアクセスするには、Get-help コマンドレットを使用します。 PowerShell を再起動する必要はありません。
更新可能なヘルプをサポートするコンピュータ上のすべてのモジュールのヘルプをインストールまたは更新するには、次のように入力します。
Update-Help
特定のモジュールのヘルプを更新するには、Update-help の Module パラメーターを追加します。 モジュール名にはワイルドカード文字を使用できます。
たとえば、ServerManager モジュールのヘルプを更新するには、次のように入力します。
Update-Help -Module ServerManager
パラメーターを指定しない場合、Update-help は、セッション内のすべてのモジュールと、更新可能なヘルプをサポートするすべてのインストール済みモジュールのヘルプを更新します。 これを含めるには、PSModulePath 環境変数の値に示されているディレクトリにモジュールをインストールする必要があります。 これらは、"Get-help-ListAvailable" コマンドによって返されるモジュールでもあります。
Module パラメーターの値が * (すべて) の場合、Update-help は、更新可能なヘルプをサポートしていないモジュールを含め、インストールされているすべてのモジュールのヘルプを更新しようとします。 このコマンドは、通常、更新可能なヘルプをサポートしていないモジュールをコマンドレットが検出したときに多くのエラーを生成します。
ファイル共有からヘルプを更新する方法: 保存-ヘルプ
インターネットに接続されていないコンピューターをサポートする場合、または企業内での更新を制御または合理化する場合は、Help コマンドレットを使用します。 Help コマンドレットは、インターネットからヘルプファイルをダウンロードし、指定したファイルシステムディレクトリに保存します。
指定したディレクトリ内のヘルプファイルを、各モジュールで使用可能な最新のヘルプファイルと比較します。 ディレクトリにヘルプファイルがない場合、または新しいヘルプファイルがモジュールに使用できる場合は、Get-help コマンドレットによって、インターネットから新しいファイルがダウンロードされます。 ただし、ヘルプファイルのラップを解除したりインストールしたりすることはありません。
ファイルシステムディレクトリに保存されたヘルプファイルからコンピューターのヘルプファイルをインストールまたは更新するには、Update-help コマンドレットの SourcePath パラメーターを使用します。 Update-help コマンドレットは、最新のヘルプファイルを識別し、ラップを解除して検証し、モジュールディレクトリの言語固有のサブディレクトリにインストールします。
たとえば、インストールされているすべてのモジュールのヘルプをサーバー共有ディレクトリに保存するには、次のように \ \ \ 入力します。
Save-Help -DestinationPath \\Server\Share
次に、サーバー共有ディレクトリからヘルプを更新するには、次のように \ \ \ 入力します。
Update-Help -SourcePath \\Server\Share
次の例では、ローカルコンピューターにインストールされていないモジュールのヘルプを保存するために、[ヘルプ] の使用方法を示しています。 この例では、管理者は、ローカルコンピューターに DhcpServer モジュールまたは DHCP サーバーの役割をインストールせずに、インターネットに接続されているクライアントコンピューターから DhcpServer モジュールのヘルプを保存するために、保存-ヘルプを実行します。
オプション 1: Invoke コマンドを実行してリモートモジュールの PSModuleInfo オブジェクトを取得し、それを変数に保存して $m した後、モジュール名として $m 変数を指定して、PSModuleInfo オブジェクトのを実行します。
$m = Invoke-Command -ComputerName RemoteServer -ScriptBlock
{ Get-Module -Name DhcpServer -ListAvailable }
Save-Help -Module $m -DestinationPath C:\SavedHelp
オプション 2: DHCP サーバーモジュールを実行しているコンピューターを対象とする PSSession を開き、モジュールの PSModuleInfo オブジェクトを取得し、変数 $m に保存した後、$m 変数に保存されているオブジェクトに対して [保存-ヘルプ] を実行します。
$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 変数に保存されているオブジェクトに対して [保存-ヘルプ] を実行します。
$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:\UsbFlashDrive\DhcpModule.xml -InputObject $m
次に、インターネットにアクセスできるコンピューターにリムーバブルメディアを転送し、Export-clixml を使用して PSModuleInfo オブジェクトをインポートします。 [保存-ヘルプを実行して、インポートした DhcpServer module PSModuleInfo オブジェクトのヘルプを保存します。
$deserialized_m = Import-Clixml E:\UsbFlashDrive\DhcpModule.xml
Save-Help -Module $deserialized_m -DestinationPath `
E:\UsbFlashDrive\SavedHelp
最後に、リムーバブルメディアをネットワークにアクセスできないコンピューターに転送してから、update-help を実行してヘルプをインストールします。
Update-Help -Module DhcpServer -SourcePath E:\UsbFlashDrive\SavedHelp
パラメーターを指定しない場合、ヘルプは、セッション内のすべてのモジュールと、更新可能なヘルプをサポートするすべてのインストール済みモジュールのヘルプをダウンロードします。 モジュールを含めるには、PSModulePath 環境変数の値に一覧表示されているディレクトリに、ヘルプを保存するローカルコンピューターまたはリモートコンピューターのモジュールをインストールする必要があります。 これらは、"Get-help-ListAvailable" コマンドを実行して返されるモジュールでもあります。
さまざまな言語のヘルプファイルを更新する方法
既定では、Update-help および help コマンドレットは、ローカルコンピューター上の Windows に設定されている UI カルチャと言語でヘルプをダウンロードします。 指定されたモジュールのヘルプファイルがローカル UI カルチャで使用できない場合、Update-help および update-help は Windows 言語フォールバックルールを使用して、サポートされている最適な言語を見つけます。
ただし、update-help および UICulture コマンドレットのパラメーターを使用して、使用可能な任意の UI カルチャでヘルプファイルをダウンロードしてインストールすることができます。
たとえば、セッションのすべてのモジュールの最新のヘルプファイルを日本語 (Ja-jp) とフランス語 (fr-fr) で保存するには、次のように入力します。
Save-Help -Path \Server\Share -UICulture ja-jp, fr-fr
指定した言語でモジュールのヘルプファイルが使用できない場合は、Update-help コマンドレットによって、各モジュールのヘルプが使用可能な言語を示すエラーメッセージが返されます。これにより、ニーズに最も合った代替手段を選択できます。
ヘルプを自動的に更新する方法
常に最新のヘルプファイルがあることを保証するには、PowerShell プロファイルに update-help コマンドを追加します。
内部クォータを使用すると、Update-help コマンドが1日に複数回実行されるのを防ぐことができます。 1日に1回の最大値を上書きするには、Force パラメーターを使用します。
プロファイルで次のようなコマンドを使用します。 このコマンドは、バックグラウンドジョブにインストールされているすべてのモジュールのヘルプを更新するため、作業には影響しません。 この例では、Out-Null コマンドを使用して、返されるジョブと、1日に複数回コマンドを使用した場合に表示される可能性のあるエラーメッセージを抑制します。
Start-Job {Update-Help} | Out-Null
また、Update-help コマンドレットまたは help コマンドレットを任意の間隔で実行するスケジュールされたジョブを作成することもできます。
たとえば、次のコマンドは、毎週金曜日の 5:00 AM に update-help help コマンドを実行するスケジュールされたジョブを作成します。 このコマンドを実行するには、[管理者として実行] オプションを使用して PowerShell を起動します。
Register-ScheduledJob -Name UpdateHelpJob -ScriptBlock {Update-Help} `
-Trigger (New-JobTrigger -Weekly -DaysOfWeek Friday -At "5:00 AM")
オンラインヘルプの使用方法
ローカルコンピューターのヘルプファイルを更新できない場合、または更新しない場合でも、最新のヘルプファイルをオンラインで取得できます。
コマンドレットまたは関数のオンラインヘルプトピックを開くには、Get-help コマンドレットの Online パラメーターを使用します。
たとえば、次のコマンドは、既定のインターネットブラウザーで、Get-help コマンドレットのオンラインヘルプトピックを開きます。
Get-Help Get-Job -Online
スクリプトのオンラインヘルプを表示するには、Online パラメーターとスクリプトへの完全なパスを使用します。
Online パラメーターは、About トピックでは機能しません。 Powershell 言語に関するヘルプトピックを含む、PowerShell Core の概要に関するトピックについては、 Powershell コアモジュールに関するトピックを参照してください。
インターネットのダウンロードを最小化または禁止する方法
インターネットに接続されていないユーザーに対してインターネットのダウンロードを最小限にし、更新可能なヘルプを提供するには、Get-help コマンドレットを使用します。 インターネットからヘルプをダウンロードし、ネットワーク共有に保存します。 次に、すべてのコンピューターで Update-help コマンドを実行するグループポリシー設定またはスケジュールされたジョブを作成します。 Update-help コマンドレットの SourcePath パラメーターの値をネットワーク共有に設定します。
インターネットアクセス権を持つユーザーがインターネットから更新可能なヘルプをダウンロードできないようにするには、[Update-help の既定のソースパスを設定する] グループポリシー設定を使用します。
このグループポリシー設定は、指定したファイルシステムの場所にある SourcePath パラメーターを、影響を受けるすべてのコンピューターのすべての Update-help コマンドに暗黙的に追加します。 ユーザーは SourcePath パラメーターを明示的に使用して別のファイルシステムの場所を指定できますが、SourcePath パラメーターを除外して、インターネットからヘルプをダウンロードすることはできません。
注: [コンピューターの構成] と [ユーザーの構成] の下に、[Update-help の既定のソースパスを設定する] グループポリシー設定が表示されます。 ただし、[コンピューターの構成] の下のポリシー設定のみが有効です。 [ユーザーの構成] のポリシー設定は無視されます。
詳細については、「about_Group_Policy_Settings」をご覧ください。
標準以外のモジュールのヘルプを更新する方法
Get Module コマンドレットの ListAvailable パラメーターによって返されないモジュールのヘルプを更新または保存するには、Update-Help またはコマンドを実行する前に、現在のセッションにモジュールをインポートします。 リモートコンピューターで、[保存-ヘルプ] コマンドを実行する前に、リモートコンピューターに接続されている現在の CIM または PSSession または Invoke コマンドスクリプトブロックにモジュールをインポートします。
モジュールが現在のセッション内にある場合は、パラメーターを指定せずに update-help または Help コマンドレットを実行するか、Module パラメーターを使用してモジュール名を指定します。
Update-help コマンドレットと update-help コマンドレットの Module パラメーターは、モジュール名のみを受け入れます。 モジュールファイルのパスを受け取ることはできません。
この手法を使用すると、PSModulePath 環境変数に一覧表示されていない場所にインストールされているモジュールや、適切な形式ではないモジュール (モジュールディレクトリには、基本名がディレクトリ名と同じファイルが少なくとも1つ含まれていません) など、ListAvailable コマンドレットのパラメーターによって返されないモジュールのヘルプを更新
更新可能なヘルプをサポートする方法
モジュールを作成する場合は、モジュールのオンラインヘルプと更新可能なヘルプをサポートできます。 詳細については、「更新可能なヘルプのサポート」および「Microsoft Docs でのオンラインヘルプのサポート」を参照してください。
更新可能なヘルプは、PowerShell スナップインやコメントベースのヘルプには使用できません。
REMARKS
Update-Help および Save-Help コマンドレットは、Windows プレインストール環境 (Windows PE) ではサポートされません。