{"id":5991,"date":"2008-06-10T19:15:00","date_gmt":"2008-06-10T19:15:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/powershell\/2008\/06\/10\/powershell-eventing-quickstart\/"},"modified":"2019-02-18T13:15:50","modified_gmt":"2019-02-18T20:15:50","slug":"powershell-eventing-quickstart","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/powershell\/powershell-eventing-quickstart\/","title":{"rendered":"PowerShell Eventing QuickStart"},"content":{"rendered":"

 <\/p>\n

The second CTP of PowerShell V2 (CTP2) introduces another new feature called PowerShell Eventing. PowerShell Eventing lets you respond to the asynchronous notifications that many objects support. We didn\u2019t get a chance to fully document these cmdlets in the CTP2, though, so here\u2019s a quick start and primer to help you explore the feature.<\/p>\n

Discovering Events<\/h2>\n

Before playing with PowerShell eventing, you\u2019ll probably want to find an object that supports events. But how do you know what an object supports? You will most commonly discover this through API documentation (“To receive notifications, subscribe to the <Foo> event,”) but Get-Member has also been enhanced to show the events supported by an object:<\/p>\n

\n

PS >$timer = New-Object Timers.Timer
PS >$timer | Get-Member -Type Event <\/font><\/p>\n

   TypeName: System.Timers.Timer <\/font><\/p>\n

Name     MemberType Definition
—-     ———- ———-
Disposed Event      System.EventHandler Disposed(System.Object, System.EventArgs)
Elapsed  Event      System.Timers.ElapsedEventHandler Elapsed(System.Object, System.Timers.ElapsedEventArgs)<\/font><\/p>\n<\/blockquote>\n

Subscribing to Events<\/h2>\n

Once you’ve determined the event name you are interested in, the Register-ObjectEvent cmdlet registers your event subscription in the system. The SourceIdentifier parameter helps identify events generated by this object, and lets you manage its event subscription:<\/p>\n

\n

PS >Register-ObjectEvent $timer Elapsed -SourceIdentifier Timer.Elapsed<\/font><\/p>\n<\/blockquote>\n

In addition to the Register-ObjectEvent cmdlet, additional cmdlets let you register for WMI events and PowerShell engine events. <\/font><\/p>\n

The Get-PsEventSubscriber cmdlet shows us all event subscribers in the session:<\/p>\n

\n

PS >Get-PSEventSubscriber <\/font><\/p>\n

SubscriptionId   : 4
SourceObject     : System.Timers.Timer
EventName        : Elapsed
SourceIdentifier : Timer.Elapsed
Action           :
HandlerDelegate  :
SupportEvent     : False
ForwardEvent     : False<\/font><\/p>\n<\/blockquote>\n

Polling for Events<\/h2>\n

The simplest way to manage events is to simply subscribe to them, and occasionally check the event queue. When you are done with the event, remove it from the queue. The Get-PsEvent and Remove-PsEvent cmdlets let you do that:<\/p>\n

\n

PS >Get-PsEvent
PS >$timer.Interval = 2000
PS >$timer.Autoreset = $false
PS >$timer.Enabled = $true
PS >Get-PsEvent
PS >Get-PsEvent <\/font><\/p>\n

EventIdentifier  : 11
Sender           : System.Timers.Timer
SourceEventArgs  : System.Timers.ElapsedEventArgs
SourceArgs       : {System.Timers.Timer, System.Timers.ElapsedEventArgs}
SourceIdentifier : Timer.Elapsed
TimeGenerated    : 6\/10\/2008 3:33:39 PM
MessageData      :
ForwardEvent     : False <\/font><\/p>\n

PS >Remove-PsEvent *
PS >Get-PsEvent<\/font><\/p>\n<\/blockquote>\n

Most objects pack their interesting data in a class derived from “EventArgs.” To make working with these as easy as possible, the SourceEventArgs property is a shortcut to the first parameter in the event handler that derives from EventArgs. The SourceArgs parameter gives you full access to the event handler parameters, letting you deal with events that don’t follow the basic “Object sender, EventArgs e” pattern.<\/p>\n

Waiting for Events<\/h2>\n

Polling for an event is tedious, since you usually want to wait until the event is raised before you do something. The Wait-PsEvent cmdlet lets you do that. Unlike synchronous objects on methods (i.e.: Process.WaitForExit(),) this cmdlet lets you press Control-C to halt the wait:<\/p>\n

\n

PS >$timer.Interval = 2000
PS >$timer.Autoreset = $false
PS >$timer.Enabled = $true; Wait-PsEvent Timer.Elapsed <\/font><\/p>\n

<2 seconds pass><\/em><\/font><\/p>\n

EventIdentifier  : 12
Sender           : System.Timers.Timer
SourceEventArgs  : System.Timers.ElapsedEventArgs
SourceArgs       : {System.Timers.Timer, System.Timers.ElapsedEventArgs}
SourceIdentifier : Timer.Elapsed
TimeGenerated    : 6\/10\/2008 3:24:18 PM
MessageData      :
ForwardEvent     : False<\/font><\/p>\n<\/blockquote>\n

Once you’ve finished working with the event, remove it from the queue.<\/p>\n

Asynchronous Processing of Events<\/h2>\n

While waiting for an event is helpful, you usually don’t want to block your script or shell session just waiting for the event to fire. To support this, the Register-*Event cmdlets support an -Action scriptblock. PowerShell will invoke that scriptblock in the background when your event arrives. These actions invoke in their own module \u2014 they can get and set $GLOBAL variables, but regular variable modifications happen in their own isolated environment.<\/p>\n

\n

function DoEvery
{
   param([int] $seconds,[ScriptBlock] $action ) <\/font><\/p>\n

   $timer = New-Object System.Timers.Timer
   $timer.Interval = $seconds * 1000
   $timer.Enabled = $true
   Register-ObjectEvent $timer “Elapsed” -SourceIdentifier “Timer.Elapsed” -Action $action
} <\/font><\/p>\n

DoEvery 2 { [Console]::Beep(300, 100) } <\/font><\/p>\n

## Eventually
Unregister-PsEvent “Timer.Elapsed” <\/font><\/p>\n<\/blockquote>\n

(Warning: The $args parameter in event actions has changed since CTP2 based on usability feedback. Such is the risk and reward of pre-release software!)<\/strong><\/p>\n

However, doing two things at once means multithreading. And multithreading? Thar be dragons! To prevent you from having to deal with multi-threading issues, PowerShell tightly controls the execution of these script blocks. When it’s time to process an action, it suspends the current script or pipeline, executes the action, and then resumes where it left off. It only processes one action at a time.<\/p>\n

One great use of asynchronous actions is engine events, and the Register-PsEvent cmdlet:<\/p>\n

\n

## Now in your profile
$maximumHistoryCount = 1kb <\/font><\/p>\n

## Register for the engine shutdown event
Register-PsEvent ([System.Management.Automation.PsEngineEvent]::Exiting) -Action {
   Get-History -Count $maximumHistoryCount | ? { $_.CommandLine -ne “exit” } |
       Export-CliXml (Join-Path (Split-Path $profile) “commandHistory.clixml”)
} <\/font><\/p>\n

## Load our previous history
$historyFile = (Join-Path (Split-Path $profile) “commandHistory.clixml”)
if(Test-Path $historyFile)
{
   Import-CliXml $historyFile | Add-History
}<\/font><\/p>\n<\/blockquote>\n

Support Events<\/h2>\n

Ultimately, almost any event can be written in terms of Register-ObjectEvent. PowerShell is all about task-based abstractions, though, so event forwarding lets you (and ISVs) map complex event domains (such as WMI queries) to much simpler ones. The -SupportEvent parameter to the event registration cmdlets help there, as its event registrations don’t show in the default views: <\/p>\n

\n

## Enable process creation events
function Enable-ProcessCreationEvent
{
   $query = New-Object System.Management.WqlEventQuery “__InstanceCreationEvent”, `
       (New-Object TimeSpan 0,0,1), `
       “TargetInstance isa ‘Win32_Process'”
   $processWatcher = New-Object System.Management.ManagementEventWatcher $query <\/font><\/p>\n

   $identifier = “WMI.ProcessCreated”
   Register-ObjectEvent $processWatcher “EventArrived” -SupportEvent $identifier -Action {
       [void] (New-PsEvent “PowerShell.ProcessCreated” -Sender $args[0] -EventArguments $args[1].SourceEventArgs.NewEvent.TargetInstance)
   }
} <\/font><\/p>\n

## Disable process creation events
function Disable-ProcessCreationEvent
{
   Unregister-PsEvent -Force -SourceIdentifier “WMI.ProcessCreated”
} <\/font><\/p>\n

## Register for the custom “PowerShell.ProcessCreated” engine event
Register-PsEvent “PowerShell.ProcessCreated” -Action {
   $processName = $args[1].SourceArgs[0].Name.Split(“.”)[0]
   (New-Object -COM Sapi.SPVoice).Speak(“Welcome to $processName”)
} <\/font><\/p>\n

## Eventually
Unregister-PsEvent PowerShell.ProcessCreated <\/font><\/p>\n<\/blockquote>\n

(Warning: The $args parameter in event actions has changed since CTP2 based on usability feedback. Such is the risk and reward of pre-release software!)<\/strong><\/p>\n

Event Forwarding<\/h2>\n

When registering for an event on a remote machine, you can specify the “-Forward” parameter if you want to deliver the event to the client session connected to the remote machine. Here’s an example:<\/p>\n

\n\n\n\n
\n
001
002
003
004
005
006
007
008
009
010
011
012
013
014
015
016
017
018
019
020
021
022
023
024
025
026
027
028
029
030
031
032
033
034
035
036
037
038
039
040
041
042<\/div>\n<\/td>\n
\n
$remoteComputer<\/span> <\/span>=<\/span> <\/span>“REMOTE_COMPUTER”<\/span>
$session<\/span> <\/span>=<\/span> <\/span>New-PsSession<\/span> <\/span>$remoteComputer<\/span><\/p>\n

Unregister-Event<\/span> <\/span>WMI.Service.Stopped<\/span> <\/span>-ErrorAction<\/span> <\/span>SilentlyContinue<\/span><\/p>\n

## Register for an event that fires when a service stops on the remote computer<\/span>
## Set this to forward to the client machine.<\/span>
Invoke-Command<\/span> <\/span>$session<\/span> <\/span>{<\/span><\/p>\n

    <\/span>## The WMI query to detect a stopping service<\/span>
    <\/span>$query<\/span> <\/span>=<\/span> <\/span>@”
        SELECT *
        FROM __InstanceModificationEvent
        WITHIN 2
        WHERE TargetInstance ISA ‘Win32_Service’
        AND TargetInstance.Name = ‘WSearch’
        AND TargetInstance.State = ‘Stopped’
“@<\/span><\/p>\n

    <\/span>## Register for the WMI event<\/span>
    <\/span>Register-WmiEvent<\/span> <\/span>-Query<\/span> <\/span>$query<\/span> <\/span>“WMI.Service.Stopped”<\/span> <\/span>-Forward<\/span>
}<\/span><\/p>\n

## Register for notifications from remote computers with the event name<\/span>
## WMI.Service.Stopped. We’ll LOCALLY show the event log of the computer<\/span>
## that generated it.<\/span>
$null<\/span> <\/span>=<\/span> <\/span>Register-EngineEvent<\/span> <\/span>WMI.Service.Stopped<\/span> <\/span>`
    <\/span>-Action<\/span> <\/span>{<\/span> <\/span>Show-EventLog<\/span> <\/span>$event<\/span>.<\/span>ComputerName<\/span> <\/span>}<\/span><\/p>\n

## Stop the service<\/span>
Invoke-Command<\/span> <\/span>$session<\/span> <\/span>{<\/span> <\/span>Stop-Service<\/span> <\/span>WSearch<\/span> <\/span>}<\/span><\/p>\n

## Play in the shell<\/span>
1<\/span>..<\/span>10<\/span> <\/span>|<\/span> <\/span>%<\/span> <\/span>{<\/span> <\/span>Write-Host<\/span> <\/span>“Sleeping…”<\/span>;<\/span> <\/span>Start-Sleep<\/span> <\/span>1<\/span> <\/span>}<\/span><\/p>\n

Read-Host<\/span> <\/span>“Is it fixed?”<\/span><\/p>\n

## Fix the service by restarting it.<\/span>
Invoke-Command<\/span> <\/span>$session<\/span> <\/span>{<\/span> <\/span>Start-Service<\/span> <\/span>WSearch<\/span> <\/span>}<\/span><\/p>\n

Remove-PsSession<\/span> <\/span>$session<\/span> <\/div>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n

Hope this helps getting started.<\/p>\n

—
Lee Holmes [MSFT]
Windows PowerShell Development
Microsoft Corporation<\/p>\n","protected":false},"excerpt":{"rendered":"

  The second CTP of PowerShell V2 (CTP2) introduces another new feature called PowerShell Eventing. PowerShell Eventing lets you respond to the asynchronous notifications that many objects support. We didn\u2019t get a chance to fully document these cmdlets in the CTP2, though, so here\u2019s a quick start and primer to help you explore the feature. […]<\/p>\n","protected":false},"author":600,"featured_media":13641,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[161],"class_list":["post-5991","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-powershell","tag-events"],"acf":[],"blog_post_summary":"

  The second CTP of PowerShell V2 (CTP2) introduces another new feature called PowerShell Eventing. PowerShell Eventing lets you respond to the asynchronous notifications that many objects support. We didn\u2019t get a chance to fully document these cmdlets in the CTP2, though, so here\u2019s a quick start and primer to help you explore the feature. […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/5991","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/users\/600"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/comments?post=5991"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/5991\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media\/13641"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media?parent=5991"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/categories?post=5991"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/tags?post=5991"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}