Receive-Event.ps1

function Receive-Event
{
    <#
    .Synopsis
        Receives Events
    .Description
        Receives Events and output from Event Subscriptions.
    .Link
        Send-Event
    .Link
        Watch-Event
    .Example
        Get-EventSource -Subscriber | Receive-Event
    .Example
        Receive-Event -SourceIdentifier * -First 1 # Receives the most recent event with any source identifier.
    #>
    [CmdletBinding(DefaultParameterSetName='Instance')]
    [OutputType([PSObject], [Management.Automation.PSEventArgs])]
    param(
    # The event subscription ID.
    [Parameter(Mandatory,ValueFromPipelineByPropertyName,ParameterSetName='SubscriptionID')]
    [int[]]
    $SubscriptionID,

    # The event ID.
    [Parameter(Mandatory,ValueFromPipelineByPropertyName,ParameterSetName='EventIdentifier')]
    [int[]]
    $EventIdentifier,

    # The event source identifier.
    [Parameter(Mandatory,ValueFromPipelineByPropertyName,ParameterSetName='SourceIdentifier')]
    [Parameter(ValueFromPipelineByPropertyName,ParameterSetName='SubscriptionID')]
    [Parameter(ValueFromPipelineByPropertyName,ParameterSetName='EventIdentifier')]
    [string[]]
    $SourceIdentifier,

    # If provided, will return the first N events
    [int]
    $First,

    # If provided, will skip the first N events.
    [int]
    $Skip,

    # The input object.
    # If the Input Object was a job, it will receive the results of the job.
    [Parameter(ValueFromPipeline)]
    [PSObject]
    $InputObject,

    # If set, will remove events from the system after they have been returned,
    # and will not keep results from Jobs or Event Handlers.
    [switch]
    $Clear
    )



    begin {
        #region Prepare Accumulation
        # We will accumulate the events we output in case we need to -Clear them.
        $accumulated = [Collections.Arraylist]::new()
        filter accumulate {
            if (-not $skip -or ($accumulated.Count -ge $skip)) {
                $_
            }

            if (-not $First -or ($accumulated.Count -lt ($First + $skip))) {
                $null = $accumulated.Add($_)
            }
        }
        #endregion Prepare Accumulation
    }
    process {
        #region Passthru Events
        if ($PSCmdlet.ParameterSetName -eq 'EventIdentifier' -and
            $_ -is [Management.Automation.PSEventArgs]) {
            $_ | accumulate # pass events thru and accumulate them for later.
            return
        }
        #endregion PassThru Events
        #region Receiving Events by SourceIdentifier
        if ($PSCmdlet.ParameterSetName -in 'SourceIdentifier', 'EventIdentifier') {
            :nextEvent for ($ec = $PSCmdlet.Events.ReceivedEvents.Count -1 ; $ec -ge 0; $ec--) {
                $evt = $PSCmdlet.Events.ReceivedEvents[$ec]
                if ($SourceIdentifier) {
                    foreach ($sid in $sourceIdentifier) {
                        if ($evt.SourceIdentifier -eq $sid -or $evt.SourceIdentifier -like $sid) {
                            $evt | accumulate
                        }
                        if ($First -and $accumulated.Count -ge ($First + $Skip)) {
                            break nextEvent
                        }
                    }
                }
                if ($EventIdentifier) {
                    foreach ($eid in $EventIdentifier) {
                        if ($evt.EventIdentifier -eq $eid) {
                            $evt | accumulate
                        }
                        if ($First -and $accumulated.Count -ge ($First + $Skip)) {
                            break nextEvent
                        }
                    }
                }
            }
            return
        }
        #endregion Receiving Events by SourceIdentifier
        #region Receiving Events by SubscriptionID
        if ($PSCmdlet.ParameterSetName -eq 'SubscriptionID') {
            $SubscriptionID |
                # Find all event subscriptions with that subscription ID
                Get-EventSubscriber -SubscriptionId { $_ } -ErrorAction SilentlyContinue |
                # that have an .Action.
                Where-Object { $_.Action } |
                # Then pipe that action to
                Select-Object -ExpandProperty Action |
                # Receive-Job (-Keep results by default unless -Clear is passed).
                Receive-Job -Keep:(-not $Clear)
            return
        }
        #endregion Receiving Events by SubscriptionID

        #region Receiving Events by InputObject
        if ($InputObject) { # If the input object was a job,
            if ($InputObject -is [Management.Automation.Job]) {
                # Receive-Job (-Keep results by default unless -Clear is passed).
                $InputObject | Receive-Job -Keep:(-not $Clear)
            } else {
                # Otherwise, find event subscribers
                Get-EventSubscriber |
                    # whose source is this input object
                    Where-Object Source -EQ $InputObject |
                    # that have an .Action.
                    Where-Object { $_.Action } |
                    # Then pipe that action to
                    Select-Object -ExpandProperty Action |
                    # Receive-Job (-Keep results by default unless -Clear is passed).
                    Receive-Job -Keep:(-not $Clear)
            }
        }
        #endregion Receiving Events by InputObject
    }

    end {
        #region -Clear accumulation (if requested)
        if ($accumulated.Count -and $Clear) { # If we accumulated events, and said to -Clear them,
            $accumulated | Remove-Event       # remove those events.
        }
        #region -Clear accumulation (if requested)
    }
}