about_Updatable_Help

简短说明

介绍 PowerShell 中的可更新帮助系统。

长说明

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

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

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

在 PowerShell 4.0 中，HelpInfoUri 属性通过 Windows PowerShell 远程处理保留，这使得 Save-Help 适用于安装在远程计算机上、但不一定安装在本地计算机上的模块。 可以通过在无法访问 Internet 的计算机上运行 Export-Clixml，在可以访问 Internet 的计算机上导入 PSModuleInfo 对象，然后在 PSModuleInfo 对象上运行 Save-Help，将 PSModuleInfo 对象保存到磁盘或可移动媒体（如 USB 驱动器）。 保存的帮助可以通过使用可移动媒体复制到远程断开连接的计算机，然后通过运行 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 和访问联机帮助主题的备注。

例如，以下命令获取 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 的帮助，你必须是计算机上的管理员组的成员。

如果你不是管理员组的成员，则无法更新这些模块的帮助；但是，如果你有 Internet 访问权限，则可以查看联机帮助。

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

Update-Help 和 Save-Help cmdlet 具有提供当前用户的显式凭据的 UseDefaultCredentials 参数。 此参数旨在访问安全的 Internet 位置。

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

如何安装和更新帮助文件

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

Update-Help cmdlet 为你执行所有繁琐的工作，包括以下任务。

• 确定哪些模块支持可更新帮助。
• 查找每个模块存储其可更新帮助文件的 Internet 位置。
• 将计算机上的每个模块的帮助文件与每个模块可用的最新帮助文件进行比较。
• 从 Internet 下载新文件。
• 解包帮助文件包。
• 验证文件是否为有效的帮助文件。
• 在模块目录的语言特定子目录中安装帮助文件。

若要访问新的帮助主题，请使用 Get-Help cmdlet。 无需重启 PowerShell。

若要在支持可更新帮助的计算机上安装或更新所有模块的帮助，请键入：

Update-Help

若要更新特定模块的帮助，请添加 Update-Help 的模块参数。 模块名称中允许使用通配符。

例如，若要更新 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 的联机参数。

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

Get-Help Get-Job -Online

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

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

如何最小化或阻止 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 命令之前，请将模块导入到当前会话或 Invoke-Command 脚本块中，该块已连接到远程计算机。

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

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

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

如何支持可更新的帮助

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

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

备注

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

另请参阅

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