使用 FilterHashtable 建立 Get-WinEvent 查詢

發行項
11/08/2024

此範例僅適用於 Windows 平臺。

若要閱讀原始的 2014 年 6 月 3 日 Scripting Guy 部落格文章，請參閱使用 FilterHashTable 搭配 PowerShell 篩選事件記錄檔。

本文是原始部落格文章的摘錄，並說明如何使用 Get-WinEvent Cmdlet 的 FilterHashtable 參數來篩選事件記錄。 PowerShell 的 Get-WinEvent Cmdlet 是篩選 Windows 事件和診斷記錄的強大方法。當查詢使用 FilterHashtable 參數時Get-WinEvent，效能會改善。

當您使用大型事件記錄檔時，將物件向下傳送至 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'
}

關於列舉的部落格文章

本文提供如何在哈希表中使用列舉值的相關信息。如需列舉的詳細資訊，請閱讀這些 Scripting Guy 部落格文章。若要建立傳回列舉值的函式，請參閱列舉和值。如需詳細資訊，請參閱有關列舉的 Scripting Guy 系列部落格文章。

哈希表索引鍵/值組

若要建置有效率的 Get-WinEvent 查詢，請使用 Cmdlet 搭配 FilterHashtable 參數。 FilterHashtable 接受哈希表做為篩選條件，以從 Windows 事件記錄檔取得特定資訊。哈希表使用 索引鍵/值 組。如需有關雜湊表的詳細資訊，請參閱 about_Hash_Tables。

如果索引鍵/值組位於同一行，則必須以分號分隔。如果每個 機碼/值 組都位於個別行上，則不需要分號。例如，本文會將索引鍵/值組放在不同的行上，而且不會使用分號。

此範例會使用 FilterHashtable 參數的數個索引鍵/值組。已完成的查詢包括 LogName、ProviderName、關鍵詞、標識碼和層級。

下表顯示可接受的索引鍵/值組，並包含在 Get-WinEvent FilterHashtable 參數的檔中。

下表顯示索引鍵名稱、數據類型，以及數據值是否接受通配符。

金鑰名稱	實值數據類型	接受通配符？
LogName	`<String[]>`	Yes
ProviderName	`<String[]>`	Yes
路徑	`<String[]>`	No
關鍵字	`<Long[]>`	No
識別碼	`<Int32[]>`	No
層級	`<Int32[]>`	No
StartTime	`<DateTime>`	No
EndTime	`<DateTime>`	No
UserID	`<SID>`	No
資料	`<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。 例如，Source 欄位顯示 Defrag的事件，正確的 ProviderName 為 Microsoft-Windows-Defrag。

如果您的查詢需要從封存的事件記錄檔取得數據，請使用 Path 索引鍵。 Path 值會指定記錄檔的完整路徑。如需詳細資訊，請參閱 Scripting Guy 部落格文章：使用 PowerShell 剖析已儲存的事件記錄檔中的錯誤。

在哈希表中使用列舉值

關鍵詞是哈希表中的下一個索引鍵。 Keywords 數據類型是包含大量數位之[long]實值型別的陣列。使用下列命令來尋找的最大值 [long]：

[long]::MaxValue

9223372036854775807

針對關鍵詞索引鍵，PowerShell 會使用數位，而不是安全性之類的字串。 Windows 事件檢視器 會將關鍵詞顯示為字串，但它們是列舉值。在哈希表中，如果您使用 關鍵詞 索引鍵搭配字串值，則會顯示錯誤訊息。

開啟 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
無	0

更新哈希表，並包含索引鍵、關鍵詞和 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__
}

依事件標識碼篩選

若要取得更特定的數據，查詢的結果會依事件標識符進行篩選。哈希表中會參考事件標識碼做為索引鍵標識碼，而值是特定的事件標識碼。Windows 事件檢視器 會顯示事件標識碼。此範例使用事件標識碼 1023。

更新哈希表，並包含機碼、標識碼和值 1023 的索引鍵/值組。

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

依層級篩選

若要進一步精簡結果，並只包含錯誤的事件，請使用 Level 索引鍵。 Windows 事件檢視器 會將 Level 顯示為字串值，但會列舉這些值。在哈希表中，如果您使用 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 中。如需詳細資訊，請參閱 StandardEventLevel 列舉。

Level 索引鍵的名稱和列舉值如下所示：

名稱	值
詳細資訊	5
資訊	4
警告	3
錯誤	2
重大	1
LogAlways	0

已完成查詢的哈希表包含索引鍵、層級和值 2。

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

列舉中的 Level static 屬性（選擇性）

會列舉 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__
}

共用方式為

使用 FilterHashtable 建立 Get-WinEvent 查詢

關於列舉的部落格文章

哈希表索引鍵/值組

使用哈希表建置查詢

在哈希表中使用列舉值

關鍵字靜態屬性值（選擇性）

依事件標識碼篩選

依層級篩選

列舉中的 Level static 屬性（選擇性）

其他資源

共用方式為

使用 FilterHashtable 建立 Get-WinEvent 查詢

關於列舉的部落格文章

哈希表索引鍵/值組

使用哈希表建置查詢

在哈希表中使用列舉值

關鍵字靜態屬性值 （選擇性）

依事件標識碼篩選

依層級篩選

列舉中的 Level static 屬性 （選擇性）

其他資源

關鍵字靜態屬性值（選擇性）

列舉中的 Level static 屬性（選擇性）