{"id":13601,"date":"2011-06-17T00:01:00","date_gmt":"2011-06-17T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2011\/06\/17\/manage-event-subscriptions-with-powershell\/"},"modified":"2022-10-18T05:40:35","modified_gmt":"2022-10-18T12:40:35","slug":"manage-event-subscriptions-with-powershell","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/manage-event-subscriptions-with-powershell\/","title":{"rendered":"Manage Event Subscriptions with PowerShell"},"content":{"rendered":"

Summary<\/strong>: Bruce Payette shows how to manage event subscriptions with Windows PowerShell.<\/p>\n

Microsoft Scripting Guy, Ed Wilson, here. I am really excited about the idea I had for this week, and I hope you will be too. I asked Candace Gillhoolley at Manning Press about posting some sample works from some of the Manning Press library of books. She responded enthusiastically and shared five samples that we will post this week. Today is part two of two parts from Bruce Payette and Windows PowerShell in Action<\/em>. See yesterday\u2019s blog post<\/a> for part 1.<\/p>\n

Windows PowerShell in Action, Second Edition<\/a><\/h2>\n

\"Image<\/a><\/p>\n

By Bruce Payette<\/p>\n

The key difference between event-based scripting and traditional procedural scripting is that, instead of an activity being executed as a result of an action in the script, a script (or at least a portion of it) is executed as a result of an action by the system.. In this article based on chapter 20 of Windows PowerShell in Action, Second Edition<\/a>, author Bruce Payette discusses asynchronous event-handling models in PowerShell. To save 35% on your next purchase use Promotional Code payette22035<\/strong> when you check out at www.manning.com<\/a>.<\/p>\n

<\/a><\/p>\n

\"manning\"<\/a><\/strong><\/p>\n

Managing event subscriptions<\/strong><\/h2>\n

In this section, you\u2019ll see how to find your event subscriptions and how to remove them when you\u2019re done with them. Being able to remove them is important because event subscriptions persist in the session until explicitly removed.<\/p>\n

Listing event subscriptions<\/strong><\/p>\n

Of course, before you can remove a subscription, you have to find it. Windows PowerShell provides the Get-EventSubscriber<\/strong> to do this. Let\u2019s use it to look at the subscription you registered in the previous section (see yesterday\u2019s Hey! Scripting Guy blog<\/a>):<\/p>\n

PS (1) > Get-EventSubscriber >\n\nSubscriptionId\u00a0: 1\nSourceObject : System.Timers.Timer \nEventName : Elapsed\nSourceIdentifier : fca4b869-8d5a-4f11-8d45-e84af30845f1\nAction : System.Management.Automation.PSEventJob \nHandlerDelegate : \nSupportEvent: False \nForwardEvent: False \n<\/pre>\n
The Get-EventSubscriber<\/strong> cmdlet returns PSEventSubscriber<\/strong> objects, which have complete information about the registration: the object generating the event, the action to execute, and so on. There are a couple of interesting properties to note in this output. Because you didn\u2019t give the subscription a friendly name using -Source-Identifier<\/strong> when you created it, the Register-ObjectEvent<\/strong> generated one for you. This autogenerated name is the string representation of a GUID, so you know it\u2019s unique (but not very friendly). The other thing to notice is that the action shows up as a PowerShell Job<\/strong> object.<\/p>\n
Removing event subscriptions<\/strong><\/p>\n
Now that you can list the event subscriptions, you can set about removing them. The cmdlet to do this is not Unsubscribe-Event<\/strong> because unsubscribe isn\u2019t on the approved verbs list and it\u2019s not what you want to do anyway. You registered event subscriptions with Register-ObjectEvent<\/strong>, so what you need to do is unregister the subscription, which you\u2019ll do with Unregister-Event. The cmdlet noun in this case is Event, not ObjectEvent<\/strong>, because you can use a common mechanism to unregister any kind of event. It\u2019s only the registration part that varies. The rest of the eventing cmdlets remain the same.<\/p>\n
When you\u2019re unregistering an event subscription, there are two ways of identifying the event to unregister: by the SubscriptionId<\/strong> property or by the Source-Identifier<\/strong>. The subscription ID is simply an integer that\u2019s incremented each time an event subscription is created. Because you didn\u2019t give your event registration a friendly name, you\u2019ll use the SubscriptionId<\/strong> to unregister it:<\/p>\n
> PS (4) > Unregister-Event -SubscriptionId 1 -Verbose >\n\nVERBOSE: Performing operation \"Unsubscribe\" on Target \"Event\nsubscription 'timertest2'\n<\/pre>\n
Note that you included the -Verbose<\/strong> flag in this command so that you could see something happening. Let\u2019s try running the command again<\/p>\n
> PS (5) > Unregister-Event -SubscriptionId 1 >\n\nUnregister-Event : Event subscription with identifier '1' does not >\nexist. >\nAt line:1 char:17 >\n+ Unregister-Event <<<< -SubscriptionId 1 >\n+ CategoryInfo : InvalidArgument: (:) [Unregister-Event >\n], ArgumentException >\n+ FullyQualifiedErrorId : INVALID_SUBSCRIPTION_IDENTIFIER, >\nMicrosoft.PowerShell.Commands.UnregisterEventCommand >\n<\/pre>\n
\u2026and it results in an error. The Unregister-Event<\/strong> cmdlet is silent as long as nothing goes wrong. If something does go wrong, you get an error.<\/p>\n
We\u2019ve covered the basics of creating and managing event subscriptions. But before the handlers for these events can do much useful work, they\u2019ll need access to additional information. In the next section, you\u2019ll write more sophisticated handlers and see how they can use the automatic variables provided by the eventing subsystem.<\/p>\n
Asynchronous event handling with scriptblocks<\/h2>\n
In this section, we\u2019ll look at the automatic variables and other features that PowerShell provides to allow scriptblocks to be used as effective event handlers.<\/p>\n
Automatic variables in the event handler<\/h3>\n
In PowerShell eventing, the scriptblock that handles the event action has access to a number of variables that provide information about the event being handled:<\/p>\n
> $event, $eventSubscriber, $sender, $sourceEventArgs, and $sourceArgs<\/code><\/p>\n
These variables are described in table 2.<\/p>\n
Table 2<\/strong> The automatic variables available in the event handler scriptblock<\/p>\n\n\n\n\n\n\n\n\n
\n
\n          Variable\n        <\/p>\n<\/td>\n
\n
\n          Description\n        <\/p>\n<\/td>\n<\/tr>\n
\n
\n          $event\n        <\/p>\n<\/td>\n
\n
\n          This variable contains an object of type System.Management.Automation.PSEventArgs that represents the event that\u2019s being handled. It allows you to access a wide variety of information about the event, as you\u2019ll see in an example. The value of this variable is the same object that the Get-Event cmdlet returns.\n        <\/p>\n<\/td>\n<\/tr>\n
\n
\n          $eventSubscriber\n        <\/p>\n<\/td>\n
\n
\n          This variable contains the PSEventSubscriber object that represents the event subscriber of the event that\u2019s being handled. The value of this variable is the same object that the Get-EventSubscriber cmdlet returns.\n        <\/p>\n<\/td>\n<\/tr>\n
\n
\n          $sender\n        <\/p>\n<\/td>\n
\n
\n          The value in this variable is the object that generated the event. This variable is a shortcut for $EventArgs.Sender.\n        <\/p>\n<\/td>\n<\/tr>\n
\n
\n          $sourceEventArgs\n        <\/p>\n<\/td>\n
\n
\n          Contains objects that represent the arguments of the event that\u2019s being processed. This variable is a shortcut for $Event.SourceArgs.\n        <\/p>\n<\/td>\n<\/tr>\n
\n
\n          $sourceArgs\n        <\/p>\n<\/td>\n
\n
\n          Contains the values from $Event.SourceArgs. Like any other scriptblock, if there is a param statement, the parameters defined by that statement will be populated and $args will only contain leftover values for which there were no parameters.\n        <\/p>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Let\u2019s write a quick test event handler to see what\u2019s in the object in $Event<\/strong>. You\u2019ll use the timer event again:<\/p>\n
> PS (1) > $timer = New-Object System.Timers.Timer -Property @{ >\n\n\n>> Interval = 1000; Enabled = $true; AutoReset = $false } >\n>> \n<\/pre>\n
In the event subscription action, you\u2019ll display the contents of the event object:<\/p>\n
PS (2) > Register-ObjectEvent $timer Elapsed -Action { >\n>> $Event | Out-Host >\n>> } >\n>>  >\n  >\nId          Name                State      HasMoreData      Location >\n--          ----                -----      -----------      -------- >\n4           9e3586c3-534...     NotStarted False  >\n<\/pre>\n
You\u2019ll start the timer to generate the event:<\/p>\n
PS (3) > $timer.Start() >\nPS (4) > >\n  >\nComputerName     : >\nRunspaceId       : 373d0ee9-47a5-4ceb-89e5-61e6389d6838 >\nEventIdentifier  : 7 >\nSender           : System.Timers.Timer >\nSourceEventArgs  : System.Timers.ElapsedEventArgs >\nSourceArgs       : {System.Timers.Timer, System.Timers.ElapsedEv >\nentArgs} >\nSourceIdentifier : 9e3586c3-534b-465a-84b3-7404110a0f12 >\nTimeGenerated    : 8\/10\/2010 12:17:40 PM >\nMessageData      : >\n<\/pre>\n
In this output, you see the properties on the PSEvent**** **object that correspond to the variables listed in table 2. The **Timer<\/strong> object that generated the event is available through the Sender property on the object and the $sender<\/strong> variable in the scriptblock.<\/p>\n
The PSEvent<\/strong> object also includes context data about the event, including the time the event occurred, the event identifier, and the RunspaceId<\/strong> this event is associated with. The ComputerName<\/strong> property is blank because this is a local event, but, in the case of a remote event, it would contain the name of the computer where the event occurred.<\/p>\n
Dynamic modules and event handler state<\/h3>\n
Because an event can fire at any time, you could never know what variables were in scope and this, in turn, could make it hard to know what state will exist when the action is executed. Instead, you want to be able to run the event handlers in a well-defined, isolated environment. This objective aligns with the design goals for PowerShell modules, so you can leverage this feature by creating a dynamic module for the action scriptblock. The eventing subsystem does this by calling the New-BoundScriptBlockScriptblock()<\/strong> method to attach a dynamic module to the handler scriptblock.<\/p>\n
Beyond ensuring a coherent runtime environment for your event handler scriptblock, the module also allows it to have private state. This ability can be quite useful when you\u2019re monitoring a system\u2019s behavior over a period of time. The information can be accumulated privately and then processed once enough samples have been gathered. Let\u2019s look at an example that illustrates how this state isolation works. The following is a trivial example where you maintain a count of the number of timer events fired. Once you reach a predetermined limit, the timer will be stopped. Let\u2019s walk through the example. First, you create the Timer<\/strong> object:<\/p>\n
PS (1) > $timer = New-Object System.Timers.Timer -Property @{ >\n>> Interval = 500; AutoReset = $true} >\n>>  >\n<\/pre>\n
As usual, subscribe to the Elapsed<\/strong> event on the timer:<\/p>\n
PS (2) > Register-ObjectEvent -InputObject $timer ` >\n>> -MessageData 5 ` >\n>> -SourceIdentifier Stateful -EventName Elapsed -Action { >\n>> $script:counter += 1 >\n>> Write-Host \"Event counter is $counter\" >\n>> if ($counter -ge $Event.MessageData) >\n>> { >\n>> Write-Host \"Stopping timer\" >\n>> $timer.Stop() >\n>> } >\n>> } > $null >\n>>  >\n<\/pre>\n
In the handler scriptblock for this event, you\u2019re updating a script-scoped variable $script:counter<\/strong>, which holds the number of times the event has fired. This variable will only be visible within the dynamic module associated with the event, thus preventing your $counter<\/strong> from colliding with any other users of a variable called $counter<\/strong>.<\/p>\n
After the variable is incremented, you print the event count and then check to see if the limit has been reached. Notice that you\u2019re making use of the -MessageData<\/strong> parameter to pass the limit to the event handler, which it retrieves from the MessageData<\/strong> property on the **Event **object. Now start the timer running to see it in action:<\/p>\n
PS (3) > $timer.Start() >\nPS (4) > >\nPS (5) > Event counter is 1 >\nEvent counter is 2 >\nEvent counter is 3 >\nEvent counter is 4 >\nEvent counter is 5 >\nStopping timer >\n  >\nPS (6) > >\n<\/pre>\n
As intended, the timer message is displayed five times and then the timer is stopped. This example can easily be modified to, for example, monitor CPU usage or process working sets over a period of time.<\/p>\n
Summary<\/h2>\n
There are two fundamental event types: synchronous and asynchronous. In synchronous events, all activities are synchronized so that no activity is ever interrupted. Asynchronous events execute in a nondeterministic order. To deal with these asynchronous events, PowerShell includes an eventing subsystem that takes care of synchronizing all operations. The core model for eventing in PowerShell is built around the idea of event subscriptions. There are three cmdlets for creating these subscriptions: Get-ObjectEvent<\/strong>, Get-WmiEvent<\/strong>, and Get-EngineEvent<\/strong> for .NET, WMI, and PowerShell engine events respectively.<\/p>\n
As part of the event subscription, an action scriptblock may be specified that will be executed when the event is triggered. Context information for the event is made available to the scriptblock through the $Event<\/strong> automatic variable. Some of the properties on the object in $Event<\/strong> are also directly available through additional automatic variables.<\/p>\n
Thank you, Bruce.<\/p>\n
Well, this concludes an awesome week of guest writers from Manning Press. Join me tomorrow for the Weekend Scripter as I delve into my top ten favorite Windows PowerShell tricks.<\/p>\n
I invite you to follow me on Twitter<\/a> and Facebook<\/a>. If you have any questions, send email to me at scripter@microsoft.com<\/a>, or post your questions on the Official Scripting Guys Forum<\/a>. See you tomorrow. Until then, peace.<\/p>\n
Ed Wilson, Microsoft Scripting Guy<\/strong><\/p>\n","protected":false},"excerpt":{"rendered":"
Summary: Bruce Payette shows how to manage event subscriptions with Windows PowerShell. Microsoft Scripting Guy, Ed Wilson, here. I am really excited about the idea I had for this week, and I hope you will be too. I asked Candace Gillhoolley at Manning Press about posting some sample works from some of the Manning Press […]<\/p>\n","protected":false},"author":595,"featured_media":87096,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[266,42,56,3,4,45],"class_list":["post-13601","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-bruce-payette","tag-events-and-monitoring","tag-guest-blogger","tag-scripting-guy","tag-scripting-techniques","tag-windows-powershell"],"acf":[],"blog_post_summary":"
Summary: Bruce Payette shows how to manage event subscriptions with Windows PowerShell. Microsoft Scripting Guy, Ed Wilson, here. I am really excited about the idea I had for this week, and I hope you will be too. I asked Candace Gillhoolley at Manning Press about posting some sample works from some of the Manning Press […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/13601","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/users\/595"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=13601"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/13601\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media\/87096"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media?parent=13601"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=13601"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=13601"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}