Erstellen von Get-WinEvent-Abfragen mit FilterHashtable

Artikel
2025-04-07

Dieses Beispiel gilt nur für Windows-Plattformen.

Informationen zum Lesen des ursprünglichen Blogbeitrags vom 3. Juni 2014 Scripting Guy finden Sie unter Verwenden von FilterHashTable zum Filtern des Ereignisprotokolls mit PowerShell.

Dieser Artikel ist ein Auszug aus dem ursprünglichen Blogbeitrag und erläutert, wie der FilterHashtable-Parameter des Get-WinEvent Cmdlets zum Filtern von Ereignisprotokollen verwendet wird. Das Cmdlet von Get-WinEvent PowerShell ist eine leistungsstarke Methode zum Filtern von Windows-Ereignis- und Diagnoseprotokollen. Die Leistung verbessert sich, wenn eine Get-WinEvent Abfrage den FilterHashtable-Parameter verwendet.

Wenn Sie mit großen Ereignisprotokollen arbeiten, ist es nicht effizient, Objekte durch die Pipeline an einen Where-Object Befehl zu senden. Vor PowerShell 6 war das Get-EventLog Cmdlet eine weitere Option zum Abrufen von Protokolldaten. Beispielsweise sind die folgenden Befehle ineffizient, um die Microsoft-Windows-Defrag-Protokolle zu filtern:

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

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

Der folgende Befehl verwendet eine Hashtabelle, die die Leistung verbessert:

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

Blogbeiträge zur Aufzählung

Dieser Artikel enthält Informationen zur Verwendung von aufgezählten Werten in einer Hashtabelle. Weitere Informationen zur Aufzählung finden Sie in diesen Skripting Guy-Blogbeiträgen. Informationen zum Erstellen einer Funktion, die die aufgezählten Werte zurückgibt, finden Sie unter Enumerationen und Werte. Weitere Informationen finden Sie in der Scripting Guy-Reihe von Blogbeiträgen zur Enumeration.

Schlüssel-Wert-Paare für Hashtabellen

Verwenden Sie das Get-WinEvent Cmdlet mit dem Parameter "FilterHashtable ", um effiziente Abfragen zu erstellen. FilterHashtable akzeptiert eine Hashtabelle als Filter, um bestimmte Informationen aus Windows-Ereignisprotokollen abzurufen. Eine Hashtabelle verwendet Schlüssel-Wert-Paare . Weitere Informationen zu Hashtabellen finden Sie unter about_Hash_Tables (Informationen zu Hashtabellen).

Wenn sich die Schlüsselwertpaare in derselben Zeile befinden, müssen sie durch ein Semikolon getrennt werden. Wenn sich jedes Schlüssel-Wert-Paar in einer separaten Zeile befindet, wird das Semikolon nicht benötigt. In diesem Artikel werden beispielsweise Schlüsselwertpaare in separate Zeilen platziert und keine Semikolons verwendet.

In diesem Beispiel werden mehrere Schlüsselwertpaare des FilterHashtable-Parameters verwendet. Die abgeschlossene Abfrage enthält LogName, ProviderName, Schlüsselwörter, ID und Ebene.

Die akzeptierten Schlüssel-Wert-Paare werden in der folgenden Tabelle angezeigt und sind in der Dokumentation für den Parameter "Get-WinEventFilterHashtable " enthalten.

In der folgenden Tabelle werden die Schlüsselnamen, Datentypen und die Zulässigkeit von Platzhalterzeichen für einen Datenwert angezeigt.

Schlüsselname	Wertdatentyp	Platzhalterzeichen akzeptiert?
LogName	`<String[]>`	Ja
ProviderName	`<String[]>`	Ja
Pfad	`<String[]>`	Nein
Schlüsselwörter	`<Long[]>`	Nein
ID	`<Int32[]>`	Nein
Niveau	`<Int32[]>`	Nein
Startzeit	`<DateTime>`	Nein
EndTime	`<DateTime>`	Nein
UserID	`<SID>`	Nein
Daten	`<String[]>`	Nein
`<named-data>`	`<String[]>`	Nein

Der <named-data> Schlüssel stellt ein benanntes Ereignisdatenfeld dar. Beispielsweise kann das Perflib-Ereignis 1008 die folgenden Ereignisdaten enthalten:

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

Sie können diese Ereignisse mithilfe des folgenden Befehls abfragen:

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

Hinweis

Die Möglichkeit zum Abfragen von <named-data> wurde in PowerShell 6 hinzugefügt.

Erstellen einer Abfrage mit einer Hashtabelle

Es ist sinnvoll, die Hashtabelle aus jeweils einzelnen Schlüssel-Wert-Paaren aufzubauen, um die Ergebnisse zu überprüfen und Probleme zu behandeln. Die Abfrage ruft Daten aus dem Anwendungsprotokoll ab. Die Hashtabelle entspricht Get-WinEvent -LogName Application.

Erstellen Sie zunächst die Get-WinEvent Abfrage. Verwenden Sie das Schlüssel-Wert-Paar des FilterHashtable-Parameters mit dem Schlüssel, LogName und dem Wert Application.

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

Fahren Sie mit dem ProviderName-Schlüssel fort, um die Hashtabelle zu erstellen. Normalerweise ist "ProviderName" der Name, der im Feld "Quelle " in der Windows-Ereignisanzeige angezeigt wird. Beispiel: .NET Runtime Im folgenden Screenshot:

Abbildung der Windows-Ereignisanzeigequellen

Aktualisieren Sie die Hashtabelle, und schließen Sie das Schlüssel-Wert-Paar mit dem Schlüssel, ProviderName und dem Wert ein. .NET Runtime

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

