Unregister-Event

Understanding Unregister-Event in PowerShell

Welcome back to Wahmans PowerShell Blog! Today, we’re diving into a cmdlet that helps you clean up and control runtime events in your PowerShell sessions: Unregister-Event.

The official Microsoft description for Unregister-Event says: Cancels an event subscription. This cmdlet is used to remove event subscriptions that were previously registered using Register-ObjectEvent, Register-EngineEvent, or Register-WmiEvent.

Why is this important? Because leaving event subscriptions open, especially in long-running or looping scripts, can cause event queue buildup, memory leaks and multi-triggering of handlers. So knowing how to use Unregister-Event is essential!

Example 1: Basic Usage – Manually Register and Unregister an Event

# Create a timer object
$timer = New-Object Timers.Timer
$timer.Interval = 1000
$timer.AutoReset = $true

# Register event
$event = Register-ObjectEvent -InputObject $timer -EventName Elapsed -SourceIdentifier TimerElapsed -Action {
    Write-Host "Timer ticked at $(Get-Date)"
}

# Start the timer
$timer.Start()

Start-Sleep -Seconds 5

# Unregister the event
Unregister-Event -SourceIdentifier TimerElapsed

# Stop the timer after unregistering
$timer.Stop()

In this simple example, we set a timer, hook an event to write output every second, and then after 5 seconds, we unregister the event — stopping any further ticks from being processed.

Example 2: Unregister by Event Subscription ID

# Register an event and store the subscription object
$sub = Register-EngineEvent -SourceIdentifier "MyEngineEvent" -Action { Write-Output "Received MyEngineEvent" }

# Trigger the event
New-Event -SourceIdentifier "MyEngineEvent"

# Unregister by ID
Unregister-Event -SubscriptionId $sub.Id

Here we use Register-EngineEvent, which adds to the PowerShell event queue using a custom identifier. We then remove it using its unique SubscriptionId.

Example 3: Automatically Unregistering in a Script Block

# Register event with a temporary action
$event = Register-ObjectEvent -InputObject (New-Object Timers.Timer -Property @{Interval = 2000; AutoReset = $false }) `
    -EventName Elapsed -SourceIdentifier TempTimer `
    -Action {
        Write-Host "One-time event fired."
        # Auto-unregister inside action
        Unregister-Event -SourceIdentifier TempTimer
    }

# Start the timer
$event.SourceObject.Start()

Start-Sleep -Seconds 5

This example shows how you can unregister the event from within its own action – useful for single-instance events that must clean themselves up for efficiency.

Example 4: Unregistering All Events in a Script

# Register multiple events
Register-EngineEvent PowerShell.OnIdle -SourceIdentifier IdleEvent -Action { Write-Host "Idle event triggered" }
Register-EngineEvent PowerShell.Exiting -SourceIdentifier ExitEvent -Action { Write-Host "PowerShell is exiting" }

# Check current events
Get-EventSubscriber

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

In complex scripts or long-running sessions with multiple events, you can list all subscriptions using Get-EventSubscriber and programmatically unregister them. This is great for scripts that provide their own cleanup routine.

Summary

The Unregister-Event cmdlet is simple but powerful. By properly unregistering event subscriptions, you can ensure your PowerShell scripts remain efficient, stable, and clean. Whether you’re automating time-based tasks or handling system events, mastering event subscription management is essential!

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