Merge pull request #11205 from MicrosoftDocs/main

6/20/2024 PM Publish

reference/5.1/Microsoft.PowerShell.Utility/Get-EventSubscriber.md

@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Utility
-ms.date: 12/12/2022
+ms.date: 06/20/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/get-eventsubscriber?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Get-EventSubscriber
@@ -174,6 +174,32 @@ being generated when the Elapsed event occurs.
 For more information about modules, see
 [about_Modules](../Microsoft.PowerShell.Core/About/about_Modules.md).
 
+### Example 3: Get hidden event subscribers
+
+This example registers an event subscriber for the **PowerShell.Exiting** event. The subscription is
+registered using the **SupportEvent** parameter, which hides the event subscriber from the default
+output of the `Get-EventSubscriber` cmdlet. You must use the **Force** parameter to get all event
+subscribers, including hidden subscribers.
+
+```powershell
+Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
+    Get-History | Export-Clixml d:\temp\history.clixml
+}
+Get-EventSubscriber  # No output - must use -Force
+Get-EventSubscriber -Force
+```
+
+```Output
+SubscriptionId   : 1
+SourceObject     :
+EventName        :
+SourceIdentifier : PowerShell.Exiting
+Action           : System.Management.Automation.PSEventJob
+HandlerDelegate  :
+SupportEvent     : True
+ForwardEvent     : False
+```
+
 ## PARAMETERS
 
 ### -Force

reference/5.1/Microsoft.PowerShell.Utility/Select-Object.md

