使用 FilterHashtable 创建 Get-WinEvent 查询Creating Get-WinEvent queries with FilterHashtable

本文内容

请参阅通过 PowerShell 使用 FilterHashTable 筛选事件日志，以查看 2014 年 6 月 3 日的原创“脚本专家”博客文章。

本文摘录自此原创博客文章，并说明了如何使用 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' }

下面的命令使用了可提升性能的哈希表：

  1. Get-WinEvent -FilterHashtable @{
  2.    LogName='Application'
  3.    ProviderName='*defrag'
  4. }

关于枚举的博客文章Blog posts about enumeration

本文提供了如何在哈希表中使用枚举值的相关信息。有关枚举的详细信息，请参阅“脚本专家”博客文章。若要创建用于返回枚举值的函数，请参阅枚举和值。有关详细信息，请参阅关于枚举的“脚本专家”系列博客文章。

哈希表键值对Hash table key/value pairs

若要生成高效查询，请将 Get-WinEvent cmdlet 和 FilterHashtable 参数结合使用。FilterHashtable 允许哈希表作为筛选器，以从 Windows 事件日志获取特定信息。哈希表将使用键值对。有关哈希表的详细信息，请参阅 about_Hash_Tables。

键值对均位于同一行时，必须使用分号将它们分隔开来。每个键值对位于单独的行时，则无需使用分号。例如，本文将键值对均放置在单独的行上，因此未使用分号。

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

下表显示了允许的键值对，关于 Get-WinEventFilterHashtable 参数的文档也包含这些键值对。

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

项名称值数据类型是否接受通配符？
LogName<String[]>是
ProviderName<String[]>是
路径<String[]>否
关键字<Long[]>否
ID<Int32[]>否
层次<Int32[]>否
StartTime<DateTime>否
EndTime<DateTime>否
UserID<SID>否
数据<String[]>否
*<String[]>否

使用哈希表生成查询Building a query with a hash table

若要验证结果并解决问题，它帮助生成一次包含一个键值对的哈希表。查询从“Application”日志获取数据。哈希表等效于 Get-WinEvent –LogName Application。

首先创建 Get-WinEvent 查询。使用 FilterHashtable 参数的键值对，其中键为“LogName”，值为“Application”。

  1. Get-WinEvent -FilterHashtable @{
  2.    LogName='Application'
  3. }

继续使用 ProviderName 键生成哈希表。ProviderName 是在“Windows 事件查看器”的“源”字段中显示的名称。例如，下面的屏幕截图中的“.NET 运行时”：

“Windows 事件查看器”源的图片。

更新哈希表，并包含键为 **ProviderName 且值为 .NET 运行时的键值对。

  1. Get-WinEvent -FilterHashtable @{
  2.    LogName='Application'
  3.    ProviderName='.NET Runtime'
  4. }

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

在哈希表中使用枚举值Using enumerated values in a hash table

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

  1. [long]::MaxValue
  1. 9223372036854775807

对于 Keywords 键，PowerShell 使用数字，而不是字符串（如 Security）。“Windows 事件查看器”将 Keywords 显示为字符串，但它们是枚举值。在哈希表中使用包含字符串值的 Keywords 键时，将显示错误消息。

打开“Windows 事件查看器”，从“操作”窗格单击“筛选当前日志”。“关键字”下拉菜单将显示可用的关键字，如下面的屏幕截图所示：

“Windows 事件查看器”关键字的图片。

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

  1. [System.Diagnostics.Eventing.Reader.StandardEventKeywords] | Get-Member -Static -MemberType Property
  1.    TypeName: System.Diagnostics.Eventing.Reader.StandardEventKeywords
  2. Name             MemberType Definition
  3. —-             ———- ———-
  4. AuditFailure     Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
  5. AuditSuccess     Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
  6. CorrelationHint  Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
  7. CorrelationHint2 Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
  8. EventLogClassic  Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
  9. None             Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
  10. ResponseTime     Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
  11. Sqm              Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
  12. WdiContext       Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…
  13. WdiDiagnostic    Property   static System.Diagnostics.Eventing.Reader.StandardEventKey…

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

Keywords 名称和枚举值如下所示：

名称值
AuditFailure4503599627370496
AuditSuccess9007199254740992
CorrelationHint218014398509481984
EventLogClassic36028797018963968
Sqm2251799813685248
WdiDiagnostic1125899906842624
WdiContext562949953421312
ResponseTime281474976710656
无0

更新哈希表，并包含键为 Keywords 且 EventLogClassic 枚举值为 36028797018963968 的键值对。

  1. Get-WinEvent -FilterHashtable @{
  2.    LogName='Application'
  3.    ProviderName='.NET Runtime'
  4.    Keywords=36028797018963968
  5. }

Keywords 静态属性值（可选）Keywords static property value (optional)

枚举 Keywords 键，但可以在哈希表查询中使用静态属性名称。必须使用 Value__ 属性将属性名称转换为值，而非使用返回值。

例如，下面的脚本就使用了 Value__ 属性。

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

按事件 ID 筛选Filtering by Event Id

若要获取更多特定数据，请按事件 ID 筛选查询的结果。哈希表将“事件 ID”引用为键 ID，其值为特定的“事件 ID”。“Windows 事件查看器”将显示“事件 ID”。此示例使用“事件 ID 1023”。

更新哈希表，并包含键为 ID 且值为 1023 的键值对。

  1. Get-WinEvent -FilterHashtable @{
  2.    LogName='Application'
  3.    ProviderName='.NET Runtime'
  4.    Keywords=36028797018963968
  5.    ID=1023
  6. }

按级别筛选Filtering by Level

若要进一步优化结果并仅包含属于错误的事件，请使用 Level 键。“Windows 事件查看器”将 Level 显示为字符串值，但它们是枚举值。在哈希表中使用包含字符串值的 Level 键时，将显示错误消息。

Level 包含诸如“错误”、“警告”或“信息性”等值。使用下面的命令显示 StandardEventLevel 属性名称。

  1. [System.Diagnostics.Eventing.Reader.StandardEventLevel] | Get-Member -Static -MemberType Property
  1.    TypeName: System.Diagnostics.Eventing.Reader.StandardEventLevel
  3. Name          MemberType Definition
  4. ----          ---------- ----------
  5. Critical      Property   static System.Diagnostics.Eventing.Reader.StandardEventLevel Critical {get;}
  6. Error         Property   static System.Diagnostics.Eventing.Reader.StandardEventLevel Error {get;}
  7. Informational Property   static System.Diagnostics.Eventing.Reader.StandardEventLevel Informational {get;}
  8. LogAlways     Property   static System.Diagnostics.Eventing.Reader.StandardEventLevel LogAlways {get;}
  9. Verbose       Property   static System.Diagnostics.Eventing.Reader.StandardEventLevel Verbose {get;}
  10. Warning       Property   static System.Diagnostics.Eventing.Reader.StandardEventLevel Warning {get;}

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

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

名称值
Verbose5
信息4
警告3
错误2
关键1
LogAlways0

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

  1. Get-WinEvent -FilterHashtable @{
  2.    LogName='Application'
  3.    ProviderName='.NET Runtime'
  4.    Keywords=36028797018963968
  5.    ID=1023
  6.    Level=2
  7. }

枚举中的 Level 静态属性（可选）Level static property in enumeration (optional)

枚举 Level 键，但可以在哈希表查询中使用静态属性名称。必须使用 Value__ 属性将属性名称转换为值，而非使用返回值。

例如，下面的脚本就使用了 Value__ 属性。

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