Compartir a través de

New-WinEvent

Módulo:
Microsoft.PowerShell.Diagnostics Module

Creates a new Windows event for the specified event provider.

Sintaxis

Default (Es el valor predeterminado). 

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

Description

The New-WinEvent cmdlet creates an Event Tracing for Windows (ETW) event for an event provider. You can use this cmdlet to add events to ETW channels from PowerShell.

Ejemplos

Example 1 - Create a new event

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

This command uses the New-WinEvent cmdlet to create event 45090 for the Microsoft-Windows-PowerShell provider.

Example 2 - Get the template for an event

In this example, Get-WinEvent is used to get the template for event id 8007 from the Group Policy event provider. Notice that the event has two formats.

In version 0, the IsMachine field is a boolean value. In version 1, the IsMachine field is an unsigned integer value.

(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.

The Description property contains the message that gets written to the event log. The %3 and %1 value are placeholders for the values passed into the template. The %3 string is replace with the value passed to the PrincipalSamName field. The %1 string is replaced with value passed to the PolicyElaspedTimeInSeconds field.

Example 3 - Create a new event using a versioned template

This example shows how to create an event using a specific template version.

$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

If the values in the payload do not match the types in the template, the event is logged but the payload contains an error.

Parámetros

-Id

Specifies an event Id that is registered in the event provider.

Propiedades del parámetro

Tipo:Int32
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:2
Mandatory:True
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-Payload

The payload is an array of values passed as positional arguments to the event template. The values are inserted into the template to construct the message for the event. Events can have multiple template versions that use different formats.

If the values in the payload do not match the types in the template, the event is logged but the payload contains an error.

Propiedades del parámetro

Tipo:

Object[]

Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:3
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-ProviderName

Specifies the event provider that writes the event to an event log, such as "Microsoft-Windows-PowerShell". An ETW event provider is a logical entity that writes events to ETW sessions.

Propiedades del parámetro

Tipo:String
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:1
Mandatory:True
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-Version

Specifies the version number of the event. PowerShell converts the number to the required Byte type. The value specifies the version of the event when different versions of the same event are defined.

Propiedades del parámetro

Tipo:Byte
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Entradas

None

You can't pipe objects to this cmdlet.

Salidas

None

This cmdlet returns no output.

Notas

After the provider writes the event to an eventlog, you can use the Get-WinEvent cmdlet to get the event from the event log.