about_Updatable_Help
应用到: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0
主题
About_Updatable_Help
简短说明
介绍 Windows PowerShell® 中的可更新帮助系统。
详细说明
Windows PowerShell 提供了多种不同的方式来访问有关 Windows PowerShell cmdlet 和概念的最新帮助主题。
Windows PowerShell 3.0 中引入了可更新帮助系统,旨在确保你在本地计算机上始终具有最新的帮助主题,以便你可以在命令行读取它们。通过它可轻松完成以下操作:下载和安装帮助文件并在更新的帮助文件可用时立即进行更新。
为了为企业中的多台计算机和无法访问 Internet 的计算机提供更新帮助,可更新帮助允许你将帮助文件下载到文件系统目录或文件共享,然后从文件共享中安装帮助文件。
在 Windows PowerShell 4.0 中,HelpInfoUri 属性通过 Windows PowerShell 远程处理保留,这使 Save-help 可适用于安装在远程计算机上(但不一定安装在本地计算机上)的模块。你可以将 PSModuleInfo 对象保存到磁盘或可移动媒体(例如 USB 驱动器),方法是在无法访问 Internet 的计算机上运行 Export-CliXml、在无法访问 Internet 的计算机上导入 PSModuleInfo 对象,然后在 PSModuleInfo 对象上运行 Save-Help。可以使用可移动媒体将已保存的帮助复制到已断开连接的远程计算机,然后通过运行 Update-Help 进行安装。Save-Help 功能中的这些改进使你可以在没有任何种类的网络访问的计算机上安装帮助。有关如何使用新的 Save-Help 功能的示例,请参阅本主题中的“如何从文件共享更新帮助:SAVE-HELP”。
可更新帮助还支持联机访问最新的帮助主题和有关 cmdlet 的基本帮助,即使计算机上没有帮助文件也是如此。
Windows PowerShell 3.0 不附带帮助文件。你可以使用可更新帮助功能来为 Windows PowerShell 中默认包含的所有命令和所有 Windows 模块安装帮助文件。
可更新帮助 CMDLET
Update-Help:
从 Internet 或文件共享下载最新的帮助文件并将其安装在本地计算机上。
Save-Help:
从 Internet 下载最新的帮助文件并将其保存在文件系统目录或文件共享中。若要在计算机上安装帮助文件,请使用 Update-Help。
Get-Help:
在命令行中显示帮助主题。
从计算机上的帮助文件中获取帮助。
为不含有帮助文件的 cmdlet 和函数显示自动生成的帮助。
在默认的 Internet 浏览器中打开 cmdlet、函数、脚本和工作流的联机帮助主题。
更新 WINDOWS POWERSHELL ISE 中的帮助
你还可以通过在 Windows PowerShell 集成脚本环境 (ISE) 中使用帮助菜单中的“更新 Windows PowerShell 帮助”项来更新帮助。
在没有参数的情况下,“更新 Windows PowerShell 帮助”项将运行 Update-Help 命令。
自动生成的帮助:不带有帮助文件的帮助
如果计算机上没有有关某个 cmdlet、函数或工作流的帮助文件,则 Get-help cmdlet 将显示自动生成的帮助,并提示你下载帮助文件或联机阅读它们。
自动生成的帮助包括语法和别名,以及解释如何使用可更新帮助 cmdlet 并访问联机帮助主题的备注。
例如,以下命令获取 Get-Culture cmdlet 的基本帮助。当计算机上没有帮助文件时,输出显示 Get-Help 屏幕。
PS C:\> Get-Help Get-Culture
名称
Get-Culture
语法
Get-Culture [<CommonParameters>]
别名
无
备注
若要获取包括说明和示例的最新帮助内容,请键入: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 组的成员,则无法更新这些模块的帮助;但是如果你可以访问 Internet,则可以在 TechNet 库中联机查看帮助。
为 $home\Documents\WindowsPowerShell\Modules 目录中的模块或 $home 目录的其他子目录中的模块更新帮助不需要特殊权限。
Update-Help 和 Save-Help cmdlet 具有 UseDefaultCredentials 参数,可提供当前用户的显式凭据。此参数设计用于访问安全的 Internet 位置。
Update-Help 和 Save-Help cmdlet 还具有 Credential 参数,可使你在远程计算机上运行该命令并访问第三台计算机上的文件共享。仅当你使用 Update-Help 的 SourcePath 或 LiteralPath 参数和 Save-Help 的 DestinationPath 或 LiteralPath 参数时,Credential 参数才有效。
如何安装和更新帮助文件
若要首次下载和安装帮助文件,或更新计算机上的帮助文件,请使用 Update-Help cmdlet。
Update-Help cmdlet 将为你完成所有工作,包括以下任务。
确定哪些模块支持可更新帮助。
查找每个模块用来存储其可更新帮助文件的 Internet 位置。
将计算机上的每个模块的帮助文件与为每个模块提供的最新帮助文件进行比较。
从 Internet 下载新文件。
对帮助文件包进行解包。
验证这些文件是有效的帮助文件。
在模块目录的特定于语言的子目录中安装帮助文件。
若要访问新的帮助主题,请使用 Get-Help cmdlet。你不需要重新启动 Windows PowerShell。
若要在支持可更新帮助的计算机上为所有模块安装或更新帮助,请键入:
Update-Help
若要更新特定模块的帮助,请添加 Update-Help 的 Module 参数。允许在模块名称中使用通配符。
Update-Help -Module ServerManager
说明
在没有参数的情况下,Update-Help 为会话中的所有模块和支持可更新帮助的所有已安装模块更新帮助。若要包含这些模块,则必须使其安装在 PSModulePath 环境变量的值中列出的目录中。这些也是“Get-Help -ListAvailable”命令返回的模块。
如果 Module 参数的值为 *(全部),则 Update-Help 将尝试为所有已安装的模块更新帮助,包括不支持可更新帮助的模块。当 cmdlet 遇到不支持可更新帮助的模块时,此命令通常会生成许多错误。
如何从文件共享更新帮助:SAVE-HELP
若要支持未连接到 Internet 的计算机或者控制或优化企业中的帮助更新,请使用 Save-Help cmdlet。Save-Help cmdlet 从 Internet 下载帮助文件,并将其保存在你指定的文件系统目录中。
Save-Help 将指定目录中的帮助文件与为每个模块提供的最新帮助文件进行比较。如果该目录没有帮助文件,或该模块有更新的帮助文件,则 Save-Help cmdlet 将从 Internet 下载新文件。但是,它不会解包或安装帮助文件。
若要从已保存到文件系统目录的帮助文件安装或更新计算机上的帮助文件,请使用 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 来从已连接到 Internet 的客户端计算机为 DhcpServer 模块保存帮助,而无需在本地计算机上安装 DhcpServer 模块或 DHCP 服务器角色。
选项 1:
运行 Invoke-Command 以获取远程模块的 PSModuleInfo 对象、将其保存在变量 $m 中,然后通过将变量 $m 指定为模块名称来在 PSModuleInfo 对象上运行 Save-Help。
$m = Invoke-Command -ComputerName RemoteServer -ScriptBlock
{ Get-Module -Name DhcpServer -ListAvailable }
Save-Help -Module $m -DestinationPath C:\SavedHelp
选项 2:
打开 PSSession(面向运行 DHCP 服务器模块的计算机)以获取该模块的 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:
打开 CIM 会话(面向运行 DHCP 服务器模块的计算机)以获取该模块的 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
# 接下来,将可移动媒体传输到具有 Internet 访问的计算机上,然后使用 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 命令添加到 Windows PowerShell 配置文件。
内部配额可防止 Update-Help 命令每天运行一次以上。若要覆盖每天一次的限制,请使用 Force 参数。
在配置文件中使用某个命令(如以下命令)。此命令在后台作业中更新所有已安装模块的帮助,以便它不会打扰你的工作。它使用 Out-Null 命令来禁止显示返回的作业和任何错误消息,这些消息本来会在你每天使用该命令一次以上时显示。
Start-Job {Update-Help} | Out-Null
你还可以创建以任何间隔运行 Update-Help 或 Save-Help cmdlet 的计划作业。
例如,以下命令在每周五上午 5:00 创建可运行 Update-Help 帮助命令的计划作业。若要运行此命令,请使用"以管理员身份运行"选项启动 Windows PowerShell。
Register-ScheduledJob -Name UpdateHelpJob -ScriptBlock {Update-Help} `
-Trigger (New-JobTrigger -Weekly -DaysOfWeek Friday -At "5:00 AM")
有关计划作业的详细信息,请参阅 about_Scheduled_Jobs。
如何使用联机帮助
如果你无法更新或选择不更新本地计算机上的帮助文件,你仍然可以联机获取最新的帮助文件。
若要打开任何 cmdlet 或函数的联机帮助主题,请使用 Get-Help cmdlet 的 Online 参数。
例如,以下命令在默认的 Internet 浏览器中打开 Get-Job cmdlet 的联机帮助主题:
Get-Help Get-Job -Online
- 或者-
Get-Help -on Get-Job
若要获取某个脚本的联机帮助,请使用 Online 参数和该脚本的完整路径。
Online 参数不适用于 About 主题。若要查看有关 Windows PowerShell 核心的主题(包括有关 Windows PowerShell 语言的帮助主题),请参阅“Windows PowerShell 核心模块 About 主题”,网址为 https://go.microsoft.com/fwlink/?LinkID=113206。
如何最大程度减少或阻止 INTERNET 下载
若要最大程度减少 Internet 下载并向未连接到 Internet 的用户提供可更新帮助,请使用 Save-Help cmdlet。从 Internet 下载帮助并将其保存到网络共享。然后,创建可在所有计算机上运行 Update-Help 命令的组策略设置或计划作业。将 Update-Help cmdlet 的 SourcePath 参数的值设置为网络共享。
若要防止具有可访问 Internet 的用户从 Internet 下载可更新帮助,请使用“为 Update-Help 设置默认源路径”组策略设置。
此组策略设置使用你指定的文件系统位置将 SourcePath 参数隐式添加到每台受影响的计算机上的每个 Update-Help 命令。用户可使用 SourcePath 参数显式指定不同的文件系统位置,但它们无法排除 SourcePath 参数并从 Internet 下载帮助。
注意:
“为 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 环境变量中列出的位置的模块,或格式不正确的模块(模块目录未包含至少一个基本名称与目录名称相同的文件)。
如何支持可更新帮助
如果你创作了一个模块,你可以为你的模块支持联机帮助和可更新帮助。有关详细信息,请参阅 MSDN 库中的“支持可更新帮助”和“支持联机帮助”。
不适用于 Windows PowerShell 管理单元的可更新帮助或基于注释的帮助。
关键字
About_Updateable_Help
备注
Update-Help 和 Save-Help cmdlet 在 Windows 预安装环境 (Windows PE) 上不受支持。
另请参阅
Get-Help
Save-Help
Update-Help
可更新帮助状态表