@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Utility
-ms.date: 03/16/2023
+ms.date: 06/19/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/select-object?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Select-Object
@@ -348,6 +348,81 @@ Name Weight
 a         7
 ```
 
+### Example 13 - ExpandProperty alters the original object
+
+This example demonstrates the side-effect of using the **ExpandProperty** parameter. When you use
+**ExpandProperty**, `Select-Object` adds the selected properties to the original object as
+**NoteProperty** members.
+
+```powershell
+PS> $object = [PSCustomObject]@{
+    name = 'USA'
+    children = [PSCustomObject]@{
+        name = 'Southwest'
+    }
+}
+PS> $object
+
+name children
+---- --------
+USA  @{name=Southwest}
+
+# Use the ExpandProperty parameter to expand the children property
+PS> $object | Select-Object @{n="country"; e={$_.name}} -ExpandProperty children
+
+name      country
+----      -------
+Southwest USA
+
+# The original object has been altered
+PS> $object
+
+name children
+---- --------
+USA  @{name=Southwest; country=USA}
+```
+
+As you can see, the **country** property was added to the **children** object after using the
+**ExpandProperty** parameter.
+
+### Example 14 - Create a new object with expanded properties without altering the input object
+
+You can avoid the side-effect of using the **ExpandProperty** parameter by creating a new object and
+copying the properties from the input object.
+
+```powershell
+PS> $object = [PSCustomObject]@{
+    name = 'USA'
+    children = [PSCustomObject]@{
+        name = 'Southwest'
+    }
+}
+PS> $object
+
+name children
+---- --------
+USA  @{name=Southwest}
+
+# Create a new object with selected properties
+PS> $newobject = [PSCustomObject]@{
+    country = $object.name
+    children = $object.children
+}
+
+PS> $newobject
+
+country children
+------- --------
+USA     @{name=Southwest}
+
+# $object remains unchanged
+PS> $object
+
+name children
+---- --------
+USA  @{name=Southwest}
+```
+
 ## PARAMETERS
 
 ### -ExcludeProperty
@@ -379,6 +454,10 @@ error.
 
 In either case, the output objects' **Type** matches the expanded property's **Type**.
 
+> [!NOTE]
+> There is a side-effect when using **ExpandProperty**. The `Select-Object` adds the selected
+> properties to the original object as **NoteProperty** members.
+
 If the **Property** parameter is specified, `Select-Object` attempts to add each selected property
 as a **NoteProperty** to every outputted object.
 

reference/5.1/Microsoft.PowerShell.Utility/Send-MailMessage.md

@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Utility
-ms.date: 12/04/2023
+ms.date: 06/18/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/send-mailmessage?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Send-MailMessage
@@ -439,7 +439,7 @@ The `Send-MailMessage` cmdlet is obsolete. For more information, see
 [Platform Compatibility note DE0005](https://aka.ms/SendMailMessage). This cmdlet doesn't guarantee
 secure connections to SMTP servers.
 
-_DE0005_ suggests using the third-party library, [MailKit](https://github.com/jstedfast/MimeKit). If
+_DE0005_ suggests using the third-party library, [MailKit](https://github.com/jstedfast/MailKit). If
 you are using Exchange Online, you can use the
 [Send-MgUserMail](/powershell/module/microsoft.graph.users.actions/send-mgusermail) from the
 Microsoft Graph PowerShell SDK.

reference/5.1/Microsoft.PowerShell.Utility/Unregister-Event.md

@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Utility
-ms.date: 12/12/2022
+ms.date: 06/20/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/unregister-event?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Unregister-Event
@@ -43,40 +43,37 @@ created by using the `New-Event` cmdlet, the new event is also deleted from the
 
 ### Example 1: Cancel an event subscription by source identifier
 
-```
-PS C:\> Unregister-Event -SourceIdentifier "ProcessStarted"
-```
-
 This command cancels the event subscription that has a source identifier of ProcessStarted.
 
+```powershell
+Unregister-Event -SourceIdentifier "ProcessStarted"
+```
+
 To find the source identifier of an event, use the `Get-Event` cmdlet. To find the source identifier
-of an event subscription, use the `Get-EventSubscriber` cmdlet.
+of an event subscription, use the `Get-EventSubscriber` cmdlet
 
 ### Example 2: Cancel an event subscription by subscription identifier
 
-```
-PS C:\> Unregister-Event -SubscriptionId 2
-```
-
 This command cancels the event subscription that has a subscription identifier of 2.
 
+```powershell
+Unregister-Event -SubscriptionId 2
+```
+
 To find the subscription identifier of an event subscription, use the `Get-EventSubscriber` cmdlet.
 
 ### Example 3: Cancel all event subscriptions
 
-```
-PS C:\> Get-EventSubscriber -Force | Unregister-Event -Force
-```
-
-This command cancels all event subscriptions in the session.
+This example cancels all event subscriptions in the session.
 
-The command uses the `Get-EventSubscriber` cmdlet to get all event subscriber objects in the
-session, including the subscribers that are hidden by using the **SupportEvent** parameter of the
-event registration cmdlets.
+```powershell
+Get-EventSubscriber -Force | Unregister-Event -Force
+```
 
-It uses a pipeline operator (`|`) to send the subscriber objects to `Unregister-Event`, which
-deletes them from the session. To complete the task, the **Force** parameter is also required on
-`Unregister-Event`.
+Using the **Force** parameter with `Get-EventSubscriber` gets all event subscriber objects in the
+session, including the subscribers that are hidden. The output is piped to `Unregister-Event`, which
+deletes the subscribers from the session. The **Force** parameter is required on `Unregister-Event`
+to remove any hidden subscribers.
 
 ## PARAMETERS
 

reference/7.2/Microsoft.PowerShell.Utility/Get-EventSubscriber.md

@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Utility
-ms.date: 12/12/2022
+ms.date: 06/20/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/get-eventsubscriber?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Get-EventSubscriber
@@ -174,6 +174,32 @@ being generated when the Elapsed event occurs.
 For more information about modules, see
 [about_Modules](../Microsoft.PowerShell.Core/About/about_Modules.md).
 
+### Example 3: Get hidden event subscribers
+
+This example registers an event subscriber for the **PowerShell.Exiting** event. The subscription is
+registered using the **SupportEvent** parameter, which hides the event subscriber from the default
+output of the `Get-EventSubscriber` cmdlet. You must use the **Force** parameter to get all event
+subscribers, including hidden subscribers.
+
+```powershell
+Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
+    Get-History | Export-Clixml d:\temp\history.clixml
+}
+Get-EventSubscriber  # No output - must use -Force
+Get-EventSubscriber -Force
+```
+
+```Output
+SubscriptionId   : 1
+SourceObject     :
+EventName        :
+SourceIdentifier : PowerShell.Exiting
+Action           : System.Management.Automation.PSEventJob
+HandlerDelegate  :
+SupportEvent     : True
+ForwardEvent     : False
+```
+
 ## PARAMETERS
 
 ### -Force

reference/7.2/Microsoft.PowerShell.Utility/Select-Object.md

@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Utility
-ms.date: 11/16/2023
+ms.date: 06/19/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/select-object?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Select-Object
@@ -350,6 +350,81 @@ name weight
 a         7
 ```
 
