关于可更新的帮助

简短描述

描述 PowerShell 中的可更新帮助系统。

详细描述

PowerShell 提供了多种不同的方法来访问 PowerShell cmdlet 和概念的最新帮助主题。

PowerShell 3.0 中引入的可更新帮助系统旨在确保您始终在本地计算机上拥有最新的帮助主题，以便您可以在命令行中阅读它们。它可以轻松下载和安装帮助文件，并在有新的帮助文件可用时更新它们。

要为企业中的多台计算机和无法访问 Internet 的计算机提供更新的帮助，可更新帮助允许您将帮助文件下载到文件系统目录或文件共享，然后从文件共享安装帮助文件。

在 PowerShell 4.0 中，HelpInfoUri 属性是通过 Windows PowerShell 远程处理保留的，这允许 Save-Help 适用于安装在远程计算机上的模块，但不一定安装在本地计算机上。您可以通过在无法访问 Internet 的计算机上运行 Export-Clixml 将 PSModuleInfo 对象保存到磁盘或可移动媒体（例如 USB 驱动器），导入可以访问 Internet 的计算机上的 PSModuleInfo 对象，然后在 PSModuleInfo 对象上运行 Save-Help。可以使用可移动介质将保存的帮助复制到远程、断开连接的计算机，然后通过运行 Update-Help 进行安装。 Save-Help 功能的这些改进使您可以在没有任何网络访问权限的计算机上安装帮助。有关如何使用新的 Save-Help 功能的示例，请参阅本主题中的如何从文件共享更新帮助。

可更新的帮助还支持在线访问最新的帮助主题和 cmdlet 的基本帮助，即使计算机上没有帮助文件也是如此。

PowerShell 不附带帮助文件。您可以使用可更新帮助功能来安装 PowerShell 默认包含的所有命令和所有 Windows 模块的帮助文件。

可更新的帮助 cmdlet

• Update-Help：从 Internet 或文件共享下载最新的帮助文件，并将其安装在本地计算机上。

• Save-Help：从互联网下载最新的帮助文件并将其保存在文件系统目录或文件共享中。要在计算机上安装帮助文件，请使用 Update-Help。

• Get-Help：在命令行显示帮助主题。从计算机上的帮助文件获取帮助。显示没有帮助文件的 cmdlet 和函数的自动生成帮助。在默认 Internet 浏览器中打开 cmdlet、函数、脚本和工作流的联机帮助主题。

自动生成帮助：没有帮助文件的帮助

如果您的计算机上没有 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 中模块的帮助，您必须是计算机上管理员组的成员。

如果您不是管理员组的成员，则无法更新这些模块的帮助；但如果您可以访问互联网，则可以在线查看帮助。

更新 $HOME/Documents/PowerShell/Modules 目录中的模块或 $HOME 目录其他子目录中的模块的帮助不需要特殊权限。

Update-Help 和 Save-Help cmdlet 有一个 UseDefaultCredentials 参数，用于提供当前用户的显式凭据。此参数设计用于访问安全的互联网位置。

Update-Help 和 Save-Help cmdlet 还具有一个 Credential 参数，允许您在远程计算机上运行命令并访问文件在第三台计算机上共享。仅当您使用 Update-Help 的 SourcePath 或 LiteralPath 参数以及 DestinationPath 或Save-Help 的 LiteralPath 参数。

如何安装和更新帮助文件

要首次下载并安装帮助文件，或者更新计算机上的帮助文件，请使用 Update-Help cmdlet。

Update-Help cmdlet 会为您完成所有艰苦的工作，包括以下任务。

• 确定哪些模块支持可更新帮助。
• 查找每个模块存储其可更新帮助文件的 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。 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。

$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 中，然后对保存在 $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:\UsbDrive\DhcpModule.xml -InputObject $m

接下来，将可移动媒体传输到可以访问 Internet 的计算机，然后使用 Import-Clixml 导入 PSModuleInfo 对象。运行 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 语言回退规则来查找最受支持的语言。

但是，您可以使用 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 将返回一条错误消息，其中列出了该帮助文件所使用的语言。每个模块都有帮助，因此您可以选择最能满足您需求的替代方案。

笔记

目前，可更新帮助内容仅以英语 (en-US) 发布。

如何使用在线帮助

如果您无法或选择不更新本地计算机上的帮助文件，您仍然可以在线获取最新的帮助文件。

要打开任何 cmdlet 或函数的联机帮助主题，请使用 Get-Help cmdlet 的 Online 参数。

例如，以下命令在默认 Internet 浏览器中打开 Get-Job cmdlet 的联机帮助主题：

Get-Help Get-Job -Online

要获取脚本的联机帮助，请使用 Online 参数和脚本的完整路径。

在线参数不适用于“关于”主题。要查看有关 PowerShell 的主题（包括有关 PowerShell 语言的帮助主题），请参阅 PowerShell 关于主题。

如何减少或阻止互联网下载

要最大程度地减少 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 命令之前，将模块导入到连接到远程计算机的当前会话或 Invoke-Command 脚本块中。

当模块位于当前会话中时，运行不带参数的 Update-Help 或 Save-Help cmdlet，或使用 Module 参数指定模块名称。

Update-Help 和 Save-Help cmdlet 的 Module 参数仅接受模块名称。他们不接受模块文件的路径。

使用此技术可以更新或保存 Get-Module cmdlet 的 ListAvailable 参数未返回的任何模块的帮助，例如安装在不正确位置的模块$env:PSModulePath 环境变量中列出的模块，或格式不正确的模块（模块目录不包含至少一个基本名称与目录名称相同的文件）。

如何支持可更新的帮助

如果您创作模块，则可以支持模块的在线帮助和可更新帮助。有关详细信息，请参阅支持可更新帮助和支持联机帮助。

可更新的帮助不适用于 PowerShell 管理单元或基于注释的帮助。

评论

Windows 预安装环境 (Windows PE) 不支持 Update-Help 和 Save-Help cmdlet。

参见

• Get-Help
• Save-Help
• Update-Help