共用方式為


about_Updatable_Help

適用於: Windows PowerShell 3.0

主題

About_Updatable_Help

簡短描述

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

詳細描述

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

「可更新的說明」系統是在 Windows PowerShell 3.0 中引進,其設計目的是為了確保您的本機電腦上永遠有最新的說明主題,以便您可以在命令列中讀取。您可以輕鬆地下載並安裝說明檔,並在有較新的說明檔可用時加以更新。

若要將可更新的說明提供給企業中的多部電腦和沒有網際網路的電腦,「可更新的說明」可讓您將說明檔下載至檔案系統目錄或檔案共用,然後再從檔案共用安裝說明檔。

在 Windows PowerShell 4.0 中,HelpInfoUri 屬性是透過 Windows PowerShell 遠端來保留,因此 Save-Help 可用於安裝在遠端電腦上,但不一定安裝在本機電腦上的模組。您可以在沒有網際網路連線的電腦上執行 Export-CliXml,在沒有網際網路連線的電腦上匯入 PSModuleInfo 物件,然後在 PSModuleInfo 物件上執行 Save-Help,以將 PSModuleInfo 物件儲存至磁碟或卸除式媒體 (例如 USB 磁碟機)。您可以使用卸除式媒體將儲存的說明複製到遠端離線電腦,然後再執行 Update-Help 來安裝說明。Save-Help 功能的這些改進可讓您在沒有任何一種網路連線的電腦上安裝說明。如需如何使用新的 Save-Help 功能的範例,請參閱本主題中的<如何從檔案共用更新說明:SAVE-HELP>。

「可更新的說明」也支援最新說明主題和 Cmdlet 基本說明的線上存取,即使電腦上沒有說明檔亦然。

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

可更新的說明 CMDLET

Update-Help:

從網際網路或檔案共用下載最新的說明檔,然後在本機電腦上進行安裝。

Save-Help:

從網際網路下載最新的說明檔,並將其儲存在檔案系統目錄或檔案共用中。若要在電腦上安裝說明檔,請使用 Update-Help。

Get-Help:

在命令列中顯示說明主題。

從電腦上的說明檔取得說明。

為沒有說明檔的 Cmdlet 和函式,顯示自動產生的說明。

在預設的網際網路瀏覽器中,開啟 Cmdlet、函式、指令碼和工作流程的線上說明主題。

更新 WINDOWS POWERSHELL ISE 中的說明

您也可以在 Windows PowerShell 整合式指令碼環境 (ISE) 中,使用 [說明] 功能表中的 [更新 Windows PowerShell 說明] 項目來更新說明。

[更新 Windows PowerShell 說明] 項目會執行 Update-Help 命令且不搭配任何參數。

自動產生的說明:沒有說明檔的說明

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

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

例如,下列命令可取得 Get-Culture Cmdlet 的基本說明。這個輸出顯示當電腦上沒有任何說明檔時顯示 Get-Help。

         PS C:\> Get-Help Get-Culture

名稱

Get-Culture

語法

Get-Culture [<一般參數>]

別名

備註

若要取得最新的 [說明] 內容 (包括描述和範例類型):Update-Help。

模組的說明檔

「可更新的說明」之最小單位是模組的說明。模組說明包含模組中所有 Cmdlet、函式、工作流程、提供者、指令碼和概念的說明。您可以更新電腦上安裝之所有模組的說明,即使模組未匯入目前的工作階段亦然。

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

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

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

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

(Get-Command Set-ExecutionPolicy).ModuleName

若要更新特定模組的說明,請輸入:

        Update-Help -Module <ModuleName>

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

        Update-Help -Module Microsoft.PowerShell.Security

可更新的說明之權限

您必須是電腦上 Administrators 群組的成員,才能更新 $pshome\Modules 目錄中之模組的說明。

如果您不是 Administrators 群組的成員,則無法更新這些模組的說明;但如果您可以連線到網際網路,便能在線上檢視 TechNet Library 中的說明。

更新 $home\Documents\WindowsPowerShell\Modules 中或 $home 目錄的其他子目錄中之模組的說明時,並不需要特殊權限。

Update-Help 和 Save-Help Cmdlet 具有 UseDefaultCredentials 參數,可提供目前使用者的明確認證。這個參數的設計是為了存取安全的網際網路位置。

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

