關於可更新的說明
簡短描述
說明 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 功能可讓您在沒有任何網路存取的計算機上安裝說明。 For an example of how to use the new Save-Help functionality, see "HOW TO UPDATE HELP FROM A FILE SHARE: SAVE-HELP" in this topic.
可更新的說明也支援在線存取最新說明主題,以及 Cmdlet 的基本說明,即使計算機上沒有說明檔也一般。
PowerShell 3.0 未隨附說明檔。 您可以使用 [可更新的說明] 功能,針對 PowerShell 和所有 Windows 模組中預設包含的所有命令安裝說明檔。
可更新的說明 CMDLET
Update-Help:從因特網或檔案共享下載最新的說明檔,並將其安裝在本機計算機上。
Save-Help:從因特網下載最新的說明檔,並將其儲存在文件系統目錄或檔案共用中。 若要在計算機上安裝說明檔,請使用Update-Help。
Get-Help:在命令行顯示說明主題。 從電腦上的說明檔取得說明。 針對沒有說明檔的 Cmdlet 和函式,顯示自動產生的說明。 開啟預設因特網瀏覽器中 Cmdlet、函式、腳本和工作流程的在線幫助主題。
在 PowerShell ISE 中更新說明
您也可以使用 PowerShell 整合式腳本環境中的 [說明] 功能表中的 [更新 PowerShell 說明] 專案來更新說明, (ISE) 。
[更新 PowerShell 說明] 專案會執行 Update-Help 命令,而不需參數。
自動產生的說明:沒有說明檔的說明
如果您沒有計算機上 Cmdlet、函式或工作流程的說明檔,Get-Help Cmdlet 會顯示自動產生的說明,並提示您下載說明檔或在線閱讀。
自動產生的說明包含語法和別名,以及說明如何使用可更新的說明 Cmdlet 以及存取在線說明主題的備註。
例如,下列命令會取得 Get-Culture Cmdlet 的基本說明。 當計算機上沒有說明檔案時,輸出會顯示 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
例如,若要尋找包含 Set-ExecutionPolicy Cmdlet 的模組,請輸入:
(Get-Command Set-ExecutionPolicy).ModuleName
若要更新特定模組的說明,請輸入:
Update-Help -Module <ModuleName>
例如,若要更新包含 Set-ExecutionPolicy Cmdlet 之模組的說明,請輸入:
Update-Help -Module Microsoft.PowerShell.Security
可更新說明的許可權
若要更新 $pshome\Modules 目錄中模組的說明,您必須是計算機上的 Administrators 群組成員。
如果您不是 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。 您不需要重新啟動 PowerShell。
若要安裝或更新支援可更新說明之電腦上所有模組的說明,請輸入:
Update-Help
若要更新特定模組的說明,請新增Update-Help的Module參數。 模組名稱中允許通配符。
例如,若要更新 ServerManager 模組的說明,請輸入:
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,然後在 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
接下來,將卸除式媒體傳輸至具有因特網存取的計算機,然後使用 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 命令新增至您的 PowerShell 配置檔。
內部配額可防止 Update-Help 命令每天執行一次以上。 若要覆寫每天最多一次,請使用 Force 參數。
在配置檔中使用類似下列命令。 此命令會更新背景作業中所有已安裝模組的說明,因此不會干擾您的工作。 它會使用 Out-Null 命令來隱藏傳回的作業,以及當您每天使用命令超過一次時,會出現的任何錯誤訊息。
Start-Job {Update-Help} | Out-Null
您也可以建立排程工作,以在任何間隔執行 Update-Help 或 Save-Help Cmdlet。
例如,下列命令會建立排程工作,以在星期五上午 5:00 執行 Update-Help 說明命令。 若要執行此命令,請使用 [以系統管理員身分執行] 選項啟動 PowerShell。
Register-ScheduledJob -Name UpdateHelpJob -ScriptBlock {Update-Help} `
-Trigger (New-JobTrigger -Weekly -DaysOfWeek Friday -At "5:00 AM")
如何使用在線說明
如果您無法或選擇不要更新本機計算機上的說明檔,您仍然可以在線取得最新的說明檔。
若要開啟任何 Cmdlet 或函式的在線說明主題,請使用 Get-Help Cmdlet 的 Online 參數。
例如,下列命令會在預設因特網瀏覽器中開啟 Get-Job Cmdlet 的在線說明主題:
Get-Help Get-Job -Online
若要取得腳本的在線說明,請使用 Online 參數和腳本的完整路徑。
Online 參數不適用於 About 主題。 若要查看 PowerShell Core 的相關主題,包括 PowerShell 語言的說明主題,請參閱 PowerShell Core 模組關於 Topics。
如何最小化或防止因特網下載
若要將因特網下載降到最低,並提供可更新的說明給未連線到因特網的使用者,請使用 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 環境變數中未列出的位置的模組,或是模組目錄 (模組目錄不包含至少一個基底名稱與目錄名稱相同的檔案) 。
如何支援可更新的說明
如果您撰寫模組,您可以支援模組的在線說明和可更新的說明。 如需詳細資訊,請參閱 Microsoft Docs 中的和支援在線說明。
PowerShell 嵌入式管理單元或批注型說明無法使用可更新的說明。
REMARKS
Windows 預先安裝環境 (Windows PE) 不支援 Update-Help 和 Save-Help Cmdlet。