在 PowerShell 中解释帮助文件内容并更新本地帮助内容

已完成

找到任务所需的命令时,可使用其帮助文件来了解如何使用。 其中一种方法是查看示例并尝试了解其用法。 但很少有示例能够涵盖该命令用法的所有可能变体。 了解如何解释帮助文件语法有助于确定给定命令的所有功能。

Get-EventLog 帮助

以 Get-EventLog 的帮助为例。 如果在控制台中输入命令 Get-Help Get-EventLog 并按 Enter 键,帮助将返回以下语法:

Get-EventLog [-LogName] <String> [[-InstanceId] <Int64[]>] [-After <DateTime>] [-AsBaseObject] [-Before <DateTime>] [-ComputerName <String[]>] [-EntryType {Error | Information | FailureAudit | SuccessAudit | Warning}] [-Index <Int32[]>] [-Message <String>] [-Newest <Int32>] [-Source <String[]>] [-UserName <String[]>] [<CommonParameters>]

Get-EventLog [-AsString] [-ComputerName <String[]>] [-List] [<CommonParameters>]

这两个文本块是参数集,每一个都表示可以运行命令的一种方式。 请注意,两个参数集都有许多参数,并且包含几个共同的参数。 不能在参数集之间混合和匹配参数。 也就是说,如果决定使用 –List 参数,则不能同时使用 –LogName,因为这些参数不会一起出现在同一个参数集中。

–LogName 参数名称用方括号括起来,这意味着它是一个位置参数。 不能运行不带日志名称的命令。 但无需输入 –LogName 参数名称。 需要将日志名称字符串作为第一个参数传递,因为这是帮助文件中出现 –LogName 参数的位置。 因此,以下两个命令提供相同的结果:

Get-EventLog –LogName Application
Get-EventLog Application

省略参数名称

省略参数名称时需谨慎,原因如下。 不能省略所有参数。 例如,‑ComputerName 参数不能省略参数名称。 此外,你会很快无法对内容进行跟踪。 提供参数名称时,参数可按任意顺序显示,如以下命令所示:

Get-EventLog –ComputerName LON-DC1 –LogName Application –Newest 10

但在省略参数名称时,必须确保按正确的顺序输入参数。 例如,由于日志名称值未显示在正确位置,以下命令不起作用:

Get-EventLog –ComputerName LON-DC1 Application

指定多个值

某些参数接受多个值。 在语法部分,参数值类型中的双方括号表示法指定这些参数。 例如:

-ComputerName <string[]>

上述语法指示 –ComputerName 参数可以接受一个或多个字符串值。 指定多个值的一种方法是使用逗号分隔的列表。 无需用引号将值括起来,除非值本身包含逗号或空格,例如空格字符或制表符。 例如,使用以下命令指定多个计算机名:

Get-EventLog –LogName Application –ComputerName LON-CL1,LON-DC1

注意

可通过查看命令的完整帮助找到有关每个参数的详细信息。 例如,运行 Get-Help Get-EventLog –Full 查看 Get-EventLog 的完整帮助,并注意显示的其他信息。 例如,可以确认 –LogName 参数是必需的,并且出现在第一个位置。

最佳做法:如果刚开始使用 Windows PowerShell,请尝试提供完整的参数名称,而不是按位置传递参数值。 使用完整的参数名称更易于查看命令和对其进行故障排除,如果你输入的命令不正确,也更容易发现错误。

更新帮助

Windows PowerShell 3.0 和更高版本不会随附帮助文件。 而是以联机服务的形式提供帮助文件。 Microsoft 创作的命令将其帮助文件托管在 Microsoft 拥有的 Web 服务器上。 只要作者或供应商正确生成模块并提供帮助文件的联机位置,有时可联机获得非 Microsoft 命令。 通过使用联机模型,编写命令的作者(包括 Microsoft 作者)可以随着时间的推移对其帮助文件进行更改和改进,然后交付这些文件,而无需创建整个产品更新。

运行 Update-Help 扫描计算机以查找所有已安装的模块,检索每个模块的联机帮助位置,并尝试下载其各自的帮助文件。 必须以本地管理员组成员的身份运行此命令,因为 Windows PowerShell 核心命令帮助存储在 %systemdir% 文件夹中。 如果无法下载帮助,将显示错误消息。 在这种情况下,Windows PowerShell 仍会为命令创建默认帮助显示。

Windows PowerShell 默认以系统配置的语言下载帮助文件。 如果没有以该语言编写的帮助,Windows PowerShell 默认使用 en-US(美国英语)语言。 可使用 Update-Help 的参数来指定要为其检索帮助的 UICulture 来重写此行为。

默认情况下,即使连续多次运行命令,Update-Help 也会每 24 小时检查一次帮助文件。 若要重写此行为,请包括 –Force 参数。

与 Update-Help 配套的是 Save-Help。 它会下载帮助内容并将其保存到指定的位置。 利用此功能可将该内容复制到未连接到 Internet 的计算机。 Update-Help 提供了一个参数来指定替代源位置。 通过此功能,可在未连接到 Internet 的计算机上更新帮助。

在 Windows PowerShell 4.0 之前,Update-Help 和 Save-Help 只下载安装在本地计算机(运行命令的位置)上的 cmdlet 的帮助。 在 Windows PowerShell 4.0 和更高版本中,可对安装在远程计算机上的模块使用 Save-Help。