Update-Help
下載並安裝您電腦上的最新說明檔。
語法
Update-Help
[[-Module] <String[]>]
[-FullyQualifiedModule <ModuleSpecification[]>]
[[-SourcePath] <String[]>]
[-Recurse]
[[-UICulture] <CultureInfo[]>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-Force]
[-Scope <UpdateHelpScope>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Update-Help
[[-Module] <String[]>]
[-FullyQualifiedModule <ModuleSpecification[]>]
[-LiteralPath <String[]>]
[-Recurse]
[[-UICulture] <CultureInfo[]>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-Force]
[-Scope <UpdateHelpScope>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Description
Update-Help
Cmdlet 會下載 PowerShell 模組的最新說明檔,並將其安裝在您的電腦上。 您不需要重新啟動 PowerShell,才能使變更生效。 您可以使用 Get-Help
Cmdlet 立即檢視新的說明檔。
Update-Help
檢查計算機上的說明檔版本。 如果您沒有模組的說明檔,或說明檔已過期,Update-Help
下載最新的說明檔。 您可以從因特網或檔案共享下載並安裝說明檔。
如果沒有參數,Update-Help
更新支援可更新說明之模組的說明檔,並載入會話或安裝在 $env:PSModulePath
中包含的位置。 如需詳細資訊,請參閱 about_Updatable_Help。
Update-Help
檢查已安裝的說明版本。 如果 Update-Help
找不到模組的更新說明檔,它會以無訊息方式繼續,而不會顯示錯誤訊息。 使用 Force 參數來略過版本檢查。 使用 Verbose 參數來查看狀態和進度詳細數據。 使用 Module 參數來更新特定模組的說明檔。
您也可以在未連線到因特網的電腦上使用 Update-Help
。 首先,使用 Save-Help
Cmdlet 從因特網下載說明檔,並將其儲存在系統無法連線到因特網的共享資料夾中。 然後使用 Update-Help
的 SourcePath 參數,從共用下載更新的說明檔,並將其安裝在計算機上。
Update-Help
Cmdlet 是在 Windows PowerShell 3.0 中引進的。
重要
Update-Help
需要 PowerShell 6.0 和以下的系統管理許可權。 PowerShell 6.1 和更新版本會將預設 範圍 設定為 CurrentUser
。 在 PowerShell 6.1 之前,無法使用 Scope 參數。
您必須是計算機上的 Administrators 群組成員,才能更新核心 PowerShell 模組的說明檔。
若要下載或更新 PowerShell 安裝目錄中模組的說明檔($PSHOME\Modules
),包括 PowerShell Core 模組,請使用 [以系統管理員身分執行] 選項 啟動 PowerShell。 例如:Start-Process pwsh.exe -Verb RunAs
。
範例
範例 1:更新所有模組的說明檔
Update-Help
Cmdlet 會更新支援可更新說明之已安裝模組的說明檔。 使用者介面 (UI) 文化特性語言是在作系統中設定。
Update-Help
範例 2:更新指定模組的說明檔
Update-Help
Cmdlet 只會針對開頭為 Microsoft.PowerShell的模組名稱更新說明檔。
Update-Help -Module Microsoft.PowerShell*
範例 3:更新系統上未設定為 en-US 地區設定的說明
Update-Help
Cmdlet 的設計目的是要下載多種語言的說明。 不過,當系統使用的語言沒有可用的說明時,模組和UI文化特性會顯示錯誤訊息。
在此範例中,Update-Help
是在設定為 en-GB
地區設定的系統上執行。
Update-Help Microsoft.PowerShell.Utility -Force
Update-Help: Failed to update Help for the module(s) 'Microsoft.PowerShell.Utility' with
UI culture(s) {en-GB} : The specified culture is not supported: en-GB. Specify a culture
from the following list: {en-US}..
English-US help content is available and can be installed using: Update-Help -UICulture en-US.
說明檔一律會針對 en-US
地區設定發佈。 若要下載英文說明,請使用 UICulture 參數執行 Update-Help
,並指定 en-US
地區設定。
範例 4:從檔案共用更新多部計算機上的說明檔案
在此範例中,更新的說明檔會從因特網下載並儲存在檔案共用中。 需要使用者認證,才能存取檔案共享並安裝更新。 使用檔案共享時,可以更新防火牆後方或未連線到因特網的計算機。
Save-Help -DestinationPath \\Server01\Share\PSHelp -Credential Domain01\Admin01
Invoke-Command -ComputerName (Get-Content Servers.txt) -ScriptBlock {
Update-Help -SourcePath \\Server01\Share\PSHelp -Credential Domain01\Admin01
}
Save-Help
命令會針對支援可更新說明的所有模組下載最新的說明檔。
DestinationPath 參數會將檔案儲存在 \\Server01\Share\PSHelp
檔案共用中。
Credential 參數會指定有權存取檔案共享的使用者。
Invoke-Command
Cmdlet 會在多部電腦上執行遠端 Update-Help
命令。
ComputerName 參數會從 Servers.txt 檔案取得遠端電腦清單。
ScriptBlock 參數會執行 Update-Help
命令,並使用 SourcePath 參數來指定包含更新說明檔的檔案共用。
Credential 參數會指定可存取檔案共用並執行遠端 Update-Help
命令的使用者。
範例 5:取得更新的說明檔清單
Update-Help
Cmdlet 會更新指定模組的說明。 Cmdlet 會使用 Verbose 一般參數來顯示已更新的說明檔清單。 您可以使用 詳細資訊 來檢視特定模組之所有說明檔或說明檔的輸出。
如果沒有 Verbose 參數,Update-Help
就不會顯示命令的結果。
Verbose 參數輸出有助於確認說明檔是否已更新,或是否已安裝最新版本。
Update-Help -Module Microsoft.PowerShell.Utility -Verbose
範例 6:尋找支援可更新說明的模組
此範例會列出支援可更新說明的模組。 命令會使用模組的 HelpInfoUri 屬性來識別支援可更新說明的模組。
HelpInfoUri 屬性包含執行 Update-Help
Cmdlet 時重新導向的 URL。
Get-Module -ListAvailable | Where-Object -Property HelpInfoUri
Directory: C:\program files\powershell\6\Modules
ModuleType Version Name PSEdition ExportedCommands
---------- ------- ---- --------- ----------------
Manifest 6.1.0.0 CimCmdlets Core {Get-CimAssociatedInstance... }
Manifest 1.2.2.0 Microsoft.PowerShell.Archive Desk {Compress-Archive... }
Manifest 6.1.0.0 Microsoft.PowerShell.Diagnostics Core {Get-WinEvent, New-WinEvent}
Directory: C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules
ModuleType Version Name PSEdition ExportedCommands
---------- ------- ---- --------- ----------------
Manifest 2.0.1.0 Appx Core,Desk {Add-AppxPackage, ... }
Script 1.0.0.0 AssignedAccess Core,Desk {Clear-AssignedAccess, ... }
Manifest 1.0.0.0 BitLocker Core,Desk {Unlock-BitLocker, ... }
範例 7:清查更新的說明檔
在此範例中,腳本 Get-UpdateHelpVersion.ps1
為每個模組及其版本號碼建立可更新說明檔案的清查。
腳本會使用模組的 HelpInfoUri 屬性,識別支援可更新說明的模組。 對於支援可更新說明的模組,腳本會尋找並剖析說明信息檔 (*helpinfo.xml),以尋找最新的版本號碼。
腳本會使用 PSCustomObject 類別和哈希表來建立自定義輸出物件。
# Get-UpdateHelpVersion.ps1
Param(
[parameter(Mandatory=$False)]
[String[]]
$Module
)
$HelpInfoNamespace = @{helpInfo='http://schemas.microsoft.com/powershell/help/2010/05'}
if ($Module) { $Modules = Get-Module $Module -ListAvailable | where {$_.HelpInfoUri} }
else { $Modules = Get-Module -ListAvailable | where {$_.HelpInfoUri} }
foreach ($mModule in $Modules)
{
$mDir = $mModule.ModuleBase
if (Test-Path $mDir\*helpinfo.xml)
{
$mName=$mModule.Name
$mNodes = dir $mDir\*helpinfo.xml -ErrorAction SilentlyContinue |
Select-Xml -Namespace $HelpInfoNamespace -XPath "//helpInfo:UICulture"
foreach ($mNode in $mNodes)
{
$mCulture=$mNode.Node.UICultureName
$mVer=$mNode.Node.UICultureVersion
[PSCustomObject]@{"ModuleName"=$mName; "Culture"=$mCulture; "Version"=$mVer}
}
}
}
ModuleName Culture Version
---------- ------- -------
ActiveDirectory en-US 3.0.0.0
ADCSAdministration en-US 3.0.0.0
ADCSDeployment en-US 3.0.0.0
ADDSDeployment en-US 3.0.0.0
ADFS en-US 3.0.0.0
參數
-Confirm
在執行 Cmdlet 之前,提示您進行確認。
類型: | SwitchParameter |
別名: | cf |
Position: | Named |
預設值: | False |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-Credential
指定有權存取 SourcePath 所指定檔案系統位置之用戶的認證。 只有當命令中使用 SourcePath 或 LiteralPath 參數時,此參數才有效。
Credential 參數可讓您在遠端電腦上使用 SourcePath 參數來執行 Update-Help
命令。 藉由提供明確的認證,您可以在遠端計算機上執行 命令,並在第三部計算機上存取檔案共用,而不會發生拒絕存取錯誤或使用 CredSSP 驗證來委派認證。
輸入使用者名稱,例如 User01 或 Domain01\User01,或輸入 Get-Credential
Cmdlet 所產生的 PSCredential 物件。 如果您輸入使用者名稱,系統會提示您輸入密碼。
認證會儲存在 PSCredential 物件中,密碼會儲存為 secureString 。
注意
如需 SecureString 數據保護的詳細資訊,請參閱 SecureString 有多安全?。
類型: | PSCredential |
Position: | Named |
預設值: | Current user |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-Force
表示此 Cmdlet 不會遵循每天一次的限制、略過版本檢查,以及下載超過 1 GB 限制的檔案。
如果沒有此參數,Update-Help
每 24 小時只會執行一次。 每個模組的下載量限製為 1 GB 的未壓縮內容,而說明檔案只有在比電腦上的現有檔案還新時才會安裝。
每天一次的限制可保護裝載說明檔的伺服器,並讓您可以將 Update-Help
命令新增至 PowerShell 配置檔,而不會產生重複連線或下載的資源成本。
若要在多個 UI 文化特性中更新模組的說明,而不使用 Force 參數,請在相同的命令中包含所有 UI 文化特性,例如:
Update-Help -Module PSScheduledJobs -UICulture en-US, fr-FR, pt-BR
類型: | SwitchParameter |
Position: | Named |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-FullyQualifiedModule
此值可以是模組名稱、完整模組規格或模組檔案的路徑。
當值為路徑時,路徑可以是完整或相對路徑。 相對於包含 using 語句的腳本,會解析相對路徑。
當值是名稱或模組規格時,PowerShell 會搜尋指定模組 PSModulePath。
模組規格是具有下列索引鍵的哈希表。
-
ModuleName
- 必要 指定模組名稱。 -
GUID
- 選擇性 指定模組的 GUID。 - 它也 必要 至少指定下列三個索引鍵的其中一個。
-
ModuleVersion
- 指定模組的最低可接受的版本。 -
MaximumVersion
- 指定模組的最大可接受的版本。 -
RequiredVersion
- 指定模組的確切必要版本。 這無法與其他版本金鑰搭配使用。
-
您無法在與 Module 參數相同的命令中指定 FullyQualifiedModule 參數。
類型: | ModuleSpecification[] |
Position: | Named |
預設值: | None |
必要: | False |
接受管線輸入: | True |
接受萬用字元: | False |
-LiteralPath
指定更新說明檔的資料夾,而不是從因特網下載它們。 如果您使用 Save-Help
Cmdlet 將說明檔下載至目錄,請使用此參數或 SourcePath。
您可以管線目錄物件,例如從 Get-Item
或 Get-ChildItem
Cmdlet,以 Update-Help
。
與 sourcePath 的值不同,LiteralPath 的值會與類型完全相同。 不會將任何字元解譯為通配符。 如果路徑包含逸出字元,請以單引弧括住它。 單引號會告知PowerShell不要將任何字元解譯為逸出序列。
類型: | String[] |
別名: | PSPath, LP |
Position: | Named |
預設值: | None |
必要: | False |
接受管線輸入: | True |
接受萬用字元: | False |
-Module
更新指定模組的說明。 在逗號分隔清單中輸入一或多個模組名稱或名稱模式,或指定每一行列出一個模組名稱的檔案。 允許通配符。 您可以將 Get-Module
Cmdlet 中的模組管線至 Update-Help
Cmdlet。
您指定的模組必須安裝在計算機上,但不需要匯入目前的會話。 您可以在會話中指定任何模組,或安裝在 $env:PSModulePath
環境變數中所列位置的任何模組。
值 *
(all) 會嘗試更新電腦上所安裝之所有模組的說明。
包含不支援可更新說明的模組。 當命令遇到不支援可更新說明的模組時,這個值可能會產生錯誤。 請改為在沒有參數的情況下執行 Update-Help
。
Update-Help
Cmdlet 的 Module 參數不接受模組檔案或模組指令清單檔的完整路徑。 若要更新不在 $env:PSModulePath
位置的模組說明,請在執行 Update-Help
命令之前,將模組匯入目前的會話。
類型: | String[] |
別名: | Name |
Position: | 0 |
預設值: | None |
必要: | False |
接受管線輸入: | True |
接受萬用字元: | True |
-Recurse
執行遞歸搜尋指定目錄中的說明檔。 只有當命令使用 SourcePath 參數時,此參數才有效。
類型: | SwitchParameter |
Position: | Named |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-Scope
指定更新說明的系統範圍。
AllUsers 範圍的更新需要 Windows 系統上的系統管理許可權。
-Scope
參數是在PowerShell Core 6.1版中引進的。
CurrentUser 是 PowerShell 6.1 和更新版本說明檔案的預設範圍。
AllUsers 可以指定為所有使用者安裝或更新說明。 在 Unix 系統上,需要 sudo
許可權,才能更新所有使用者的說明。 例如:sudo pwsh -c Update-Help
可接受的值為:
- CurrentUser
- AllUsers
類型: | UpdateHelpScope |
Position: | Named |
預設值: | CurrentUser |
必要: | False |
接受管線輸入: | True |
接受萬用字元: | False |
-SourcePath
指定檔案系統資料夾,其中 Update-Help
取得更新的說明檔,而不是從因特網下載。 輸入資料夾的路徑。 請勿指定檔名或擴展名。 您可以從 Get-Item
或 Get-ChildItem
Cmdlet 管線資料夾,以 Update-Help
。
根據預設,Update-Help
從因特網下載更新的說明檔。 當您使用 Save-Help
Cmdlet 將更新的說明檔下載至目錄時,請使用 SourcePath。
若要指定 SourcePath的預設值,請移至 組策略、電腦設定,設定 Update-Help的預設來源路徑。 此組策略設定可防止使用者使用 Update-Help
從因特網下載說明檔。
如需詳細資訊,請參閱 about_Group_Policy_Settings。
類型: | String[] |
別名: | Path |
Position: | 1 |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-UICulture
指定此 Cmdlet 取得更新說明檔的 UI 文化特性值。 輸入一或多個語言代碼,例如 es-ES
、包含文化特性物件的變數,或取得文化特性物件的命令,例如 Get-Culture
或 Get-UICulture
命令。 不允許通配符。
根據預設,Update-Help
取得作系統或其後援文化特性設定UI文化特性中的說明檔。 如果您指定 UICulture 參數,Update-Help
只會尋找指定語言的說明。
從 PowerShell 7.4 開始,您可以使用部分語言代碼,例如 en
下載任何區域的英文說明。
注意
Ubuntu 18.04 已將預設地區設定變更為 C.UTF.8
,這不是可辨識的UI文化特性。 除非您使用此參數搭配支援的地區設定,例如 en-US
,否則 Update-Help
無法以無訊息方式下載說明。 這可能會在任何使用不支援值的平台上發生。
類型: | CultureInfo[] |
Position: | 2 |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-UseDefaultCredentials
表示 Update-Help
使用目前使用者的認證來執行命令,包括因特網下載。 根據預設,命令會執行,而不需明確認證。
只有當 Web 下載使用 NT LAN Manager (NTLM)、交涉或 Kerberos 型驗證時,此參數才有效。
類型: | SwitchParameter |
Position: | Named |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-WhatIf
顯示 Cmdlet 執行時會發生什麼事。 Cmdlet 未執行。
類型: | SwitchParameter |
別名: | wi |
Position: | Named |
預設值: | False |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
輸入
您可以使用管線將目錄路徑物件傳送至此 Cmdlet。
您可以使用管線將模組物件傳送至此 Cmdlet。
輸出
None
此 Cmdlet 不會傳回任何輸出。
備註
若要更新核心 PowerShell 模組的說明,其中包含隨 PowerShell 一起安裝的命令,或 $PSHOME\Modules
目錄中的任何模組,請使用選項啟動 PowerShell,以系統管理員身分執行。
只有電腦上的 Administrators 群組成員可以更新核心 PowerShell 模組的說明、與 PowerShell 一起安裝的命令,以及 $PSHOME\Modules
資料夾中的模組。 如果您沒有更新說明檔的許可權,您可以在線上閱讀說明檔。 例如,Get-Help Update-Help -Online
。
模組是可更新說明的最小單位。 您無法更新特定 Cmdlet 的說明。 若要尋找包含特定 Cmdlet 的模組,請使用 Get-Command
Cmdlet 的 ModuleName 屬性,例如,(Get-Command Update-Help).ModuleName
。
由於說明檔已安裝在模組目錄中,Update-Help
Cmdlet 只能針對計算機上安裝的模組安裝更新的說明檔。 不過,Save-Help
Cmdlet 可以儲存電腦上未安裝之模組的說明。
Update-Help
Cmdlet 是在 Windows PowerShell 3.0 中引進的。 它在舊版 PowerShell 中無法運作。 在同時具有 Windows PowerShell 2.0 和 Windows PowerShell 3.0 的電腦上,使用 Windows PowerShell 3.0 會話中的 Update-Help
Cmdlet 來下載和更新說明檔。 說明檔同時可供 Windows PowerShell 2.0 和 Windows PowerShell 3.0 使用。
Update-Help
和 Save-Help
Cmdlet 會使用下列埠來下載說明檔:HTTP 的埠 80 和 HTTPS 的埠 443。
Update-Help
支援所有模組和核心 PowerShell 嵌入式管理單元。它不支援任何其他嵌入式管理單元。
若要更新 $env:PSModulePath
環境變數中未列出的模組說明,請將模組匯入目前的會話,然後執行 Update-Help
命令。 在沒有參數的情況下執行 Update-Help
,或使用 Module 參數來指定模組名稱。
Update-Help
和 Save-Help
Cmdlet 的 Module 參數不接受模組檔案或模組指令清單檔的完整路徑。
任何模組都可以支援可更新的說明。 如需支援您所撰寫模組中可更新說明的指示,請參閱 支援可更新的說明。
Windows 預安裝環境 (Windows PE) 不支援 Update-Help
和 Save-Help
Cmdlet。