Fixes #8781 - Add examples and clean up descriptions

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] <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")
@@ -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    : <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
@@ -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
 

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    : <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
@@ -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