New-WinEvent

为指定的事件提供程序创建一个新的 Windows 事件。

语法

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

说明

New-WinEvent cmdlet 可为事件提供程序创建 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 用于从组策略事件提供程序中获取事件 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.

“说明”属性包含写入事件日志的消息。 %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

指定在事件提供程序中注册的事件 ID。

类型:Int32
Position:2
默认值:None
必需:True
接受管道输入:False
接受通配符:False

-Payload

有效负载是作为位置参数传递给事件模板的值数组。 这些值会插入模板中以构造事件的消息。 事件可以有多个使用不同格式的模板版本。

如果有效负载中的值与模板中的类型不匹配,会记录事件,但有效负载包含错误。

类型:Object[]
Position:3
默认值:None
必需:False
接受管道输入:False
接受通配符:False

-ProviderName

指定将事件写入事件日志的事件提供程序,例如“Microsoft-Windows-PowerShell”。 ETW 事件提供程序是将事件写入 ETW 会话的逻辑实体。

类型:String
Position:1
默认值:None
必需:True
接受管道输入:False
接受通配符:False

-Version

指定事件的版本号。 PowerShell 将该数目转换为所需的字节类型。 当定义相同事件的不同版本时,该值指定事件的版本。

类型:Byte
Position:Named
默认值:None
必需:False
接受管道输入:False
接受通配符:False

输入

None

不能通过管道将对象传递给此 cmdlet。

输出

None

此 cmdlet 不返回任何输出。

备注

提供程序将事件写入事件日志后,可以使用 Get-WinEvent cmdlet 从事件日志获取事件。