如何安裝和更新說明檔

如果您是第一次下載並安裝說明檔,或想要更新電腦上的說明檔,請使用 Update-Help Cmdlet。

Update-Help Cmdlet 會為您執行所有困難的工作,包括下列工作。

判斷哪些模組支援「可更新的說明」。

尋找每個模組儲存其「可更新的說明」檔案之網際網路位置。

將您電腦上每個模組的說明檔,與每個模組可用的最新說明檔進行比較。

從網際網路下載新檔案。

解除包裝說明檔套件。

確認檔案是有效的說明檔。

在模組目錄的特定語言子目錄中安裝說明檔。

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

若要在支援「可更新的說明」之電腦上,安裝或更新所有模組的說明,請輸入:

        Update-Help

若要更新特定模組的說明,請新增 Update-Help 的 Module 參數。模組名稱允許使用萬用字元。

        Update-Help -Module ServerManager

附註

Update-Help 不必搭配任何參數,便能更新工作階段中所有模組,以及支援「可更新的說明」之所有已安裝模組的說明。您必須在 PSModulePath 環境變數值所列出的目錄中安裝模組,才能加入模組。這些模組也是 "Get-Help -ListAvailable" 命令所傳回的模組。

如果 Module 參數的值為 * (全部),Update-Help 會嘗試更新所有已安裝模組的說明,包括不支援「可更新的說明」之模組。當 Cmdlet 遇到不支援「可更新的說明」之模組時,這個命令通常會產生許多錯誤。

如何從檔案共用更新說明:SAVE-HELP

若要支援未連線到網際網路的電腦,或者要控制或簡化企業中的說明更新,請使用 Save-Help Cmdlet。Save-Help Cmdlet 會從網際網路下載說明檔,並將其儲存在您指定的檔案系統目錄中。

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

若要在電腦上透過儲存至檔案系統目錄的說明檔來安裝或更新說明檔,請使用 Update-Help Cmdlet 的 SourcePath 參數。Update-Help Cmdlet 會識別最新的說明檔,解除包裝並驗證檔案,然後將檔案安裝在模組目錄的特定語言子目錄中。

例如,若要將所有已安裝模組的說明儲存至 \\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 中,然後將變數 $m 指定為模組名稱以在 PSModuleInfo 物件上執行 Save-Help。

        $m = Invoke-Command -ComputerName RemoteServer -ScriptBlock
        { Get-Module -Name DhcpServer -ListAvailable }
        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:\UsbFlashDrive\DhcpModule.xml –InputObject $m

# 接著,將卸除式媒體傳輸至可連線到網際網路的電腦,然後使用 Import-CliXml 匯入 PSModuleInfo 物件。執行 Save-Help 儲存所匯入之 DhcpServer 模組 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

附註:

Save-Help 不必搭配任何參數,便能為工作階段中的所有模組和支援「可更新的說明」之所有已安裝模組,下載說明。您必須在要儲存說明的本機電腦或遠端電腦上,於 PSModulePath 環境變數值所列出的目錄中安裝模組,才能加入模組。這些模組也是執行 "Get-Help -ListAvailable" 命令所傳回的模組。

如何以不同語言更新說明檔

根據預設,Update-Help 和 Save-Help Cmdlet 會使用本機電腦上為 Windows 設定的 UI 文化特性和語言,來下載說明。如果指定的模組沒有本機 UI 文化特性的說明檔,Update-Help 和 Save-Help 會使用 Windows 語言後援規則來尋找最佳的支援語言。

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

例如,若要將工作階段中所有模組的最新說明檔儲存為日文 (Ja-jp) 和法文 (fr-FR),請輸入:

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

如果模組沒有指定語言的說明檔,Update-Help 和 Save-Help Cmdlet 會傳回錯誤訊息,列出每個模組說明可用的語言,以便您選擇最符合您需求的替代語言。

如何自動更新說明

若要確保永遠有最新的說明檔,您可以將 Update-Help 命令新增至 Windows PowerShell 設定檔。

內部配額可防止 Update-Help 命令每天執行一次以上。若要覆寫每天一次的上限,請使用 Force 參數。

