about_Updatable_Help

簡短描述

描述 PowerShell 中可更新的說明系統。

詳細描述

PowerShell 提供數種不同的方式來存取 PowerShell Cmdlet 和概念的最新說明主題。

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 的範例，請參閱 本主題中的如何從檔案共用 更新說明。

可更新的說明也支援在線存取最新說明主題和 Cmdlet 的基本說明，即使計算機上沒有說明檔案也一般。

PowerShell 未隨附說明檔。 您可以使用可更新的說明功能，針對 PowerShell 和所有 Windows 模組中預設包含的所有命令安裝說明檔。

可更新的說明 Cmdlet

• Update-Help：從因特網或檔案共享下載最新的說明檔，並在本機計算機上安裝它們。

• Save-Help：從因特網下載最新的說明檔，並將其儲存在文件系統目錄或檔案共用中。 若在電腦上安裝說明檔， 請使用 Update-Help。

• Get-Help：在命令行上顯示說明主題。 從電腦上的說明檔取得說明。 針對沒有說明檔案的 Cmdlet 和函式，顯示自動產生的說明。 在預設因特網瀏覽器中開啟 Cmdlet、函式、腳本和工作流程的在線說明主題。

自動產生的說明：沒有說明檔案的說明

如果您沒有電腦上的 Cmdlet、函式或工作流程說明檔， Get-Help Cmdlet 會顯示自動產生的說明，並提示您下載說明檔或在線閱讀。

自動產生的說明包含語法和別名，以及說明如何使用可更新的說明 Cmdlet 以及存取在線說明主題的備註。

例如，下列命令會取得 Cmdlet 的基本說明 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.

模組的說明檔

可更新說明的最小單位是模組的說明。 模組說明包含模組中所有 Cmdlet、函式、工作流程、提供者、腳本和概念的說明。 您可以更新電腦上所安裝之所有模組的說明，即使它們未匯入目前的會話也一樣。

您可以更新整個模組的說明，但無法更新個別 Cmdlet 的說明。

若要尋找包含特定 Cmdlet 的模組，請使用下列命令格式：

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

例如，若要尋找包含 Cmdlet 的 Set-ExecutionPolicy 模組，請輸入：

(Get-Command Set-ExecutionPolicy).ModuleName

若要更新特定模組的說明，請輸入：

Update-Help -Module <ModuleName>

例如，若要更新包含 Set-ExecutionPolicy Cmdlet 之模組的說明，請輸入：

Update-Help -Module Microsoft.PowerShell.Security

可更新說明的許可權

若要更新目錄中 $pshome/Modules模組的說明，您必須是計算機上的 Administrators 群組成員。

如果您不是 Administrators 群組的成員，就無法更新這些模組的說明;但如果您有因特網存取權，則可以在在線檢視說明。

更新目錄中 $HOME/Documents/PowerShell/Modules 模組的說明，或目錄其他子目錄中的 $HOME 模組不需要特殊許可權。

Update-Help和 Save-Help Cmdlet 具有 UseDefaultCredentials 參數，可提供目前使用者的明確認證。 此參數是專為存取安全的因特網位置所設計。

Update-Help和 Save-Help Cmdlet 也有 Credential 參數，可讓您在遠端電腦上執行 命令，並存取第三部電腦上的檔案共用。 只有在您使用 的 Update-Help SourcePath 或 LiteralPath 參數，以及 的 DestinationPath 或 LiteralPath 參數時，Credential 參數才Save-Help有效。

如何安裝和更新說明檔

若要第一次下載並安裝說明檔，或更新電腦上的說明檔，請使用 Update-Help Cmdlet。

Cmdlet Update-Help 會為您執行所有艱苦的工作，包括下列工作。

• 決定哪些模組支援可更新的說明。
• 尋找每個模組儲存其可更新說明檔案的因特網位置。
• 比較您電腦上每個模組的說明檔與每個模組可用的最新說明檔。
• 從因特網下載新檔案。
• 解除包裝說明檔套件。
• 驗證檔案是否為有效的說明檔。
• 在模組目錄的語言特定子目錄中安裝說明檔。

若要存取新的說明主題，請使用 Get-Help Cmdlet。 您不需要重新啟動 PowerShell。

若要安裝或更新支援可更新說明之電腦上所有模組的說明，請輸入：

Update-Help

若要更新特定模組的說明，請新增的Update-HelpModule參數。 模組名稱中允許通配符。

例如，若要更新 ServerManager 模組的說明，請輸入：

Update-Help -Module ServerManager

如果沒有參數， Update-Help 請更新會話中所有模組的說明，以及支援可更新說明的所有已安裝模組。 若要包含，模組必須安裝在 PSModulePath 環境變數值的目錄中。 這些也是命令所 Get-Module -ListAvailable 傳回的模組。

如果Module參數的值是 * （all），Update-Help則嘗試更新所有已安裝模組的說明，包括不支援可更新說明的模組。 此命令通常會產生許多錯誤，因為 Cmdlet 遇到不支援可更新說明的模組。

如何從檔案共用更新說明

若要支援未連線到因特網的計算機，或控制或簡化企業中的協助更新，請使用 Save-Help Cmdlet。 Cmdlet Save-Help 會從因特網下載說明檔案，並將其儲存在您指定的文件系統目錄中。

Save-Help 會將指定目錄中的說明檔與每個模組可用的最新說明檔進行比較。 如果模組沒有說明檔或較新的說明檔，Cmdlet Save-Help 會從因特網下載新檔案。 不過，它不會解除包裝或安裝說明檔。

