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 3.0 未隨附說明檔。 您可以使用 [可更新的說明] 功能，針對 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參數，可提供目前使用者的明確認證。 此參數的設計目的是要存取安全的網際網路位置。

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

如何安裝和更新說明檔

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

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

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

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

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

Update-Help

若要更新特定模組的說明，請新增 的 Update-HelpModule參數。 模組名稱中允許萬用字元。

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

Update-Help -Module ServerManager

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

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

如何從檔案共用更新說明

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

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

若要從儲存至檔案系統目錄的說明檔安裝或更新電腦上的說明檔，請使用 Cmdlet 的 Update-HelpSourcePath參數。 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 指定為模組名稱。

$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

接下來，將卸載式媒體傳輸至具有網際網路存取的電腦，然後使用 匯入 PSModuleInfo 物件 Import-Clixml 。 執行 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 下載會話中所有模組的說明，以及支援可更新說明的所有已安裝模組。 若要包含模組，模組必須安裝在環境變數值所列的 $env:PSModulePath 目錄中，或是要儲存說明的遠端電腦上。 這些也是執行命令所 Get-Help -ListAvailable 傳回的模組。

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

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

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

例如，若要在日文 (Ja-jp) 和法文 (fr-FR) 中儲存會話上所有模組的最新說明檔，請輸入：

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

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

注意

目前，可更新的說明內容只會以英文 (en-US) 發佈。 在某些非 Windows 系統上，您必須使用 UICulture 參數明確要求 en-US 內容。

如何使用線上說明

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

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

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

Get-Help Get-Job -Online

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

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

如何最小化或防止網際網路下載

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

若要防止具有網際網路存取權的使用者從網際網路下載可更新說明，請使用設定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-HelpModule參數只接受模組名稱。 它們不接受模組檔案的路徑。

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

如何支援可更新的說明

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

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

備註

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

另請參閱