Category Archives: Event

Wait-Event

February 26, 2014 Adam

SYNOPSIS
Waits until a particular event is raised before continuing to run.

SYNTAX
Wait-Event [[-SourceIdentifier] <string>] [-Timeout <int>] [<CommonParameters>]

DESCRIPTION
The Wait-Event cmdlet suspends execution of a script or Function until a particular event is raised. Execution resumes when the event is detected. To cancel the wait, press CTRL+C.

This feature provides an alternative to polling for an event. It also allows you to determine the response to an event in two different ways: by using the Action parameter of the event subscription and by waiting for an event to return and then respond with an action.

PARAMETERS
-SourceIdentifier <string>
Waits only for events with the specified source identifier. By default, Wait-Events waits for any event.

        Required?                    false
        Position?                    1
        Default value                All events
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-Timeout <int>
Determines the maximum time, in seconds, that Wait-Event waits for the event to occur. The default, -1, waits indefinitely. The timing starts when you submit the Wait-Event command.

If the specified time is exceeded, the wait ends and the command prompt returns, even if the event has not been raised. No error message is displayed.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
System.String

OUTPUTS
System.String

NOTES

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 1 ————————–

C:\PS>Wait-Event

    Description
    ———–
    This command waits for the next event that is raised.

————————– EXAMPLE 2 ————————–

C:\PS>Wait-Event -SourceIdentifier “ProcessStarted”

    Description
    ———–
    This command waits for the next event that is raised and that has a source identifier of “ProcessStarted”.

————————– EXAMPLE 3 ————————–

    C:\PS>$timer.Interval = 2000
    C:\PS> $timer.Autoreset = $false
    C:\PS> $timer.Enabled = $true; Wait-Event Timer.Elapsed

# After 2 seconds

    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

    Description
    ———–
    This command uses the Wait-Event cmdlet to wait for a timer event on a timer that is set for 2000 milliseconds.

————————– EXAMPLE 4 ————————–

C:\PS>Wait-Event -SourceIdentifier “ProcessStarted” -Timeout 90

    Description
    ———–
    This command waits up to 90 seconds for the next event that is raised and that has a source identifier of “ProcessStarted”. If the specified time expires, the wait ends.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=135276
    Register-ObjectEvent
    Register-EngineEvent
    Register-WmiEvent
    Unregister-Event
    Get-Event
    New-Event
    Remove-Event
    Wait-Event
    Get-EventSubscriber

cmdlet, Event, Unregister

Unregister-Event

February 26, 2014 Adam

NAME
Unregister-Event

SYNOPSIS
Cancels an event subscription.

SYNTAX
Unregister-Event [-SubscriptionId] <int> [-Force] [-Confirm] [-WhatIf] [<CommonParameters>]

Unregister-Event [-SourceIdentifier] <string> [-Force] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Unregister-Event cmdlet cancels an event subscription that was created by using the Register-EngineEvent, Register-ObjectEvent, or Register-WmiEvent cmdlet.

When an event subscription is canceled, the event subscriber is deleted from the session and the subscribed events are no longer added to the event queue. When you cancel a subscription to an event created by using the New-Event cmdlet, the new event is also deleted from the session.

Unregister-Event does not delete events from the event queue. To delete events, use the Remove-Event cmdlet.

PARAMETERS
-Force [<SwitchParameter>]
Cancels all event subscriptions, including subscriptions that were hidden by using the SupportEvent parameter of Register-ObjectEvent, Register-WmiEvent, and Register-EngineEvent.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-SourceIdentifier <string>
Cancels event subscriptions that have the specified source identifier.

A SourceIdentifier or SubscriptionId parameter must be included in every command.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-SubscriptionId <int>
Cancels event subscriptions that have the specified subscription identifier.

A SourceIdentifier or SubscriptionId parameter must be included in every command.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-Confirm [<SwitchParameter>]
Prompts you for confirmation before executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-WhatIf [<SwitchParameter>]
Describes what would happen if you executed the command without actually executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

