New-WinEvent

模組:

Microsoft.PowerShell.Diagnostics Module

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

語法

Default (預設值)

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

Description

此 Cmdlet 只能在 Windows 平臺上使用。

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

範例

範例 1 - 建立新的事件

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

此命令會使用 New-WinEvent Cmdlet，為MicrosoftWindows-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 字串會被傳遞至 [PolicyElapsedTimeInSeconds] 字段的值取代。

範例 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

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

參數屬性

類型:	Int32
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	1
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Payload

載荷是一個數值陣列，作為位置參數傳遞至事件範本。 這些值會插入範本中，以建構事件的訊息。 事件可以有多個使用不同格式的範本版本。

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

參數屬性

類型:	Object[]
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	2
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ProviderName

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

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	0
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Version

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

參數屬性

類型:	Byte
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CommonParameters

此 Cmdlet 支援一般參數：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 如需詳細資訊，請參閱 about_CommonParameters。

輸入

None

您不能將物件透過管道傳送到此 Cmdlet。

輸出

None

此 Cmdlet 不會傳回任何輸出。

備註

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

相關連結

• Get-WinEvent