Add example for OnRemove (#10267)

Author: sdwheeler

reference/5.1/Microsoft.PowerShell.Core/Remove-Module.md

@@ -2,7 +2,7 @@
 external help file: System.Management.Automation.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Core
-ms.date: 12/12/2022
+ms.date: 07/10/2023
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/remove-module?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Remove-Module
@@ -23,7 +23,8 @@ Remove-Module [-Name] <String[]> [-Force] [-WhatIf] [-Confirm] [<CommonParameter
 ### FullyQualifiedName
 
 ```
-Remove-Module [-FullyQualifiedName] <ModuleSpecification[]> [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]
+Remove-Module [-FullyQualifiedName] <ModuleSpecification[]> [-Force] [-WhatIf] [-Confirm]
+ [<CommonParameters>]
 ```
 
 ### ModuleInfo
@@ -38,10 +39,10 @@ The `Remove-Module` cmdlet removes the members of a module, such as cmdlets and
 current session.
 
 If the module includes an assembly (`.dll`), all members that are implemented by the assembly are
-removed, but the assembly is not unloaded.
+removed, but the assembly isn't unloaded.
 
-This cmdlet does not uninstall the module or delete it from the computer. It affects only the
-current PowerShell session.
+This cmdlet doesn't uninstall the module or delete it from the computer. It affects only the current
+PowerShell session.
 
 ## EXAMPLES
 
@@ -92,9 +93,10 @@ The command uses a pipeline operator (`|`) to send the module names to `Remove-M
 
 The **Verbose** messages show the items that are removed. The messages differ because the
 BitsTransfer module includes an assembly that implements its cmdlets and a nested module with its
-own assembly. The PSDiagnostics module includes a module script file (`.psm1`) that exports functions.
+own assembly. The PSDiagnostics module includes a module script file (`.psm1`) that exports
+functions.
 
-### Example 4: Remove a module by using ModuleInfo
+### Example 4: Remove a module using ModuleInfo
 
 ```powershell
 $a = Get-Module BitsTransfer
@@ -103,6 +105,32 @@ Remove-Module -ModuleInfo $a
 
 This command uses the **ModuleInfo** parameter to remove the BitsTransfer module.
 
+### Example 5: Using the OnRemove event
+
+When removing a module, there is an event trigger by the module that allows a module to react to
+being removed and perform some cleanup task, such as freeing resources.
+
+```powershell
+$OnRemoveScript = {
+    # perform cleanup
+    $cachedSessions | Remove-PSSession
+}
+$ExecutionContext.SessionState.Module.OnRemove += $OnRemoveScript
+
+$registerEngineEventSplat = @{
+    SourceIdentifier = ([System.Management.Automation.PsEngineEvent]::Exiting)
+    Action = $OnRemoveScript
+}
+Register-EngineEvent @registerEngineEventSplat
+```
+
+The `$OnRemoveScript` variable contains the script block that cleans up the resources. You register
+the script block by assigning it to `$ExecutionContext.SessionState.Module.OnRemove`. You can also
+use `Register-EngineEvent` to have the script block execute when the PowerShell session ends.
+
+For script-based modules, you would add this code to the `.PSM1` file or put it in a startup script
+that is listed in the **ScriptsToProcess** property of the module manifest.
+
 ## PARAMETERS
 
 ### -Force
@@ -158,9 +186,9 @@ Accept wildcard characters: False
 
 ### -ModuleInfo
 
-Specifies the module objects to remove. Enter a variable that contains a module object
-(**PSModuleInfo**) or a command that gets a module object, such as a `Get-Module` command. You can
-also pipe module objects to `Remove-Module`.
+Specifies the module objects to remove. Enter a variable that contains a **PSModuleInfo** object or
+a command that gets a module object, such as a `Get-Module` command. You can also pipe module
+objects to `Remove-Module`.
 
 ```yaml
 Type: System.Management.Automation.PSModuleInfo[]
@@ -209,7 +237,7 @@ Accept wildcard characters: False
 
 ### -WhatIf
 
-Shows what would happen if the cmdlet runs. The cmdlet is not run.
+Shows what would happen if the cmdlet runs. The cmdlet isn't run.
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter
@@ -227,7 +255,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
 
@@ -251,6 +280,9 @@ Windows PowerShell includes the following aliases for `Remove-Module`:
 
 - `rmo`
 
+When you remove a module, there is an event is triggered that can be used to run some cleanup code.
+For more details, see [Example 5](#example-5-using-the-onremove-event).
+
 ## RELATED LINKS
 
 [Get-Module](Get-Module.md)

reference/7.2/Microsoft.PowerShell.Core/Remove-Module.md

@@ -2,7 +2,7 @@
 external help file: System.Management.Automation.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Core
-ms.date: 12/12/2022
+ms.date: 07/10/2023
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/remove-module?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Remove-Module
@@ -23,7 +23,8 @@ Remove-Module [-Name] <String[]> [-Force] [-WhatIf] [-Confirm] [<CommonParameter
 ### FullyQualifiedName
 
 ```
-Remove-Module [-FullyQualifiedName] <ModuleSpecification[]> [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]
+Remove-Module [-FullyQualifiedName] <ModuleSpecification[]> [-Force] [-WhatIf] [-Confirm]
+ [<CommonParameters>]
 ```
 
 ### ModuleInfo
@@ -38,10 +39,10 @@ The `Remove-Module` cmdlet removes the members of a module, such as cmdlets and
 current session.
 
 If the module includes an assembly (`.dll`), all members that are implemented by the assembly are
-removed, but the assembly is not unloaded.
+removed, but the assembly isn't unloaded.
 
-This cmdlet does not uninstall the module or delete it from the computer. It affects only the
-current PowerShell session.
+This cmdlet doesn't uninstall the module or delete it from the computer. It affects only the current
+PowerShell session.
 
 ## EXAMPLES
 
@@ -92,9 +93,10 @@ The command uses a pipeline operator (`|`) to send the module names to `Remove-M
 
 The **Verbose** messages show the items that are removed. The messages differ because the
 BitsTransfer module includes an assembly that implements its cmdlets and a nested module with its
-own assembly. The PSDiagnostics module includes a module script file (`.psm1`) that exports functions.
+own assembly. The PSDiagnostics module includes a module script file (`.psm1`) that exports
+functions.
 
-### Example 4: Remove a module by using ModuleInfo
+### Example 4: Remove a module using ModuleInfo
 
 ```powershell
 $a = Get-Module BitsTransfer
@@ -103,6 +105,32 @@ Remove-Module -ModuleInfo $a
 
 This command uses the **ModuleInfo** parameter to remove the BitsTransfer module.
 
+### Example 5: Using the OnRemove event
+
+When removing a module, there is an event trigger by the module that allows a module to react to
+being removed and perform some cleanup task, such as freeing resources.
+
+```powershell
+$OnRemoveScript = {
+    # perform cleanup
+    $cachedSessions | Remove-PSSession
+}
+$ExecutionContext.SessionState.Module.OnRemove += $OnRemoveScript
+
+$registerEngineEventSplat = @{
+    SourceIdentifier = ([System.Management.Automation.PsEngineEvent]::Exiting)
+    Action = $OnRemoveScript
+}
+Register-EngineEvent @registerEngineEventSplat
+```
+
+The `$OnRemoveScript` variable contains the script block that cleans up the resources. You register
+the script block by assigning it to `$ExecutionContext.SessionState.Module.OnRemove`. You can also
+use `Register-EngineEvent` to have the script block execute when the PowerShell session ends.
+
+For script-based modules, you would add this code to the `.PSM1` file or put it in a startup script
+that is listed in the **ScriptsToProcess** property of the module manifest.
+
 ## PARAMETERS
 
 ### -Force
@@ -158,9 +186,9 @@ Accept wildcard characters: False
 
 ### -ModuleInfo
 
-Specifies the module objects to remove. Enter a variable that contains a module object
-(**PSModuleInfo**) or a command that gets a module object, such as a `Get-Module` command. You can
-also pipe module objects to `Remove-Module`.
+Specifies the module objects to remove. Enter a variable that contains a **PSModuleInfo** object or
+a command that gets a module object, such as a `Get-Module` command. You can also pipe module
+objects to `Remove-Module`.
 
 ```yaml
 Type: System.Management.Automation.PSModuleInfo[]
@@ -209,7 +237,7 @@ Accept wildcard characters: False
 
 ### -WhatIf
 
-Shows what would happen if the cmdlet runs. The cmdlet is not run.
+Shows what would happen if the cmdlet runs. The cmdlet isn't run.
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter
@@ -227,7 +255,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
 
@@ -252,22 +281,8 @@ PowerShell includes the following aliases for `Remove-Module`:
 - All platforms:
   - `rmo`
 
-When removing a module, there is an event on the module that will execute.
-This event allows a module to react to being removed and perform some cleanup such as freeing up resources. Example:
-
-$OnRemoveScript = {
-
-  \# perform cleanup
-
-  $cachedSessions | Remove-PSSession
-
-}
-
-$ExecutionContext.SessionState.Module.OnRemove += $OnRemoveScript
-
-For full consistency, it might be also useful to react to the closing of the PowerShell process:
-
-Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Action $OnRemoveScript
+When you remove a module, there is an event is triggered that can be used to run some cleanup code.
+For more details, see [Example 5](#example-5-using-the-onremove-event).
 
 ## RELATED LINKS
 

reference/7.3/Microsoft.PowerShell.Core/Remove-Module.md

@@ -2,7 +2,7 @@
 external help file: System.Management.Automation.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Core
-ms.date: 12/12/2022
+ms.date: 07/10/2023
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/remove-module?view=powershell-7.3&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Remove-Module
@@ -23,7 +23,8 @@ Remove-Module [-Name] <String[]> [-Force] [-WhatIf] [-Confirm] [<CommonParameter
 ### FullyQualifiedName
 
 ```
-Remove-Module [-FullyQualifiedName] <ModuleSpecification[]> [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]
+Remove-Module [-FullyQualifiedName] <ModuleSpecification[]> [-Force] [-WhatIf] [-Confirm]
+ [<CommonParameters>]
 ```
 
 ### ModuleInfo
@@ -38,10 +39,10 @@ The `Remove-Module` cmdlet removes the members of a module, such as cmdlets and
 current session.
 
 If the module includes an assembly (`.dll`), all members that are implemented by the assembly are
-removed, but the assembly is not unloaded.
+removed, but the assembly isn't unloaded.
 
-This cmdlet does not uninstall the module or delete it from the computer. It affects only the
-current PowerShell session.
+This cmdlet doesn't uninstall the module or delete it from the computer. It affects only the current
+PowerShell session.
 
 ## EXAMPLES
 
@@ -92,9 +93,10 @@ The command uses a pipeline operator (`|`) to send the module names to `Remove-M
 
 The **Verbose** messages show the items that are removed. The messages differ because the
 BitsTransfer module includes an assembly that implements its cmdlets and a nested module with its
-own assembly. The PSDiagnostics module includes a module script file (`.psm1`) that exports functions.
+own assembly. The PSDiagnostics module includes a module script file (`.psm1`) that exports
+functions.
 
-### Example 4: Remove a module by using ModuleInfo
+### Example 4: Remove a module using ModuleInfo
 
 ```powershell
 $a = Get-Module BitsTransfer
@@ -103,6 +105,32 @@ Remove-Module -ModuleInfo $a
 
 This command uses the **ModuleInfo** parameter to remove the BitsTransfer module.
 
+### Example 5: Using the OnRemove event
+
+When removing a module, there is an event trigger by the module that allows a module to react to
+being removed and perform some cleanup task, such as freeing resources.
+
+```powershell
+$OnRemoveScript = {
+    # perform cleanup
+    $cachedSessions | Remove-PSSession
+}
+$ExecutionContext.SessionState.Module.OnRemove += $OnRemoveScript
+
+$registerEngineEventSplat = @{
+    SourceIdentifier = ([System.Management.Automation.PsEngineEvent]::Exiting)
+    Action = $OnRemoveScript
+}
+Register-EngineEvent @registerEngineEventSplat
+```
+
+The `$OnRemoveScript` variable contains the script block that cleans up the resources. You register
+the script block by assigning it to `$ExecutionContext.SessionState.Module.OnRemove`. You can also
+use `Register-EngineEvent` to have the script block execute when the PowerShell session ends.
+
+For script-based modules, you would add this code to the `.PSM1` file or put it in a startup script
+that is listed in the **ScriptsToProcess** property of the module manifest.
+
 ## PARAMETERS
 
 ### -Force
@@ -158,9 +186,9 @@ Accept wildcard characters: False
 
 ### -ModuleInfo
 
-Specifies the module objects to remove. Enter a variable that contains a module object
-(**PSModuleInfo**) or a command that gets a module object, such as a `Get-Module` command. You can
-also pipe module objects to `Remove-Module`.
+Specifies the module objects to remove. Enter a variable that contains a **PSModuleInfo** object or
+a command that gets a module object, such as a `Get-Module` command. You can also pipe module
+objects to `Remove-Module`.
 
 ```yaml
 Type: System.Management.Automation.PSModuleInfo[]
@@ -209,7 +237,7 @@ Accept wildcard characters: False
 
 ### -WhatIf
 
-Shows what would happen if the cmdlet runs. The cmdlet is not run.
+Shows what would happen if the cmdlet runs. The cmdlet isn't run.
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter
@@ -227,7 +255,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
 
@@ -252,22 +281,8 @@ PowerShell includes the following aliases for `Remove-Module`:
 - All platforms:
   - `rmo`
 
-When removing a module, there is an event on the module that will execute.
-This event allows a module to react to being removed and perform some cleanup such as freeing up resources. Example:
-
-$OnRemoveScript = {
-
-  \# perform cleanup
-
-  $cachedSessions | Remove-PSSession
-
-}
-
-$ExecutionContext.SessionState.Module.OnRemove += $OnRemoveScript
-
-For full consistency, it might be also useful to react to the closing of the PowerShell process:
-
-Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Action $OnRemoveScript
+When you remove a module, there is an event is triggered that can be used to run some cleanup code.
+For more details, see [Example 5](#example-5-using-the-onremove-event).
 
 ## RELATED LINKS