INPUTS
System.Management.Automation.PSEventSubscriber
You can pipe the output from Get-EventSubscriber to Unregister-Event.

OUTPUTS
None
This cmdlet does not return any output.

NOTES

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.

Unregister-Event cannot delete events created by using the New-Event cmdlet unless you have subscribed to the event by using the Register-EngineEvent cmdlet. To delete a custom event from the session, you must remove it programmatically or close the session.

————————– EXAMPLE 1 ————————–

C:\PS>Unregister-Event -SourceIdentifier ProcessStarted

    Description
    ———–
    This command cancels the event subscription that has a source identifier of “ProcessStarted”.

To find the source identifier of an event, use the Get-Event cmdlet. To find the source identifier of an event subscription, use the Get-EventSubscriber cmdlet.

————————– EXAMPLE 2 ————————–

C:\PS>Unregister-Event -subscriptionId 2

    Description
    ———–
    This command cancels the event subscription that has a subscription identifier of 2.

To find the subscription identifier of an event subscription, use the Get-EventSubscriber cmdlet.

————————– EXAMPLE 3 ————————–

C:\PS>Get-Eventsubscriber -Force | Unregister-Event -Force

    Description
    ———–
    This command cancels all event subscriptions in the session.

The command uses the Get-EventSubscriber cmdlet to get all event subscriber objects in the session, including the subscribers that are hidden by using the SupportEvent parameter of the event registration cmdlets.

It uses a pipeline operator (|) to send the subscriber objects to Unregister-Event, which deletes them from the session. To complete the task, the Force parameter is also required on Unregister-Event.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=135269
    Register-ObjectEvent
    Register-EngineEvent
    Register-WmiEvent
    Unregister-Event
    Get-Event
    New-Event
    Remove-Event
    Wait-Event
    Get-EventSubscriber

cmdlet, Event, Remove

Remove-Event

February 26, 2014 Adam

NAME
Remove-Event

SYNOPSIS
Deletes events from the event queue.

SYNTAX
Remove-Event [-EventIdentifier] <int> [-Confirm] [-WhatIf] [<CommonParameters>]