若要從儲存至文件系統目錄的說明檔安裝或更新電腦上的說明檔，請使用 Cmdlet 的 Update-Help SourcePath 參數。 Cmdlet Update-Help 會識別最新的說明檔、解除包裝及驗證它們，並在模組目錄的語言特定子目錄中安裝它們。

例如，若要將所有已安裝模組的說明儲存到 \\Server\Share 目錄，請輸入：

Save-Help -DestinationPath \\Server\Share

然後，若要從 \\Server\Share 目錄更新說明，請輸入：

Update-Help -SourcePath \\Server\Share

下列範例示範如何使用 Save-Help 來儲存本機計算機上未安裝之模組的說明。 在此範例中，系統管理員會執行 Save-Help ，以從因特網連線的用戶端計算機儲存 DhcpServer 模組的說明，而不需要在本機計算機上安裝 DhcpServer 模組或 DHCP 伺服器角色。

選項 1：執行 Invoke-Command 以取得遠端模組的 PSModuleInfo 物件、將它儲存在變數中，$m然後在 PSModuleInfo 物件上執行Save-Help，方法是將變數$m指定為模組名稱。

$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-ClixmlPSModuleInfo 物件。 執行 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 Cmdlet 會在本機計算機上針對 Windows 設定的 UI 文化特性和語言下載說明。 如果指定模組的說明檔無法在本機UI文化特性中使用， Update-Help 並使用 Save-Help Windows語言後援規則來尋找最佳支持的語言。

不過，您可以使用 和 Save-Help Cmdlet 的 Update-Help UICulture 參數，在可用的任何 UI 文化特性中下載並安裝說明檔。

例如，若要儲存日文 （ja-Jp） 和法文 （fr-FR） 工作階段上所有模組的最新說明檔，請輸入：

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

如果您指定的語言中無法使用模組的說明檔， Update-Help 和 Save-Help Cmdlet 會傳回錯誤訊息，其中列出每個模組可用說明的語言，因此您可以選擇最符合您需求的替代方案。

注意

目前，可更新的說明內容僅以英文發佈（en-US）。

如何使用在線說明

如果您無法或選擇不更新本機計算機上的說明檔，您仍然可以在線取得最新的說明檔。

若要開啟任何 Cmdlet 或函式的在線說明主題，請使用 Cmdlet 的 Get-Help Online 參數。

例如，下列命令會在預設因特網瀏覽器中開啟 Cmdlet 的在線說明主題 Get-Job ：

Get-Help Get-Job -Online

若要取得腳本的在線說明，請使用 Online 參數和腳本的完整路徑。

Online 參數不適用於 About 主題。 若要查看 PowerShell 的相關主題，包括 PowerShell 語言的說明主題，請參閱 PowerShell 關於主題。

如何最小化或防止因特網下載

若要將因特網下載降到最低，並提供可更新的說明給未連線到因特網的使用者，請使用 Save-Help Cmdlet。 從因特網下載說明，並將其儲存至網路共用。 然後，建立組策略設定或排程工作，以在所有計算機上執行 Update-Help 命令。 將 Cmdlet 的 Update-Help SourcePath 參數值設定為網路共用。

若要防止具有因特網存取權的使用者從因特網下載可更新的說明，請使用 設定 Update-Help 組策略設定的預設來源路徑。

此組策略設定會以您指定的檔案系統位置，隱含地將SourcePath參數新增至每個受影響電腦上的每個Update-Help命令。 用戶可以明確地使用 SourcePath 參數來指定不同的文件系統位置，但無法排除 SourcePath 參數，並從因特網下載說明。

注意

[設定 Update-Help 組策略設定的預設來源路徑] 會出現在 [計算機設定] 和 [用戶設定] 底下。 不過，只有 [計算機設定] 底下的原則設定有效。 會忽略 [用戶設定] 底下的原則設定。

如需詳細資訊，請參閱 about_Group_Policy_Settings。

如何更新非標準模組的說明

若要更新或儲存 Cmdlet 之 ListAvailable 參數Get-Module未傳回之模組的說明，請在執行 Update-Help 或 Save-Help 命令之前，將模組匯入目前的會話。 在執行命令之前 Save-Help ，在遠端電腦上，將模組匯入目前會話或 Invoke-Command 腳本區塊，以連線到遠端電腦。

當模組位於目前的會話中時，請執行 Update-Help 或 Save-Help Cmdlet 而不使用參數，或使用 Module 參數來指定模組名稱。

和 Save-Help Cmdlet 的 Update-Help Module 參數只接受模組名稱。 它們不接受模組檔案的路徑。

使用這項技術來更新或儲存 Cmdlet 之 ListAvailable 參數Get-Module未傳回之任何模組的說明，例如安裝在環境變數中未列出的$env:PSModulePath位置的模組，或格式不正確的模組（模組目錄不包含至少一個基底名稱與目錄名稱相同的檔案）。

如何支援可更新的說明

如果您撰寫模組，您可以支援模組的在線說明和可更新的說明。 如需詳細資訊，請參閱 支援可更新的說明 和支援 在線說明。

PowerShell 嵌入式管理單元或批注型說明無法使用可更新的說明。

備註

Update-Help Windows 預安裝環境 （Windows PE） 不支援 和 Save-Help Cmdlet。

另請參閱

• Get-Help
• Save-Help
• Update-Help