在您的設定檔中使用類似下列一個命令。這個命令會在背景工作中更新所有已安裝模組的說明,因此不會干擾您的工作。它使用 Out-Null 命令來隱藏所傳回的工作,以及每天使用命令一次以上所顯示的任何錯誤訊息。

        Start-Job {Update-Help} | Out-Null

您也可以建立排程工作,依任何間隔執行 Update-Help 或 Save-Help Cmdlet。

例如,下列命令會建立排程工作,在每星期五上午 5:00 執行 Update-Help 說明命令。若要執行這個命令,請使用 [以系統管理員身分執行] 選項啟動 Windows PowerShell。

        Register-ScheduledJob -Name UpdateHelpJob -ScriptBlock {Update-Help} `
           -Trigger (New-JobTrigger -Weekly -DaysOfWeek Friday -At "5:00 AM")

如需排程工作的詳細資訊,請參閱 about_Scheduled_Jobs。

如何使用線上說明

如果您無法或選擇不要更新本機電腦上的說明檔,您仍可從線上取得最新的說明檔。

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

例如,下列命令會在預設的網際網路瀏覽器中開啟 Get-Job Cmdlet 的線上說明主題:

        Get-Help Get-Job -Online

- 或者 -

        Get-Help -on Get-Job

若要取得指令碼的線上說明,請使用 Online 參數和指令碼的完整路徑。

Online 參數無法搭配關於主題使用。若要查看 Windows PowerShell 核心的關於主題 (包括 Windows PowerShell 語言的說明主題),請參閱 https://go.microsoft.com/fwlink/?LinkID=113206 上的<Windows PowerShell 核心模組的關於主題>。

如何減少或避免網際網路下載

若要減少網際網路下載次數,並將「可更新的說明」提供給未連線到網際網路的使用者,請使用 Save-Help Cmdlet。從網際網路下載說明,並將其儲存至網路共用。然後,建立群組原則設定或排程工作,在所有電腦上執行 Update-Help 命令。將 Update-Help Cmdlet 的 SourcePath 參數值設定為網路共用。

若要防止可連線到網際網路的使用者從網際網路下載「可更新的說明」,請使用 [設定 Update-Help 的預設來源路徑] 群組原則設定。

這個群組原則設定使用您指定的檔案系統位置,以隱含方式將 SourcePath 參數新增至每部受影響電腦上的每個 Update-Help 命令。使用者可以使用 SourcePath 參數明確地指定不同的檔案系統位置,但無法排除 SourcePath 參數並從網際網路下載說明。

注意:

「設定 Update-Help 的預設來源路徑」群組原則設定會出現在 [電腦組態] 和 [使用者組態] 中。不過,只有 [電腦設定] 底下的原則設定才有效。[使用者設定] 底下的原則設定則會略過。

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

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

若要更新或儲存不是由 Get-Module Cmdlet 的 ListAvailable 參數所傳回之模組的說明,請將模組匯入目前的工作階段,再執行 Update-Help 或 Save-Help 命令。如果在遠端電腦上,請在執行 Save-Help 命令之前,將模組匯入連線到遠端電腦的目前 CIM 或 PSSession (或 Invoke-Command 指令碼區塊)。

當模組處於目前的工作階段時,執行 Update-Help 或 Save-Help Cmdlet 且不搭配任何參數,或使用 Module 參數來指定模組名稱。

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

這個方法可用來更新或儲存不是由 Get-Module Cmdlet 的 ListAvailable 參數所傳回之任何模組的說明,例如安裝在 PSModulePath 環境變數未列出之位置的模組,或格式不正確的模組 (模組目錄未至少包含一個基底名稱與目錄名稱相同的檔案)。

如何支援可更新的說明

如果您撰寫模組,則可以支援模組的線上說明和「可更新的說明」。如需詳細資訊,請參閱 MSDN Library 中的<支援可更新的說明>和<支援線上說明>。

Windows PowerShell 嵌入式管理單元或註解式說明沒有「可更新的說明」可用。

關鍵字

About_Updateable_Help

備註

Windows 預先安裝環境 (Windows PE) 不支援 Update-Help 和 Save-Help Cmdlet。

另請參閱

Get-Help

Save-Help

Update-Help

可更新的說明狀態表

(https://go.microsoft.com/fwlink/?LinkID=270007)