New-WinEvent

  • 參考
模組:
Microsoft.PowerShell.Diagnostics

為指定的事件提供者建立新的 Windows 事件。

Syntax

New-WinEvent
   [-ProviderName] <String>
   [-Id] <Int32>
   [-Version <Byte>]
   [[-Payload] <Object[]>]
   [<CommonParameters>]

Description

此 Cmdlet 僅適用於 Windows 平臺。

Cmdlet New-WinEvent 會為事件提供者建立 Windows 事件追蹤 （ETW） 事件。 您可以使用此 Cmdlet，從 PowerShell 將事件新增至 ETW 通道。

範例

範例 1 - 建立新的事件

New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Workflow", "Running")

此命令會 New-WinEvent 使用 Cmdlet 為 Microsoft-Windows-PowerShell 提供者建立事件 45090。

範例 2 - 取得事件的範本

在此範例中， Get-WinEvent 用來從組策略事件提供者取得事件標識碼 8007 的範本。 請注意，事件有兩種格式。

在版本 0 中 ，IsMachine 欄位是布爾值。 在版本 1 中 ，IsMachine 字段是無符號整數值。

(Get-WinEvent -ListProvider Microsoft-Windows-GroupPolicy).Events | Where-Object Id -eq 8007

Id          : 8007
Version     : 0
LogLink     : System.Diagnostics.Eventing.Reader.EventLogLink
Level       : System.Diagnostics.Eventing.Reader.EventLevel
Opcode      : System.Diagnostics.Eventing.Reader.EventOpcode
Task        : System.Diagnostics.Eventing.Reader.EventTask
Keywords    : {}
Template    : <template xmlns="http://schemas.microsoft.com/win/2004/08/events">
                <data name="PolicyElaspedTimeInSeconds" inType="win:UInt32" outType="xs:unsignedInt"/>
                <data name="ErrorCode" inType="win:UInt32" outType="win:HexInt32"/>
                <data name="PrincipalSamName" inType="win:UnicodeString" outType="xs:string"/>
                <data name="IsMachine" inType="win:Boolean" outType="xs:boolean"/>
                <data name="IsConnectivityFailure" inType="win:Boolean" outType="xs:boolean"/>
              </template>

Description : Completed periodic policy processing for user %3 in %1 seconds.

Id          : 8007
Version     : 1
LogLink     : System.Diagnostics.Eventing.Reader.EventLogLink
Level       : System.Diagnostics.Eventing.Reader.EventLevel
Opcode      : System.Diagnostics.Eventing.Reader.EventOpcode
Task        : System.Diagnostics.Eventing.Reader.EventTask
Keywords    : {}
Template    : <template xmlns="http://schemas.microsoft.com/win/2004/08/events">
                <data name="PolicyElaspedTimeInSeconds" inType="win:UInt32" outType="xs:unsignedInt"/>
                <data name="ErrorCode" inType="win:UInt32" outType="win:HexInt32"/>
                <data name="PrincipalSamName" inType="win:UnicodeString" outType="xs:string"/>
                <data name="IsMachine" inType="win:UInt32" outType="xs:unsignedInt"/>
                <data name="IsConnectivityFailure" inType="win:Boolean" outType="xs:boolean"/>
              </template>

Description : Completed periodic policy processing for user %3 in %1 seconds.

Description 屬性包含寫入事件記錄檔的訊息。 %3和 %1 值是傳遞至範本之值的佔位元。 字串 %3 會取代為傳遞至 PrincipalSamName 欄位的值。 字串 %1 會取代為傳遞至 PolicyElaspedTimeInSeconds 欄位的值。

範例 3 - 使用已建立版本的範本建立新事件

此範例示範如何使用特定範本版本建立事件。

$Payload = @(300, [uint32]'0x8001011f', $env:USERNAME, 0, 1)
New-WinEvent -ProviderName Microsoft-Windows-GroupPolicy -Id 8007 -Version 1 -Payload $Payload
Get-winEvent -ProviderName Microsoft-Windows-GroupPolicy -MaxEvents 1

ProviderName: Microsoft-Windows-GroupPolicy

TimeCreated            Id LevelDisplayName Message
-----------            -- ---------------- -------
5/4/2022 8:40:24 AM  8007 Information      Completed periodic policy processing for user User1 in 300 seconds

如果承載中的值不符合範本中的類型，則會記錄事件，但承載包含錯誤。

參數

-Id

指定事件提供者中註冊的事件標識碼。

Type:Int32
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Payload

承載是當做位置自變數傳遞至事件範本的值數位。 這些值會插入範本中，以建構事件的訊息。 事件可以有多個使用不同格式的範本版本。

如果承載中的值不符合範本中的類型，則會記錄事件，但承載包含錯誤。

Type:Object[]
Position:2
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ProviderName

指定將事件寫入事件記錄檔的事件提供者，例如 「Microsoft-Windows-PowerShell」。。 ETW 事件提供者是將事件寫入 ETW 工作階段的邏輯實體。

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Version

指定事件的版本號碼。 PowerShell 會將數字轉換成必要的 Byte 類型。 當定義相同事件的不同版本時，值會指定事件的版本。

Type:Byte
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

輸入

None

您無法使用管線將物件傳送至此 Cmdlet。

輸出

None

此 Cmdlet 不會傳回任何輸出。

備註

提供者將事件寫入事件記錄檔之後，您可以使用 Get-WinEvent Cmdlet 從事件記錄檔取得事件。