使用 FilterHashtable 创建 Get-WinEvent 查询

---

该示例仅适用于Windows平台。

要阅读 2014 年 6 月 3 日的原始脚本专家博客文章，请参阅使用 FilterHashTable 通过 PowerShell 筛选事件日志。

本文摘录自原始博客文章，介绍如何使用 Get-WinEvent cmdlet 的 FilterHashtable 参数来筛选事件日志。 PowerShell 的 Get-WinEvent cmdlet 是过滤 Windows 事件和诊断日志的强大方法。当 Get-WinEvent 查询使用 FilterHashtable 参数时，性能会提高。

当您处理大型事件日志时，将对象沿着管道发送到 Where-Object 命令的效率很低。在 PowerShell 6 之前，Get-EventLog cmdlet 是获取日志数据的另一个选项。例如，以下命令过滤 Microsoft-Windows-Defrag 日志的效率很低：

Get-EventLog -LogName Application | Where-Object Source -Match defrag

Get-WinEvent -LogName Application | Where-Object { $_.ProviderName -Match 'defrag' }

以下命令使用哈希表来提高性能：

Get-WinEvent -FilterHashtable @{
   LogName='Application'
   ProviderName='*defrag'
}

有关枚举的博客文章

本文介绍如何在哈希表中使用枚举值的信息。有关枚举的更多信息，请阅读这些脚本专家博客文章。要创建返回枚举值的函数，请参阅枚举和值。有关更多信息，请参阅有关枚举的脚本专家系列博客文章。

哈希表键值对

要构建高效的查询，请使用带有 FilterHashtable 参数的 Get-WinEvent cmdlet。 FilterHashtable 接受哈希表作为过滤器，以从 Windows 事件日志中获取特定信息。哈希表使用键值对。有关哈希表的更多信息，请参阅 about_Hash_Tables。

如果键值对位于同一行，则必须用分号分隔它们。如果每个键值对位于单独的行上，则不需要分号。例如，本文将键值对放在单独的行上，并且不使用分号。

此示例使用多个 FilterHashtable 参数的键值对。完成的查询包括LogName、ProviderName、Keywords、ID和Level。

接受的键值对如下表所示，并包含在 Get-WinEvent FilterHashtable 参数的文档中。

下表显示键名称、数据类型以及数据值是否接受通配符。

Key name Value data type Accepts wildcard characters? LogName <String[]> Yes ProviderName <String[]> Yes Path <String[]> No Keywords <Long[]> No ID <Int32[]> No Level <Int32[]> No StartTime <DateTime> No EndTime <DateTime> No UserID <SID> No Data <String[]> No <named-data> <String[]> No

<named-data> 键表示命名事件数据字段。例如，Perflib 事件 1008 可以包含以下事件数据：

<EventData>
  <Data Name="Service">BITS</Data>
  <Data Name="Library">C:\Windows\System32\bitsperf.dll</Data>
  <Data Name="Win32Error">2</Data>
</EventData>

您可以使用以下命令查询这些事件：

Get-WinEvent -FilterHashtable @{LogName='Application'; 'Service'='Bits'}

笔记

PowerShell 6 中添加了查询 <named-data> 的功能。

使用哈希表构建查询

为了验证结果和解决问题，一次构建一个键值对的哈希表会很有帮助。该查询从应用程序日志中获取数据。哈希表相当于Get-WinEvent -LogName Application。

首先，创建 Get-WinEvent 查询。将 FilterHashtable 参数的键值对与键 LogName 和值 Application 结合使用。

Get-WinEvent -FilterHashtable @{
   LogName='Application'
}

继续使用 ProviderName 键构建哈希表。通常，ProviderName 是出现在Windows 事件查看器 的源 字段中的名称。例如，以下屏幕截图中的 .NET Runtime：

Windows 事件查看器源图像

更新哈希表并包含带有键 ProviderName 和值 .NET Runtime 的键值对。

Get-WinEvent -FilterHashtable @{
   LogName='Application'
   ProviderName='.NET Runtime'
}

笔记

对于某些事件提供程序，可以通过查看事件属性中的详细信息选项卡来获取正确的ProviderName。例如，源字段显示Defrag的事件，正确的ProviderName是Microsoft-Windows-Defrag。

如果您的查询需要从存档的事件日志中获取数据，请使用Path 键。 路径值指定日志文件的完整路径。有关详细信息，请参阅脚本专家博客文章使用 PowerShell 解析保存的事件日志中的错误。

在哈希表中使用枚举值

关键字是哈希表中的下一个键。 Keywords 数据类型是一个包含大量数字的 [long] 值类型的数组。使用以下命令查找 [long] 的最大值：

[long]::MaxValue

9223372036854775807

对于 Keywords 键，PowerShell 使用数字，而不是 Security 等字符串。 Windows 事件查看器将关键字显示为字符串，但它们是枚举值。在哈希表中，如果将 Keywords 键与字符串值一起使用，则会显示错误消息。