Remove-Event [-SourceIdentifier] <string> [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Remove-Event cmdlet deletes events from the event queue in the current session.

This cmdlet deletes only the events currently in the queue. To cancel event registrations or unsubscribe, use the Unregister-Event cmdlet.

PARAMETERS
-EventIdentifier <int>
Deletes only the event with the specified event identifier. An EventIdentifier or SourceIdentifier parameter is required in every command.

        Required?                    true
        Position?                    1
        Default value                None
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-SourceIdentifier <string>
Deletes only the events with the specified source identifier. Wildcards are not permitted. An EventIdentifier or SourceIdentifier parameter is required in every command.

        Required?                    true
        Position?                    1
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

-Confirm [<SwitchParameter>]
Prompts you for confirmation before executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-WhatIf [<SwitchParameter>]
Describes what would happen if you executed the command without actually executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

INPUTS
System.Management.Automation.PSEventArgs
You can pipe events from Get-Event to Remove-Event.

OUTPUTS
None
The cmdlet does not generate any output.

NOTES

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 1 ————————–

C:\PS>Remove-Event -SourceIdentifier “ProcessStarted”

    Description
    ———–
    This command deletes events with a source identifier of “Process Started” from the event queue.

————————– EXAMPLE 2 ————————–

C:\PS>Remove-Event -eventIdentifier 30

    Description
    ———–
    This command deletes the event with an event ID of 30 from the event queue.

————————– EXAMPLE 3 ————————–

C:\PS>Get-Event | Remove-Event

    Description
    ———–
    This command deletes all events from the event queue.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=135247
    Register-ObjectEvent
    Register-EngineEvent
    Register-WmiEvent
    Unregister-Event
    Get-Event
    New-Event
    Remove-Event
    Wait-Event

cmdlet, Event, New

New-Event

February 26, 2014 Adam

NAME
New-Event

SYNOPSIS
Creates a new event.

SYNTAX
New-Event [-SourceIdentifier] <string> [[-Sender] <psobject>] [[-EventArguments] <PSObject[]>] [[-MessageData] <psobject>] [<CommonParameters>]

DESCRIPTION
The New-Event cmdlet creates a new custom event.

You can use custom events to notify users about state changes in your program and any change that your program can detect, including hardware or system conditions, application status, disk status, network status, or the completion of a background job.

Custom events are automatically added to the event queue in your session whenever they are raised; you do not need to subscribe to them. However, if you want to forward an event to the local session or specify an action to respond to the event, use the Register-EngineEvent cmdlet to subscribe to the custom event.

When you subscribe to a custom event, the event subscriber is added to your session. If you cancel the event subscription by using the Unregister-Event cmdlet, the event subscriber and custom event are deleted from the session. If you do not subscribe to the custom event, to delete the event, you must change the program conditions or close the Windows PowerShell session.

PARAMETERS
-EventArguments <PSObject[]>
Specifies an object that contains options for the event.

        Required?                    false
        Position?                    3
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

-MessageData <psobject>
Specifies additional data associated with the event. The value of this parameter appears in the MessageData property of the event object.

        Required?                    false
        Position?                    4
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

-Sender <psobject>
Specifies the object that raises the event. The default is the Windows PowerShell engine.

        Required?                    false
        Position?                    2
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

-SourceIdentifier <string>
Specifies a name for the new event. This parameter is required, and it must be unique in the session.

The value of this parameter appears in the SourceIdentifier property of the events.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
System.Management.Automation.PSEventArgs

NOTES

The new custom event, the event subscription, 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 1 ————————–

C:\PS>New-Event -SourceIdentifier Timer -Sender windows.timer -MessageData “Test”

    Description
    ———–
    This command creates a new event in the Windows PowerShell event queue. It uses a Windows.Timer object to send the event.

————————– EXAMPLE 2 ————————–

    C:\PS>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
     $identifier = “WMI.ProcessCreated”

     Register-ObjectEvent $processWatcher “EventArrived” -SupportEvent $identifier -Action {
         [void] (New-Event -sourceID “PowerShell.ProcessCreated” -Sender $args[0] -EventArguments $args[1].SourceEventArgs.NewEvent.TargetInstance)
     }
    }

    Description
    ———–
    This sample Function uses the New-Event cmdlet to raise an event in response to another event. The command uses the Register-ObjectEvent cmdlet to subscribe to the Windows Management Instrumentation (WMI) event that is raised when a new process is created. The command uses the Action parameter of the cmdlet to call the New-Event cmdlet, which creates the new event.

Because the events that New-Event raises are automatically added to the Windows PowerShell event queue, you do not need to register for that event.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=135234
    Register-ObjectEvent
    Register-EngineEvent
    Register-WmiEvent
    Unregister-Event
    Get-Event
    Remove-Event
    Wait-Event

cmdlet, Event, Get

Get-Event

February 26, 2014 Adam

NAME
Get-Event

SYNOPSIS
Gets the events in the event queue.

SYNTAX
Get-Event [-EventIdentifier] <int> [<CommonParameters>]

Get-Event [[-SourceIdentifier] <string>] [<CommonParameters>]

DESCRIPTION
The Get-Event cmdlet gets events in the Windows PowerShell event queue for the current session. You can get all events or use the EventIdentifier or SourceIdentifier parameters to specify the events.

When an event occurs, it is added to the event queue. The event queue includes events for which you have registered, events created by using the New-Event cmdlet, and the event that is raised when Windows PowerShell exits. You can use Get-Event or Wait-Event to get the events.

This cmdlet does not get events from the Event Viewer logs. To get those events, use Get-WinEvent or Get-EventLog.

PARAMETERS
-EventIdentifier <int>
Gets only the events with the specified event identifier.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-SourceIdentifier <string>
Gets only events with the specified source identifier. The default is all events in the event queue. Wildcards are not permitted.

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
System.Management.Automation.PSEventArgs
Get-Event returns a PSEventArgs object for each event. To see a description of this object, type “Get-Help Get-Event -full” and see the Notes section of the help topic.

