PowerShell calls .net and subscribes to events [source code]

Abstract
    Subscribes to the events that are generated by a Microsoft .NET Framework object.

grammar
    Register-ObjectEvent [-InputObject] <PSObject> [-EventName] <String> [[-SourceIdentifier] <String>] [[-Action] <ScriptBlock>] [-Forward ] [-MaxTriggerCount <Int32>] [-MessageData <PSObject>] [-SupportEvent ] [<CommonParameters>]


input
    None
    You cannot pipe objects to Register-ObjectEvent .

output
    System.Management.Automation.PSEventJob
    This cmdlet does not generate any output.

exegesis
    * Events, event subscriptions, and the event queue exist only in the current session. If you close the current session, the event queue is discarded and the event subscription is canceled.
   

example
    Example 1: Subscribe to events when a new process starts
    PS C:\>$Query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1), "TargetInstance isa 'Win32_Process'"
    PS C:\>$ProcessWatcher = New-Object System.Management.ManagementEventWatcher $Query
    PS C:\>Register-ObjectEvent -InputObject $ProcessWatcher -EventName "EventArrived"
   
    This example subscribes to events generated when a new process starts.

The command uses the ManagementEventWatcher object to get EventArrived events. A query object specifies that the events are instance creation events for the Win32_Process class.
    Example 2: Specify an action to respond to an event
    PS C:\>$Query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1), "TargetInstance isa 'Win32_Process'"
    PS C:\>$ProcessWatcher = New-Object System.Management.ManagementEventWatcher $query
    PS C:\>$Action = { New-Event "PowerShell.ProcessCreated" -Sender $Sender -EventArguments $EventArgs.NewEvent.TargetInstance }
    PS C:\>register-objectEvent -InputObject $ProcessWatcher -EventName "EventArrived" -Action $Action
    Id    Name            State      HasMoreData     Location             Command
    --    ----            -----      -----------     --------             -------
    2     422cfe5a-65e... Running    True                                 New-Event "PowerShe...
   
    This example shows how to specify an action to respond to an event. When you specify an action, events that are raised are not added to the event queue. Instead, the action responds to the event.

In this example, when an instance creation event is raised indicating that a new process is started, a new ProcessCreated event is raised.

The action uses the $Sender and $EventArgs automatic variables which are populated only for event actions.

The Register-ObjectEvent command returns a job object that represents the action, which runs as a background job. You can use the Job cmdlets, such as Get-Job and Receive-Job, to manage the background job.

For more information, see about_Jobs.
    Example 3: Subscribe to object events on remote computers
    PS C:\>$S = New-PSSession -ComputerName "Server01, Server02"
    PS C:\> Invoke-Command -Session $S -FilePath ProcessCreationEvent.ps1
    PS C:\> Invoke-Command -Session $S { get-event }# ProcessCreationEvent.ps1function 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   $Identifier = "WMI. ProcessCreated"   Register-ObjectEvent -Input $ProcessWatcher -EventName "EventArrived" `
       -SourceIdentifier $Identifier -MessageData "Test" -Forward}EnableProcessCreationEvent
   
    This example shows how to subscribe to object events on remote computers.

The first command creates PSSessions on two remote computers and saves them in the $S variable.

The second command uses the FilePath parameter of the Invoke-Command cmdlet to run the ProcessCreationEvent.ps1 script in the each of the PSSessions in $S.

The script includes a Register-ObjectEvent command that subscribes to instance creation events on the Win32_Process object through the ManagementEventWatcher object and its EventArrived event.
    Example 4: Use the dynamic module in the PSEventJob object
    PS C:\>$Timer = New-Object Timers.Timer
    PS C:\>$Timer.Interval = 500
    PS C:\>$Job = Register-ObjectEvent -InputObject $Timer -EventName Elapsed -SourceIdentifier Timer.Random -Action {$Random = Get-Random -Min 0 -Max 100}
    PS C:\>$Job.gettype().fullnameSystem.Management.Automation.PSEventJob
    PS C:\>$Job | Format-List -Property *
    State         :
    RunningModule        : __DynamicModule_6b5cbe82-d634-41d1-ae5e-ad7fe8d57fe0
    StatusMessage :
    HasMoreData   : True
    Location      :
    Command       : $Random= Get-Random -Min 0 -Max 100
    JobStateInfo  : Running
    Finished      : System.Threading.ManualResetEvent
    InstanceId    : 88944290-133d-4b44-8752-f901bd8012e2
    Id            : 1
    Name          : Timer.Random
    ChildJobs     : {}... PS C:\>$Timer.Enabled = $True
    PS C:\>& $Job.module {$Random}60
    PS C:\>& $Job.module {$Random}47
   
    This example shows how to use the dynamic module in the PSEventJob object that is created when you include an Action in an event registration.

The first command uses the New-Object cmdlet to create a timer object. The second command sets the interval of the timer to 500 (milliseconds).

The third command uses the Register-ObjectEvent cmdlet to register the Elapsed event of the timer object. The command includes an action that handles the event. Whenever the timer interval elapses, an event is raised and the commands in the action run. In this case, the Get-Random cmdlet generates a random number between 0 and 100 and saves it in the $Randomvariable.

When you use an Action parameter in a Register-ObjectEvent command, the command returns a PSEventJob object that represents the action. The command saves the job object in the $Job variable.

The PSEventJob object that the Register-ObjectEvent cmdlet returns is also available in the Action property of the event subscriber. For more information, see Get-EventSubscriber.

The fourth command shows that the $Job variable contains a PSEventJob object. The fifth command uses the Format-List cmdlet to display all of the properties of the PSEventJob object in a list.

The PSEventJob has a Module property that contains a dynamic script module that implements the action.

The sixth command enables the timer.

The remaining commands use the call operator (&) to invoke the command in the module and display the value of the $Random variable. You can use the call operator to invoke any command in a module, including commands that are not exported. In this case, the commands show the random number that is being generated when the Elapsed event occurs.

For more information about modules, see about_Modules.


RelatedLinks
    Online Version: http://go.microsoft.com/fwlink/?LinkId=821845
    Get-Event
    New-Event
    Register-EngineEvent
    Register-WmiEvent
    Remove-Event
    Unregister-Event
    Wait-Event