Using the New-Event Cmdlet in PowerShell

Welcome back to Wahmans PowerShell Blog! Today, we’re exploring a very interesting and useful cmdlet: New-Event. This cmdlet is part of the event management capabilities in PowerShell and is used to create a new event that can be handled programmatically. This is especially useful for building event-driven scripts and applications. Let’s dive in and look at both the theory and some practical examples from beginner to advanced usage.

What does New-Event do?

According to Microsoft Documentation, New-Event “creates a new event.” It allows you to manually raise or simulate events that can trigger event subscribers, making it ideal for handling custom logic flows within your PowerShell sessions or scripts.

Example 1: Basic Usage – Creating a Simple Event

# Create a simple event
New-Event -SourceIdentifier 'MySimpleEvent'

# Check the event queue
Get-Event

This creates an event with the identifier MySimpleEvent. You can now observe this event in your session with Get-Event.

Example 2: Attaching an Action to a Custom Event

# Create an event subscriber
Register-EngineEvent -SourceIdentifier 'MyCustomEvent' -Action {
    Write-Host "MyCustomEvent has been triggered!"
}

# Trigger the event
New-Event -SourceIdentifier 'MyCustomEvent'

Here, we register an action that will be executed when the MyCustomEvent is raised. This is a great way to tie event-driven logic to your scripts.

Example 3: Passing Event Data

# Register a subscriber and receive event arguments
Register-EngineEvent -SourceIdentifier 'DataEvent' -Action {
    param($sender, $eventArgs)
    Write-Host "Received data:" $eventArgs.SourceEventArgs.MessageData
}

# Fire the event with custom data
New-Event -SourceIdentifier 'DataEvent' -MessageData "Hello from Wahmans Blog!"

In this example, we show how to send custom data with your event using the -MessageData parameter. The message is then accessible within the event action block.

Example 4: Advanced Use – Loop Waiting for Specific Events

# Start a background job that waits for an event
Register-EngineEvent -SourceIdentifier 'MonitorEvent' -Action {
    param($sender, $eventArgs)
    Write-Host "MonitorEvent triggered with value:" $eventArgs.SourceEventArgs.MessageData
}

# Simulating event being fired after some delay
Start-Job {
    Start-Sleep -Seconds 2
    New-Event -SourceIdentifier 'MonitorEvent' -MessageData 'Background trigger!'
}

# Wait for event to arrive
Write-Host "Waiting for event..."
Wait-Event -SourceIdentifier 'MonitorEvent'
Write-Host "Event processed."

This example demonstrates how to wait for a specific event using Wait-Event in tandem with New-Event. This is useful when building scripts that require asynchronous behavior or reaction to external triggers.

Wrap Up

The New-Event cmdlet opens a lot of possibilities for interactive and asynchronous scripting. Whether you’re debugging, simulating external inputs, or architecting more advanced script flows, mastering this cmdlet is key to building robust PowerShell solutions.

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