打开Windows 事件查看器，然后在操作窗格中单击过滤当前日志。 关键字下拉菜单显示可用的关键字，如以下屏幕截图所示：

Windows 事件查看器关键字的图像

使用以下命令显示 StandardEventKeywords 属性名称。

[System.Diagnostics.Eventing.Reader.StandardEventKeywords] |
    Get-Member -Static -MemberType Property

   TypeName: System.Diagnostics.Eventing.Reader.StandardEventKeywords
Name             MemberType Definition
—-             ———- ———-
AuditFailure     Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
AuditSuccess     Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
CorrelationHint  Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
CorrelationHint2 Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
EventLogClassic  Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
None             Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
ResponseTime     Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
Sqm              Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
WdiContext       Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
WdiDiagnostic    Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…

枚举值记录在 .NET Framework 中。有关详细信息，请参阅 StandardEventKeywords 枚举。

关键字名称和枚举值如下：

AuditFailure

4503599627370496

AuditSuccess

9007199254740992

CorrelationHint2

18014398509481984

EventLogClassic

36028797018963968

Sqm

2251799813685248

WdiDiagnostic

1125899906842624

WdiContext

562949953421312

ResponseTime

281474976710656

None

0

更新哈希表并包含键值对，其中包含键 Keywords 和 EventLogClassic 枚举值 36028797018963968。

Get-WinEvent -FilterHashtable @{
   LogName='Application'
   ProviderName='.NET Runtime'
   Keywords=36028797018963968
}

关键字静态属性值（可选）

Keywords 键已枚举，但您可以在哈希表查询中使用静态属性名称。必须使用 Value__ 属性将属性名称转换为值，而不是使用返回的字符串。

例如，以下脚本使用 Value__ 属性。

$C = [System.Diagnostics.Eventing.Reader.StandardEventKeywords]::EventLogClassic
Get-WinEvent -FilterHashtable @{
   LogName='Application'
   ProviderName='.NET Runtime'
   Keywords=$C.Value__
}

按事件 ID 过滤

为了获取更具体的数据，查询结果会按事件 ID 进行过滤。 事件 Id 在哈希表中作为键 ID 引用，值是特定的事件 Id。 Windows 事件查看器 显示事件 ID。此示例使用事件 ID 1023。

更新哈希表并包含带有键 ID 和值 1023 的键值对。

Get-WinEvent -FilterHashtable @{
   LogName='Application'
   ProviderName='.NET Runtime'
   Keywords=36028797018963968
   ID=1023
}

按级别过滤

要进一步细化结果并仅包含错误事件，请使用级别键。 Windows 事件查看器将级别显示为字符串值，但它们是枚举值。在哈希表中，如果将 Level 键与字符串值一起使用，则会显示错误消息。

级别具有错误、警告或信息等值。使用以下命令显示 StandardEventLevel 属性名称。

[System.Diagnostics.Eventing.Reader.StandardEventLevel] |
    Get-Member -Static -MemberType Property

   TypeName: System.Diagnostics.Eventing.Reader.StandardEventLevel

Name          MemberType Definition
----          ---------- ----------
Critical      Property   static System.Diagnostics.Eventing.Reader.StandardEventLevel Critical {get;}
Error         Property   static System.Diagnostics.Eventing.Reader.StandardEventLevel Error {get;}
Informational Property   static System.Diagnostics.Eventing.Reader.StandardEventLevel Informational {get;}
LogAlways     Property   static System.Diagnostics.Eventing.Reader.StandardEventLevel LogAlways {get;}
Verbose       Property   static System.Diagnostics.Eventing.Reader.StandardEventLevel Verbose {get;}
Warning       Property   static System.Diagnostics.Eventing.Reader.StandardEventLevel Warning {get;}

枚举值记录在 .NET Framework 中。有关详细信息，请参阅标准事件级别枚举。

Level键的名称和枚举值如下：

Verbose

5

Informational

4

Warning

3

Error

2

Critical

1

LogAlways

0

已完成查询的哈希表包含键 Level 和值 2。

Get-WinEvent -FilterHashtable @{
   LogName='Application'
   ProviderName='.NET Runtime'
   Keywords=36028797018963968
   ID=1023
   Level=2
}

枚举中的级别静态属性（可选）

Level 键已枚举，但您可以在哈希表查询中使用静态属性名称。必须使用 Value__ 属性将属性名称转换为值，而不是使用返回的字符串。

例如，以下脚本使用 Value__ 属性。

$C = [System.Diagnostics.Eventing.Reader.StandardEventLevel]::Informational
Get-WinEvent -FilterHashtable @{
   LogName='Application'
   ProviderName='.NET Runtime'
   Keywords=36028797018963968
   ID=1023
   Level=$C.Value__
}