NOTES

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.

The Get-Event cmdlet returns a PSEventArgs object (System.Management.Automation.PSEventArgs) with the following properties.

— ComputerName: The name of the computer on which the event occurred. This property value is populated only when the event is forwarded from a remote computer.

— RunspaceId: A GUID that uniquely identifies the session in which the event occurred. This property value is populated only when the event is forwarded from a remote computer.

— EventIdentifier: An integer (Int32) that uniquely identifies the event notification in the current session.

— Sender: The object that generated the event. In the value of the Action parameter, the $Sender automatic Variable contains the sender object.

— SourceEventArgs: The first parameter that derives from EventArgs, if it exists. For example, in a timer elapsed event in which the signature has the form “Object sender, Timers.ElapsedEventArgs e”, the SourceEventArgs property would contain the Timers.ElapsedEventArgs. In the value of the Action parameter, the $SourceEventArgs automatic Variable contains this value.

— SourceArgs: All parameters of the original event signature. For a standard event signature, $args[0] represents the sender, and $args[1] represents the SourceEventArgs. In the value of the Action parameter, the $SourceArgs automatic Variable contains this value.

— SourceIdentifier: A string that identifies the event subscription. In the value of the Action parameter, the SourceIdentifier property of the $Event automatic Variable contains this value.

— TimeGenerated: A DateTime object that represents the time at which the event was generated. In the value of the Action parameter, the TimeGenerated property of the $Event automatic Variable contains this value.

–MessageData: Data associated with the event subscription. Users specify this data when they register an event. In the value of the Action parameter, the MessageData property of the $Event automatic Variable contains this value.

————————– EXAMPLE 1 ————————–

C:\PS>Get-Event

    Description
    ———–
    This command gets all events in the event queue.

————————– EXAMPLE 2 ————————–

C:\PS>Get-Event -SourceIdentifier “PowerShell.ProcessCreated”

    Description
    ———–
    This command gets events in which the value of the SourceIdentifier property is “PowerShell.ProcessCreated”.

————————– EXAMPLE 3 ————————–

C:\PS>$events = Get-Event

C:\PS> $events[0] | Format-List -property *

    ComputerName     :
    RunspaceId     : c2153740-256d-46c0-a57c-b805917d1b7b
    EventIdentifier : 1
    Sender         : System.Management.ManagementEventWatcher
    SourceEventArgs : System.Management.EventArrivedEventArgs
    SourceArgs     : {System.Management.ManagementEventWatcher, System.Management.EventArrivedEventArgs}
    SourceIdentifier : ProcessStarted
    TimeGenerated    : 11/13/2008 12:09:32 PM
    MessageData     :

C:\PS> Get-Event | where {$_.TimeGenerated -ge “11/13/2008 12:15:00 PM”}

    ComputerName     :
    RunspaceId     : c2153740-256d-46c0-a57c-b8059325d1a0
    EventIdentifier : 1
    Sender         : System.Management.ManagementEventWatcher
    SourceEventArgs : System.Management.EventArrivedEventArgs
    SourceArgs     : {System.Management.ManagementEventWatcher, System.Management.EventArrivedEventArgs}
    SourceIdentifier : ProcessStarted
    TimeGenerated    : 11/13/2008 12:15:00 PM
    MessageData     :

    Description
    ———–
    This example shows how to get events by using properties other than SourceIdentifier.

The first command gets all events in the event queue and saves them in the $events Variable.

The second command uses array notation to get the first (0-index) event in the array in the $events Variable. The command uses a pipeline operator (|) to send the event to the Format-List command, which displays all properties of the event in a list. This allows you to examine the properties of the event object.

The third command shows how to use the Where-Object cmdlet to get an event
based on the time that it was generated.

————————– EXAMPLE 4 ————————–

C:\PS>Get-Event -eventIdentifier 2

    Description
    ———–
    This command gets the event with an event identifier of 2.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113453
    Register-ObjectEvent
    Register-EngineEvent
    Register-WmiEvent
    Unregister-Event
    New-Event
    Remove-Event
    Wait-Event