Hinweis

Bei einigen Ereignisanbietern kann der richtige ProviderName abgerufen werden, indem er auf der Registerkarte "Details " in den Ereigniseigenschaften nachschaut. Beispielsweise bei Ereignissen, bei denen im Feld "Quelle"Defrag angezeigt wird, ist der korrekte ProviderNameMicrosoft-Windows-Defrag.

Wenn Ihre Abfrage Daten aus archivierten Ereignisprotokollen abrufen muss, verwenden Sie den Pfadschlüssel . Der Pfadwert gibt den vollständigen Pfad zur Protokolldatei an. Weitere Informationen finden Sie im Blogbeitrag Scripting Guy , Verwenden von PowerShell zum Analysieren gespeicherter Ereignisprotokolle für Fehler.

Verwenden von aufgezählten Werten in einer Hashtabelle

Schlüsselwörter sind der nächste Schlüssel in der Hashtabelle. Der Datentyp Schlüsselwörter ist ein Array des [long]-Wertetyps, das eine große Zahl enthält. Verwenden Sie den folgenden Befehl, um den Maximalwert von [long] zu finden.

[long]::MaxValue

9223372036854775807

Für den Schlüssel "Schlüsselwörter " verwendet PowerShell eine Zahl, keine Zeichenfolge wie Sicherheit. Die Windows-Ereignisanzeige zeigt die Schlüsselwörter als Zeichenfolgen an, aber sie werden aufgezählt. Wenn Sie in der Hashtabelle den Schlüssel "Schlüsselwörter " mit einem Zeichenfolgenwert verwenden, wird eine Fehlermeldung angezeigt.

Öffnen Sie die Windows-Ereignisanzeige , und klicken Sie im Bereich "Aktionen " auf " Aktuelles Protokoll filtern". Das Dropdownmenü "Schlüsselwörter " zeigt die verfügbaren Schlüsselwörter an, wie im folgenden Screenshot gezeigt:

Abbildung der Schlüsselwörter der Windows-Ereignisanzeige

Verwenden Sie den folgenden Befehl, um die StandardEventKeywords Eigenschaftennamen anzuzeigen.

[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…

Die Aufzählungswerte werden im .NET Framework dokumentiert. Weitere Informationen finden Sie unter "StandardEventKeywords-Aufzählung".

Die Schlüsselwörternamen und Enumerationswerte sind wie folgt:

Name	Wert
Prüfungsfehler	4503599627370496
AuditSuccess	9007199254740992
CorrelationHint2	18014398509481984
EventLogClassic	36028797018963968
Sqm	2251799813685248
WdiDiagnostic	1125899906842624
WdiContext	562949953421312
ResponseTime	281474976710656
Nichts	0

Aktualisieren Sie die Hashtabelle, und schließen Sie das Schlüssel-Wert-Paar mit dem Schlüssel, Schlüsselwörtern und dem EventLogClassic-Enumerationswert36028797018963968 ein.

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

Statischer Eigenschaftswert der Keywords-Eigenschaft (optional)

Der Schlüssel "Schlüsselwörter " wird aufgezählt, Sie können jedoch einen statischen Eigenschaftsnamen in der Hashtabellenabfrage verwenden. Anstatt die zurückgegebene Zeichenfolge zu verwenden, muss der Eigenschaftsname in einen Wert mit der value__ -Eigenschaft konvertiert werden.

Das folgende Skript verwendet z. B. die eigenschaft value__ .

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

Filtern nach Ereignis-ID

Um spezifischere Daten abzurufen, werden die Ergebnisse der Abfrage nach Der Ereignis-ID gefiltert. Auf die Ereignis-ID wird in der Hashtabelle als Schlüssel-ID verwiesen, und der Wert ist eine bestimmte Ereignis-ID. Die Windows-Ereignisanzeige zeigt die Ereignis-ID an. In diesem Beispiel wird die Ereignis-ID 1023 verwendet.

Aktualisieren Sie die Hashtabelle, und schließen Sie das Schlüssel-Wert-Paar mit dem Schlüssel, der ID und dem Wert 1023 ein.

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

Filtern nach Ebene

Um die Ergebnisse weiter zu verfeinern und nur Ereignisse einzuschließen, die Fehler sind, verwenden Sie den Level-Schlüssel . Die Windows-Ereignisanzeige zeigt die Ebene als Zeichenfolgenwerte an, allerdings handelt es sich um aufgezählte Werte. Wenn Sie in der Hashtabelle den Schlüssel " Ebene " mit einem Zeichenfolgenwert verwenden, wird eine Fehlermeldung angezeigt.

Die Ebene weist Werte wie Fehler, Warnung oder Informational auf. Verwenden Sie den folgenden Befehl, um die StandardEventLevel Eigenschaftennamen anzuzeigen.

[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;}

Die Aufzählungswerte werden im .NET Framework dokumentiert. Weitere Informationen finden Sie unter "StandardEventLevel-Aufzählung".

Die Namen und Aufzählungswerte des Levelschlüssels sind wie folgt:

Name	Wert
Ausführlich	5
Informativ	4
Warnung	3
Fehler	2
Kritisch	1
LogAlways	0

Die Hashtabelle für die abgeschlossene Abfrage enthält den Schlüssel, die Ebene und den Wert 2.

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

Statische Level-Eigenschaft in der Enumeration (optional)

Der Schlüssel "Ebene" wird aufgezählt, und Sie können jedoch einen statischen Eigenschaftsnamen in der Hashtabellenabfrage verwenden. Anstatt die zurückgegebene Zeichenfolge zu verwenden, muss der Eigenschaftsname in einen Wert mit der value__ -Eigenschaft konvertiert werden.