New-WinEvent

模組:

Microsoft.PowerShell.Diagnostics Module

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

語法

Default (預設值)

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

Description

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

New-WinEvent 指令檔為事件提供者建立一個事件追蹤（ETW）事件，用於Windows。 你可以用這個 cmdlet 從 PowerShell 為 ETW 通道新增事件。

範例

範例 1 - 建立新事件

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

此指令使用 New-WinEvent cmdlet 來為 Microsoft-Windows-PowerShell 提供者建立事件 45090。

範例二 - 取得事件範本

在此範例中， Get-WinEvent 使用 是從群組政策事件提供者取得事件 ID 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 value 是傳遞到範本中的值的佔位符。 %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

指定一個已註冊於事件提供者的事件 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
預設值:	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