+### Example 13: ExpandProperty alters the original object
+
+This example demonstrates the side-effect of using the **ExpandProperty** parameter. When you use
+**ExpandProperty**, `Select-Object` adds the selected properties to the original object as
+**NoteProperty** members.
+
+```powershell
+PS> $object = [PSCustomObject]@{
+    name = 'USA'
+    children = [PSCustomObject]@{
+        name = 'Southwest'
+    }
+}
+PS> $object
+
+name children
+---- --------
+USA  @{name=Southwest}
+
+# Use the ExpandProperty parameter to expand the children property
+PS> $object | Select-Object @{n="country"; e={$_.name}} -ExpandProperty children
+
+name      country
+----      -------
+Southwest USA
+
+# The original object has been altered
+PS> $object
+
+name children
+---- --------
+USA  @{name=Southwest; country=USA}
+```
+
+As you can see, the **country** property was added to the **children** object after using the
+**ExpandProperty** parameter.
+
+### Example 14: Create a new object with expanded properties without altering the input object
+
+You can avoid the side-effect of using the **ExpandProperty** parameter by creating a new object and
+copying the properties from the input object.
+
+```powershell
+PS> $object = [PSCustomObject]@{
+    name = 'USA'
+    children = [PSCustomObject]@{
+        name = 'Southwest'
+    }
+}
+PS> $object
+
+name children
+---- --------
+USA  @{name=Southwest}
+
+# Create a new object with selected properties
+PS> $newobject = [PSCustomObject]@{
+    country = $object.name
+    children = $object.children
+}
+
+PS> $newobject
+
+country children
+------- --------
+USA     @{name=Southwest}
+
+# $object remains unchanged
+PS> $object
+
+name children
+---- --------
+USA  @{name=Southwest}
+```
+
 ## PARAMETERS
 
 ### -ExcludeProperty
@@ -383,6 +458,10 @@ error.
 
 In either case, the output objects' **Type** matches the expanded property's **Type**.
 
+> [!NOTE]
+> There is a side-effect when using **ExpandProperty**. The `Select-Object` adds the selected
+> properties to the original object as **NoteProperty** members.
+
 If the **Property** parameter is specified, `Select-Object` attempts to add each selected property
 as a **NoteProperty** to every outputted object.
 

reference/7.2/Microsoft.PowerShell.Utility/Send-MailMessage.md

@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Utility
-ms.date: 12/04/2023
+ms.date: 06/18/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/send-mailmessage?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Send-MailMessage
@@ -465,7 +465,7 @@ The `Send-MailMessage` cmdlet is obsolete. For more information, see
 [Platform Compatibility note DE0005](https://aka.ms/SendMailMessage). This cmdlet doesn't guarantee
 secure connections to SMTP servers.
 
-_DE0005_ suggests using the third-party library, [MailKit](https://github.com/jstedfast/MimeKit). If
+_DE0005_ suggests using the third-party library, [MailKit](https://github.com/jstedfast/MailKit). If
 you are using Exchange Online, you can use the
 [Send-MgUserMail](/powershell/module/microsoft.graph.users.actions/send-mgusermail) from the
 Microsoft Graph PowerShell SDK.