diff --git a/reference/5.1/Microsoft.PowerShell.Diagnostics/New-WinEvent.md b/reference/5.1/Microsoft.PowerShell.Diagnostics/New-WinEvent.md index 45929222d11d..7ce59ffeb3ba 100644 --- a/reference/5.1/Microsoft.PowerShell.Diagnostics/New-WinEvent.md +++ b/reference/5.1/Microsoft.PowerShell.Diagnostics/New-WinEvent.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Diagnostics.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Diagnostics -ms.date: 09/28/2021 +ms.date: 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 @@ -22,11 +22,11 @@ New-WinEvent [-ProviderName] [-Id] [-Version ] [[-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") @@ -35,11 +35,85 @@ 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 : + +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 : + +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 @@ -55,11 +129,12 @@ 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[] @@ -93,10 +168,8 @@ 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 @@ -114,7 +187,8 @@ 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 @@ -130,8 +204,8 @@ 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 diff --git a/reference/7.0/Microsoft.PowerShell.Diagnostics/New-WinEvent.md b/reference/7.0/Microsoft.PowerShell.Diagnostics/New-WinEvent.md index 62ceba41992e..459f1277c952 100644 --- a/reference/7.0/Microsoft.PowerShell.Diagnostics/New-WinEvent.md +++ b/reference/7.0/Microsoft.PowerShell.Diagnostics/New-WinEvent.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Diagnostics.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Diagnostics -ms.date: 09/28/2021 +ms.date: 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 @@ -28,7 +28,7 @@ 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") @@ -37,11 +37,85 @@ 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 : + +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 : + +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 @@ -57,11 +131,12 @@ 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[] @@ -95,10 +170,8 @@ 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 @@ -116,7 +189,8 @@ 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 @@ -132,8 +206,8 @@ 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 diff --git a/reference/7.1/Microsoft.PowerShell.Diagnostics/New-WinEvent.md b/reference/7.1/Microsoft.PowerShell.Diagnostics/New-WinEvent.md index 81556d75bff2..e55f4708771b 100644 --- a/reference/7.1/Microsoft.PowerShell.Diagnostics/New-WinEvent.md +++ b/reference/7.1/Microsoft.PowerShell.Diagnostics/New-WinEvent.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Diagnostics.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Diagnostics -ms.date: 09/28/2021 +ms.date: 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 @@ -28,7 +28,7 @@ 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") @@ -37,11 +37,85 @@ 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 : + +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 : + +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 @@ -57,11 +131,12 @@ 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[] @@ -95,10 +170,8 @@ 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 @@ -116,7 +189,8 @@ 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 @@ -132,8 +206,8 @@ 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 diff --git a/reference/7.2/Microsoft.PowerShell.Diagnostics/New-WinEvent.md b/reference/7.2/Microsoft.PowerShell.Diagnostics/New-WinEvent.md index 4f1e61fdd3b9..4f4a30ca389b 100644 --- a/reference/7.2/Microsoft.PowerShell.Diagnostics/New-WinEvent.md +++ b/reference/7.2/Microsoft.PowerShell.Diagnostics/New-WinEvent.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Diagnostics.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Diagnostics -ms.date: 09/28/2021 +ms.date: 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 @@ -28,7 +28,7 @@ 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") @@ -37,11 +37,85 @@ 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 : + +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 : + +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 @@ -57,11 +131,12 @@ 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[] @@ -95,10 +170,8 @@ 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 @@ -116,7 +189,8 @@ 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 @@ -132,8 +206,8 @@ 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 diff --git a/reference/7.3/Microsoft.PowerShell.Diagnostics/New-WinEvent.md b/reference/7.3/Microsoft.PowerShell.Diagnostics/New-WinEvent.md index 638caa7231ae..29470f5be040 100644 --- a/reference/7.3/Microsoft.PowerShell.Diagnostics/New-WinEvent.md +++ b/reference/7.3/Microsoft.PowerShell.Diagnostics/New-WinEvent.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Diagnostics.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Diagnostics -ms.date: 09/28/2021 +ms.date: 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 @@ -28,7 +28,7 @@ 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") @@ -37,11 +37,85 @@ 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 : + +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 : + +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 @@ -57,11 +131,12 @@ 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[] @@ -95,10 +170,8 @@ 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 @@ -116,7 +189,8 @@ 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 @@ -132,8 +206,8 @@ 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