關於可更新的說明
簡短描述
說明 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-Help
Update-Help
只有在您使用 的 SourcePath 或 LiteralPath 參數Update-Help
,以及 的 Save-Help
DestinationPath 或 LiteralPath 參數時,Credential 參數才有效。
如何安裝和更新說明檔
若要第一次下載並安裝說明檔,或更新電腦上的說明檔,請使用 Update-Help
Cmdlet。
Cmdlet Update-Help
會為您執行所有困難的工作,包括下列工作。
- 判斷哪些模組支援可更新的說明。
- 尋找每個模組儲存其可更新說明檔案的因特網位置。
- 比較計算機上每個模組的說明檔與每個模組可用的最新說明檔。
- 從因特網下載新檔案。
- 解除包裝說明檔套件。
- 確認檔案是否為有效的說明檔。
- 以模組目錄的語言特定子目錄安裝說明檔。
若要存取新的說明主題,請使用 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
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
指定為模組名稱。
$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-Help
UICulture 參數,在任何可用的 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-Help
Online 參數。
例如,下列命令會在預設因特網瀏覽器中開啟 Cmdlet 的在線幫助主題 Get-Job
:
Get-Help Get-Job -Online
若要取得腳本的在線說明,請使用 Online 參數和腳本的完整路徑。
Online 參數不適用於 About 主題。 若要查看 PowerShell 的相關主題,包括 PowerShell 語言的說明主題,請參閱 PowerShell 關於 Topics。
如何最小化或防止因特網下載
若要將因特網下載降到最低,並提供可更新的說明給未連線到因特網的使用者,請使用 Save-Help
Cmdlet。 從因特網下載說明,並將其儲存至網路共用。 然後,建立 群組原則 設定或排程工作,以在所有計算機上執行Update-Help
命令。 將 Cmdlet 的 SourcePath 參數 Update-Help
值設定為網路共用。
若要防止具有因特網存取權的使用者從因特網下載可更新的說明,請使用設定 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
環境變數中之位置的模組,或是模組目錄格式不正確 (模組目錄不包含至少一個與目錄名稱相同的檔案) 。
如何支援可更新的說明
如果您撰寫模組,您可以支援課程模組的在線說明和可更新的說明。 如需詳細資訊,請參閱 Microsoft Docs 中支援可更新的說明和支援在線說明。
PowerShell 嵌入式管理單元或批注型說明無法使用可更新的說明。
備註
Windows Update-Help
預安裝環境 (Windows PE) 不支援 和 Save-Help
Cmdlet。