Understanding the Unregister-Event Cmdlet in PowerShell

Welcome back to Wahmans PowerShell blog! Today, we’re diving into a helpful cmdlet that’s essential when working with events in PowerShell: Unregister-Event.

The Unregister-Event cmdlet helps you clean up event subscriptions. When you register for an event using Register-ObjectEvent, Register-EngineEvent, or Register-WmiEvent, an event subscription is created and stored. To avoid memory leaks or undesired event handling in long-running scripts or sessions, you should always clean up those subscriptions with Unregister-Event when they’re no longer needed.

Syntax

Unregister-Event [-SubscriptionId] <Int32>
Unregister-Event [-SourceIdentifier] <String>

Example 1: Basic removal of an event subscription

This first example registers an event subscription monitoring a timer object and then unregisters it using its source identifier.

$timer = New-Object Timers.Timer
$timer.Interval = 1000
$timer.AutoReset = $true

# Register event
Register-ObjectEvent -InputObject $timer -EventName Elapsed -SourceIdentifier "MyTimerEvent" -Action { Write-Host "Timer ticked" }

# Start the timer
$timer.Start()
Start-Sleep -Seconds 3

# Unregister the event
Unregister-Event -SourceIdentifier "MyTimerEvent"

$timer.Stop()

Example 2: Unregistering using SubscriptionId

Every event registration returns an object that includes a unique SubscriptionId. We can also use this ID to unregister the event.

$event = Register-EngineEvent -SourceIdentifier "PowerShell.Exiting" -Action { Write-Host "Goodbye!" }

# View the SubscriptionId
$event.Id

# Unregister using the SubscriptionId
Unregister-Event -SubscriptionId $event.Id

Example 3: Cleaning up multiple subscriptions

This example shows how to unregister all active events in a script or session. Useful for clean-up at the end of long scripts.

# Register multiple sample events
Register-EngineEvent -SourceIdentifier "Event1" -Action { Write-Output "Event1!" }
Register-EngineEvent -SourceIdentifier "Event2" -Action { Write-Output "Event2!" }

# Get all registered events
Get-EventSubscriber | ForEach-Object { Unregister-Event -SubscriptionId $_.SubscriptionId }

Example 4: Advanced use—file system watcher with event handling

In this more advanced example, we use Register-ObjectEvent to monitor a directory for file changes and properly clean up afterward.

$folder = "C:\Temp"
$watcher = New-Object System.IO.FileSystemWatcher
$watcher.Path = $folder
$watcher.Filter = "*.txt"
$watcher.EnableRaisingEvents = $true

$event = Register-ObjectEvent -InputObject $watcher -EventName "Created" -SourceIdentifier "FileCreated" -Action {
    Write-Host "New file created: $($Event.SourceEventArgs.Name)"
}

Write-Host "Watching folder: $folder"
Start-Sleep -Seconds 10

Unregister-Event -SourceIdentifier "FileCreated"
$watcher.Dispose()

Conclusion

Proper handling of events includes not only registering them but also cleaning them up! Unregister-Event is your go-to cmdlet for that. Whether you’re stopping timers, removing WMI event subscriptions, or cleaning up engine events, don’t forget to unregister!

Happy scripting, and I will see you in the next post!

Wahmans Powershell Blog

Unregister-Event