Using Wait-Event in PowerShell

Welcome back to Wahmans PowerShell blog! Today, we’re diving into the Wait-Event cmdlet. According to Microsoft, Wait-Event “Waits until a particular event is raised before continuing to run.” This allows your script to pause execution until it receives a specific event—a powerful way to handle asynchronous or event-driven scripting in PowerShell.

Why Use Wait-Event?

If you’re working with background jobs, WMI events, or anything that emits events, Wait-Event is your friend. Let’s go through some examples from beginner to more advanced scenarios.

Example 1: Beginner – Waiting for a Custom Event

Register-EngineEvent -SourceIdentifier "MyEvent" -Action { Write-Host "MyEvent was triggered!" }

# Simulate a parallel trigger
Start-Job { Start-Sleep -Seconds 2; New-Event -SourceIdentifier 'MyEvent' }

# Wait for the event to occur
Wait-Event -SourceIdentifier 'MyEvent'

Write-Host "Event received."

This example registers a simple engine event and triggers it after 2 seconds using a background job. The main script patiently pauses with Wait-Event until the event fires.

Example 2: Intermediate – Respond to WMI Events

Want to respond when a USB drive is inserted?

Register-WmiEvent -Query "SELECT * FROM Win32_DeviceChangeEvent" -SourceIdentifier "USBEvent"

Write-Host "Please insert a USB drive..."
Wait-Event -SourceIdentifier "USBEvent"
Write-Host "Device change detected!"

This reacts to a hardware change (like plugging in USB) using WMI event queries.

Example 3: Advanced – Waiting for Completion of a Background Job

$job = Start-Job -ScriptBlock {
    Start-Sleep -Seconds 5
    "Job complete"
}

Register-ObjectEvent -InputObject $job -EventName StateChanged -SourceIdentifier JobDone -Action {
    if ($Event.SourceEventArgs.JobStateInfo.State -eq 'Completed') {
        Write-Host "Job has completed."
    }
}

Wait-Event -SourceIdentifier "JobDone"
Write-Host "Main script continues after job."

Here, we start a background job, register an event to be triggered upon its completion, and wait for that event.

Example 4: Expert – Combining Wait-Event with a Timeout

Register-EngineEvent -SourceIdentifier "TimeoutEvent" -Action { Write-Host "Timeout reached." }

# Simulate user or system action in parallel
Start-Job { Start-Sleep -Seconds 10; New-Event -SourceIdentifier 'UserEvent' }

# Wait with timeout
$event = Wait-Event -SourceIdentifier 'UserEvent' -Timeout 5

if ($null -eq $event) {
    New-Event -SourceIdentifier 'TimeoutEvent'
} else {
    Write-Host "User event received in time."
}

This script waits for a user/event condition but ensures it won’t wait forever by including a timeout fallback mechanism.

Conclusion

Wait-Event is a handy tool in PowerShell’s arsenal for building responsive and event-driven scripts. Whether you are listening for internal engine events, WMI signals, or custom triggers—this cmdlet allows graceful control over asynchronous behavior.

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