| Service | Microsoft Docs article | Related commit history on GitHub | Change details |
|---|---|---|---|
| Microsoft.PowerShell.Diagnostics | New Winevent (5.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Diagnostics/New-WinEvent.md | external help file: Microsoft.PowerShell.Commands.Diagnostics.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Diagnostics Previously updated : 09/28/2021 Last updated : 05/04/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.diagnostics/new-winevent?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: New-WinEvent New-WinEvent [-ProviderName] <String> [-Id] <Int32> [-Version <Byte>] [[-Payload ## 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 Windows PowerShell. +You can use this cmdlet to add events to ETW channels from PowerShell. ## EXAMPLES -### Example 1 +### Example 1 - Create a new event ```powershell New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Workflow", "Running") New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Wo 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. ++```powershell +(Get-WinEvent -ListProvider Microsoft-Windows-GroupPolicy).Events | Where-Object Id -eq 8007 +``` ++```Output +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 withe 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. ++```powershell +$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 +``` ++```Output + 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. + ## PARAMETERS ### -Id -Specifies an event id that was registered through an instrumentation manifest. +Specifies an event Id that is registered in the event provider. ```yaml Type: System.Int32 Accept wildcard characters: False ### -Payload -Specifies the message for the event. When the event is written to an event log, the payload is -stored in the **Message** property of the event object. +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. -When the specified payload does not match the payload in the event definition, Windows PowerShell -generates a warning, but the command still succeeds. +If the values in the payload do not match the types in the template, the event is logged but the +payload contains an error. ```yaml Type: System.Object[] Accept wildcard characters: False ### -Version -Specifies the version number of the event. Type the event number. Windows PowerShell converts the -number to the required Byte type. --This parameter lets you specify an event when different versions of the same event are defined. +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. ```yaml Type: System.Byte Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,--WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).+-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS This cmdlet does to generate any output. ## NOTES -- After the provider writes the event to an eventlog, you can use the `Get-WinEvent` cmdlet to get the- event from the event log. +After the provider writes the event to an eventlog, you can use the `Get-WinEvent` cmdlet to get the +event from the event log. ## RELATED LINKS |
| Microsoft.PowerShell.Diagnostics | New Winevent (7.0) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Diagnostics/New-WinEvent.md | external help file: Microsoft.PowerShell.Commands.Diagnostics.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Diagnostics Previously updated : 09/28/2021 Last updated : 05/04/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.diagnostics/new-winevent?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 Title: New-WinEvent You can use this cmdlet to add events to ETW channels from PowerShell. ## EXAMPLES -### Example 1 +### Example 1 - Create a new event ```powershell New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Workflow", "Running") New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Wo 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. ++```powershell +(Get-WinEvent -ListProvider Microsoft-Windows-GroupPolicy).Events | Where-Object Id -eq 8007 +``` ++```Output +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 withe 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. ++```powershell +$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 +``` ++```Output + 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. + ## PARAMETERS ### -Id -Specifies an event id that was registered through an instrumentation manifest. +Specifies an event Id that is registered in the event provider. ```yaml Type: System.Int32 Accept wildcard characters: False ### -Payload -Specifies the message for the event. When the event is written to an event log, the payload is -stored in the **Message** property of the event object. +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. -When the specified payload does not match the payload in the event definition, PowerShell generates -a warning, but the command still succeeds. +If the values in the payload do not match the types in the template, the event is logged but the +payload contains an error. ```yaml Type: System.Object[] Accept wildcard characters: False ### -Version -Specifies the version number of the event. Type the event number. PowerShell converts the -number to the required Byte type. --This parameter lets you specify an event when different versions of the same event are defined. +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. ```yaml Type: System.Byte Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,--WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).+-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS This cmdlet does to generate any output. ## NOTES -- After the provider writes the event to an eventlog, you can use the `Get-WinEvent` cmdlet to get the- event from the event log. +After the provider writes the event to an eventlog, you can use the `Get-WinEvent` cmdlet to get the +event from the event log. ## RELATED LINKS |
| Microsoft.PowerShell.Diagnostics | New Winevent (7.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Diagnostics/New-WinEvent.md | external help file: Microsoft.PowerShell.Commands.Diagnostics.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Diagnostics Previously updated : 09/28/2021 Last updated : 05/04/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.diagnostics/new-winevent?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: New-WinEvent You can use this cmdlet to add events to ETW channels from PowerShell. ## EXAMPLES -### Example 1 +### Example 1 - Create a new event ```powershell New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Workflow", "Running") New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Wo 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. ++```powershell +(Get-WinEvent -ListProvider Microsoft-Windows-GroupPolicy).Events | Where-Object Id -eq 8007 +``` ++```Output +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 withe 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. ++```powershell +$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 +``` ++```Output + 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. + ## PARAMETERS ### -Id -Specifies an event id that was registered through an instrumentation manifest. +Specifies an event Id that is registered in the event provider. ```yaml Type: System.Int32 Accept wildcard characters: False ### -Payload -Specifies the message for the event. When the event is written to an event log, the payload is -stored in the **Message** property of the event object. +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. -When the specified payload does not match the payload in the event definition, PowerShell generates -a warning, but the command still succeeds. +If the values in the payload do not match the types in the template, the event is logged but the +payload contains an error. ```yaml Type: System.Object[] Accept wildcard characters: False ### -Version -Specifies the version number of the event. Type the event number. PowerShell converts the -number to the required Byte type. --This parameter lets you specify an event when different versions of the same event are defined. +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. ```yaml Type: System.Byte Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,--WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).+-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS This cmdlet does to generate any output. ## NOTES -- After the provider writes the event to an eventlog, you can use the `Get-WinEvent` cmdlet to get the- event from the event log. +After the provider writes the event to an eventlog, you can use the `Get-WinEvent` cmdlet to get the +event from the event log. ## RELATED LINKS |
| Microsoft.PowerShell.Diagnostics | New Winevent (7.2) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Diagnostics/New-WinEvent.md | external help file: Microsoft.PowerShell.Commands.Diagnostics.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Diagnostics Previously updated : 09/28/2021 Last updated : 05/04/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.diagnostics/new-winevent?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 Title: New-WinEvent You can use this cmdlet to add events to ETW channels from PowerShell. ## EXAMPLES -### Example 1 +### Example 1 - Create a new event ```powershell New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Workflow", "Running") New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Wo 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. ++```powershell +(Get-WinEvent -ListProvider Microsoft-Windows-GroupPolicy).Events | Where-Object Id -eq 8007 +``` ++```Output +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 withe 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. ++```powershell +$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 +``` ++```Output + 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. + ## PARAMETERS ### -Id -Specifies an event id that was registered through an instrumentation manifest. +Specifies an event Id that is registered in the event provider. ```yaml Type: System.Int32 Accept wildcard characters: False ### -Payload -Specifies the message for the event. When the event is written to an event log, the payload is -stored in the **Message** property of the event object. +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. -When the specified payload does not match the payload in the event definition, PowerShell generates -a warning, but the command still succeeds. +If the values in the payload do not match the types in the template, the event is logged but the +payload contains an error. ```yaml Type: System.Object[] Accept wildcard characters: False ### -Version -Specifies the version number of the event. Type the event number. PowerShell converts the -number to the required Byte type. --This parameter lets you specify an event when different versions of the same event are defined. +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. ```yaml Type: System.Byte Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,--WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).+-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS This cmdlet does to generate any output. ## NOTES -- After the provider writes the event to an eventlog, you can use the `Get-WinEvent` cmdlet to get the- event from the event log. +After the provider writes the event to an eventlog, you can use the `Get-WinEvent` cmdlet to get the +event from the event log. ## RELATED LINKS |
| Microsoft.PowerShell.Diagnostics | New Winevent (7.3) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.3/Microsoft.PowerShell.Diagnostics/New-WinEvent.md | external help file: Microsoft.PowerShell.Commands.Diagnostics.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Diagnostics Previously updated : 09/28/2021 Last updated : 05/04/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.diagnostics/new-winevent?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 Title: New-WinEvent You can use this cmdlet to add events to ETW channels from PowerShell. ## EXAMPLES -### Example 1 +### Example 1 - Create a new event ```powershell New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Workflow", "Running") New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Wo 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. ++```powershell +(Get-WinEvent -ListProvider Microsoft-Windows-GroupPolicy).Events | Where-Object Id -eq 8007 +``` ++```Output +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 withe 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. ++```powershell +$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 +``` ++```Output + 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. + ## PARAMETERS ### -Id -Specifies an event id that was registered through an instrumentation manifest. +Specifies an event Id that is registered in the event provider. ```yaml Type: System.Int32 Accept wildcard characters: False ### -Payload -Specifies the message for the event. When the event is written to an event log, the payload is -stored in the **Message** property of the event object. +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. -When the specified payload does not match the payload in the event definition, PowerShell generates -a warning, but the command still succeeds. +If the values in the payload do not match the types in the template, the event is logged but the +payload contains an error. ```yaml Type: System.Object[] Accept wildcard characters: False ### -Version -Specifies the version number of the event. Type the event number. PowerShell converts the -number to the required Byte type. --This parameter lets you specify an event when different versions of the same event are defined. +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. ```yaml Type: System.Byte Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,--WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).+-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS This cmdlet does to generate any output. ## NOTES -- After the provider writes the event to an eventlog, you can use the `Get-WinEvent` cmdlet to get the- event from the event log. +After the provider writes the event to an eventlog, you can use the `Get-WinEvent` cmdlet to get the +event from the event log. ## RELATED LINKS |