about_Updatable_Help
简短说明
介绍 PowerShell 中的可更新帮助系统。
长说明
PowerShell 提供了几种不同的方法来访问 PowerShell cmdlet 和概念的最新帮助主题。
PowerShell 3.0 中引入的可更新帮助系统旨在确保你始终在本地计算机上拥有最新的帮助主题,以便可以在命令行中阅读它们。 它可以轻松下载和安装帮助文件,并在更新的帮助文件可用时更新它们。
若要为企业中的多台计算机和无法访问 Internet 的计算机提供更新的帮助,可更新的帮助允许将帮助文件下载到文件系统目录或文件共享,然后从文件共享安装帮助文件。
在 PowerShell 4.0 中,通过远程处理保留 HelpInfoUri 属性Windows PowerShell远程处理,这允许Save-Help
用于远程计算机上安装但不一定安装在本地计算机上的模块。 可以将 PSModuleInfo 对象保存到磁盘或可移动媒体 ((例如 USB 驱动器)) ,方法是在无法访问 Internet 的计算机上运行 Export-Clixml
,在具有 Internet 访问权限的计算机上导入 PSModuleInfo 对象,然后在 Save-Help
PSModuleInfo 对象上运行。 可以使用可移动媒体将保存的帮助复制到已断开连接的远程计算机,然后通过运行 Update-Help
进行安装。 这些功能改进 Save-Help
使你可以在没有任何网络访问权限的计算机上安装帮助。 有关如何使用新功能 Save-Help
的示例,请参阅本主题中的 如何从文件共享更新帮助 。
可更新的帮助还支持联机访问最新的帮助主题和 cmdlet 的基本帮助,即使计算机上没有帮助文件也是如此。
PowerShell 不附带帮助文件。 可以使用可更新的帮助功能为 PowerShell 中默认包含的所有命令和所有 Windows 模块安装帮助文件。
可更新的帮助 cmdlet
Update-Help
:从 Internet 或文件共享下载最新的帮助文件,并将其安装在本地计算机上。Save-Help
:从 Internet 下载最新的帮助文件,并将其保存在文件系统目录或文件共享中。 若要在计算机上安装帮助文件,请使用Update-Help
。Get-Help
:在命令行中显示帮助主题。 从计算机上的帮助文件中获取帮助。 显示没有帮助文件的 cmdlet 和函数自动生成的帮助。 在默认 Internet 浏览器中打开 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
模块的帮助,你必须是计算机上的管理员组的成员。
如果你不是管理员组的成员,则无法更新这些模块的帮助;但如果可以访问 Internet,则可以联机查看帮助。
更新目录中的模块或目录 $HOME/Documents/PowerShell/Modules
其他子目录中的模块的 $HOME
帮助不需要特殊权限。
Update-Help
和 Save-Help
cmdlet 具有 UseDefaultCredentials 参数,该参数提供当前用户的显式凭据。 此参数旨在访问安全的 Internet 位置。
和 cmdlet 还有一个 Credential 参数,可用于在远程计算机上运行命令并访问第三台计算机上的文件共享。Save-Help
Update-Help
Credential 参数仅在使用 的 SourcePath 或 LiteralPath 参数以及 的 Update-Help
DestinationPath 或 LiteralPath 参数Save-Help
时有效。
如何安装和更新帮助文件
若要首次下载并安装帮助文件,或者要更新计算机上的帮助文件,请使用 Update-Help
cmdlet。
cmdlet Update-Help
为你完成所有艰苦的工作,包括以下任务。
- 确定哪些模块支持可更新的帮助。
- 查找每个模块存储其可更新帮助文件的 Internet 位置。
- 将计算机上每个模块的帮助文件与可用于每个模块的最新帮助文件进行比较。
- 从 Internet 下载新文件。
- 解包帮助文件包。
- 验证文件是否为有效的帮助文件。
- 在模块目录的语言特定子目录中安装帮助文件。
若要访问新的帮助主题,请使用 Get-Help
cmdlet。 无需重启 PowerShell。
若要安装或更新计算机上支持可更新帮助的所有模块的帮助,请键入:
Update-Help
若要更新特定模块的帮助,请添加 的 Update-Help
Module 参数。 模块名称中允许使用通配符。
例如,若要更新 ServerManager 模块的帮助,请键入:
Update-Help -Module ServerManager
如果没有参数, Update-Help
则更新会话中所有模块以及支持可更新帮助的所有已安装模块的帮助。 要包含模块,模块必须安装在 PSModulePath 环境变量的值中列出的目录中。 这些模块也是命令返回的 Get-Module -ListAvailable
模块。
如果 Module 参数的值 (*
所有) , Update-Help
则尝试更新所有已安装模块的帮助,包括不支持可更新帮助的模块。 当 cmdlet 遇到不支持可更新帮助的模块时,此命令通常会生成许多错误。
如何从文件共享更新帮助
若要支持未连接到 Internet 的计算机,或者要控制或简化企业中的帮助更新,请使用 Save-Help
cmdlet。 cmdlet Save-Help
从 Internet 下载帮助文件,并将其保存在指定的文件系统目录中。
Save-Help
将指定目录中的帮助文件与可用于每个模块的最新帮助文件进行比较。 如果目录没有帮助文件或较新的帮助文件可用于模块,则 Save-Help
cmdlet 会从 Internet 下载新文件。 但是,它不会解包或安装帮助文件。
若要从保存到文件系统目录的帮助文件安装或更新计算机上的帮助文件,请使用 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
以保存连接 Internet 的客户端计算机上的 DhcpServer 模块的帮助,而无需在本地计算机上安装 DhcpServer 模块或 DHCP 服务器角色。
选项 1:运行 Invoke-Command
以获取远程模块的 PSModuleInfo 对象,将其保存在变量中,$m
然后Save-Help
通过指定变量$m
作为模块名称在 PSModuleInfo 对象上运行。
$invokeCommandSplat = @{
ComputerName = 'RemoteServer'
ScriptBlock = { Get-Module -Name DhcpServer -ListAvailable }
}
$m = Invoke-Command @invokeCommandSplat
Save-Help -Module $m -DestinationPath C:\SavedHelp
选项 2:打开以运行 DHCP 服务器模块的计算机为目标的 PSSession,获取模块的 PSModuleInfo 对象,将其保存在变量 $m
中,然后在 Save-Help
变量中 $m
保存的对象上运行。
$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
中,然后在 Save-Help
变量中 $m
保存的对象上运行。
$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:\UsbDrive\DhcpModule.xml -InputObject $m
接下来,将可移动媒体传输到可以访问 Internet 的计算机,然后使用 导入 PSModuleInfo 对象 Import-Clixml
。 运行 Save-Help
以保存导入的 DhcpServer 模块 PSModuleInfo 对象的帮助。
$deserialized_m = Import-Clixml E:\UsbDrive\DhcpModule.xml
Save-Help -Module $deserialized_m -DestinationPath E:\UsbDrive\SavedHelp
最后,将可移动媒体传输回没有网络访问权限的计算机,然后通过运行 Update-Help
安装帮助。
Update-Help -Module DhcpServer -SourcePath E:\UsbDrive\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) 发布。
如何使用联机帮助
如果无法或选择不更新本地计算机上的帮助文件,仍可联机获取最新的帮助文件。
若要打开任何 cmdlet 或函数的联机帮助主题,请使用 cmdlet 的 Get-Help
Online 参数。
例如,以下命令会在默认 Internet 浏览器中打开 cmdlet 的联机帮助主题 Get-Job
:
Get-Help Get-Job -Online
若要获取脚本的联机帮助,请使用 Online 参数和脚本的完整路径。
Online 参数不适用于“关于”主题。 若要查看有关 PowerShell 的主题(包括有关 PowerShell 语言的帮助主题),请参阅 PowerShell 关于 Topics。
如何最小化或阻止 Internet 下载
若要最大程度地减少 Internet 下载,并为未连接到 Internet 的用户提供可更新的帮助,请使用 Save-Help
cmdlet。 从 Internet 下载帮助并将其保存到网络共享。 然后,创建在所有计算机上运行Update-Help
命令的组策略设置或计划作业。 将 cmdlet 的 SourcePath 参数 Update-Help
的值设置为网络共享。
若要防止具有 Internet 访问权限的用户从 Internet 下载可更新帮助,请使用设置 Update-Help 的默认源路径组策略设置。
此组策略设置会将 SourcePath 参数与指定的文件系统位置隐式添加到每个受影响的计算机上的每个Update-Help
命令。 用户可以显式使用 SourcePath 参数指定不同的文件系统位置,但不能排除 SourcePath 参数并从 Internet 下载帮助。
注意
“ 设置 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
模块参数仅接受模块名称。 他们不接受模块文件的路径。
使用此技术更新或保存 cmdlet 的 ListAvailable 参数 Get-Module
未返回的任何模块的帮助,例如安装在环境变量中 $env:PSModulePath
未列出的位置的模块,或者模块目录中格式不正确 (模块目录中不包含至少一个其基名称与目录名称) 相同的文件。
如何支持可更新的帮助
如果创作模块,则可以为模块支持联机帮助和可更新帮助。 有关详细信息,请参阅支持可更新的帮助和支持联机帮助。
可更新的帮助不适用于 PowerShell 管理单元或基于注释的帮助。
注解
Update-Help
Windows 预安装环境 (Windows PE) 不支持 和 Save-Help
cmdlet。