Watch-Event.ps1

function Watch-Event {
    <#
    .Synopsis
        Watches Events
    .Description
        Watches Events by SourceIdentifier, or using an EventSource script.
    .Example
        Watch-Event -SourceIdentifier MySignal -Then {"fire!" | Out-Host }
    .Example
        On MySignal { "fire!" | Out-host }

        New-Event MySignal
    .Link
        Get-EventSource
    .Link
        Register-ObjectEvent
    .Link
        Register-EngineEvent
    .Link
        Get-EventSubscriber
    .Link
        Unregister-Event
    #>
    [CmdletBinding(PositionalBinding=$false)]
    [OutputType([nullable],[PSObject])]
    param()

    dynamicParam {
        #region Handle Input Dynamically
        # Watch-Event is written in an unusually flexible way:
        # It has no real parameters, only dynamic ones.
        $DynamicParameters = [Management.Automation.RuntimeDefinedParameterDictionary]::new()

        # The first step of our challenge is going to be determining the Event Source.
        $eventSource = $null
        # Since we only want to make one pass,
        # we also want to start tracking the maximum position we've found for a parameter.
        $maxPosition = -1
        # We also might want to know if we created the SourceIdentifier parameter yet.
        $SourceIDParameterCreated = $false

        #region Prepare to Add SourceID Parameter
        # Since we might add SourceID at a couple of different points in the code below,
        # we'll declare a [ScriptBlock] to add the source parameter whenever we want.
        $AddSourceIdParameter = {
            $SourceIDParameterCreated = $true # The -SourceIdentifier
            $sourceIdParameter = [Management.Automation.ParameterAttribute]::new()
            $sourceIdParameter.Mandatory = $true       # will be mandatory
            $sourceIdParameter.Position = 0  # and will be first.
            # Add the dynamic parameter whenever this is called
            $DynamicParameters.Add("SourceIdentifier",
                            [Management.Automation.RuntimeDefinedParameter]::new(
                                "SourceIdentifier", [string[]], $sourceIdParameter))
            $maxPosition = 0 # and set MaxPosition to 0 for the next parameter.
        }
        #endregion Prepare to  Add SourceID Parameter

        #region Find the Event Source and Map Dynamic Parameters

        #region Determine Invocation Name
        # In order to find the event source, we need to use information about how we were called.
        # This information is stored in $myInvocation, which can change.  So we capture it's value right now.
        $myInv = $MyInvocation
        $InvocationName = '' # Our challenge is to determine the final $invocationName to use throughout the script.


        if ($myInv.InvocationName -ne $myInv.MyCommand.Name) { # If we're calling this command with an alias
            $invocationName = @($myInv.InvocationName -split '@', 2)[1] # the invocationname is what's after @.
        }


        if (-not $invocationName) { # If we don't have an invocation name,
            # we can peek at how we are being called (by looking at the $myInvocation.Line).
            $index = $myInv.Line.IndexOf($myInv.InvocationName)

            if ($index -ge 0) { # If our command is in the line,
                $myLine = $myInv.Line.Substring($index) # we can use some regex
                # to "peek" at positional parameters before the parameter even exists.

                # In this case, that regex is currently
                # the invocation name, followed by whitespace and a SourceIdentifier.
                if ($myLine -match "\s{0,}$($myInv.InvocationName)\s{1,}(?<SourceIdentifier>\w+)") {

                    $invocationName = $Matches.SourceIdentifier
                    # If we match, use that as the $invocationName
                    # and add the sourceID parameter (so the positional parameter exists).
                    . $AddSourceIdParameter
                }
            }
        }

        if (-not $InvocationName) {
            $InvocationName= $myInv.MyCommand.Name
        }

        #endregion Determine Invocation Name
        if ($invocationName -ne $myInv.MyCommand.Name) {
            #region Find Event Source

            # If we're being called with a smart alias, determine what the underlying command is.
            # But first, let's save a pointer to $executionContext.SessionState.InvokeCommand.GetCommand
            $getCmd    = $ExecutionContext.SessionState.InvokeCommand.GetCommand

            # We want the next code to match quickly and not try too many codepaths,
            # so we'll run this in a [ScriptBlock]
            $eventSource =
                . {


                    # Our first possibility is that we have an @Function or Alias.
                    # Such a function would have to be defined using the provider syntax
                    # (e.g. ${function:@EventSource} = {}) so this is _very_ unlikely to happen by mistake.
                    $atFunction = $getCmd.Invoke("@$invocationName", 'Function,Alias')
                    if ($atFunction) {
                        if ($atFunction.ResolvedCommand) {
                            return $atFunction.ResolvedCommand
                        } else {
                            return $atFunction
                        }
                    }


                    # The next possibility is an @.ps1 script.
                    $atFile = "@$($invocationName).ps1"
                    # This could be in a few places: the current directory first,
                    foreach ($foundFile in ($pwd, $myRoot | 
                        Get-ChildItem -Recurse |
                        & { process {
                            if ($_.Name -eq $atFile) { $_ }
                        } })) {
                            
                        $foundCmd = $getCmd.Invoke($foundFile.FullName, 'ExternalScript')
                        if ($foundCmd) { return $foundCmd}
                    }

                    if ($myInv.MyCommand.Module) { # then the module root
                        $MyModuleRoot = $myInv.MyCommand.Module | Split-Path -ErrorAction SilentlyContinue
                        if ($MyModule -ne $myRoot) { # (if different from $myroot).
                            $atModuleRootCmd =
                                $getCmd.Invoke(
                                    (Get-ChildItem -LiteralPath $MyModuleRoot -Filter $atFile).FullName, 'ExternalScript')
                            if ($atModuleRootCmd) { $atModuleRootCmd; continue }
                        }



                        # Last, we want to look for extensions.
                        $myModuleName = $myInv.MyCommand.Module.Name
                        foreach ($loadedModule in Get-Module) { #
                            if ( # If a module has a [Hashtable]PrivateData for this module
                                $loadedModule.PrivateData.$myModuleName
                            ) {
                                $thisModuleRoot = [IO.Path]::GetDirectoryName($loadedModule.Path)
                                $extensionData = $loadedModule.PrivateData.$myModuleName
                                if ($extensionData -is [Hashtable]) { # that is a [Hashtable]
                                    foreach ($ed in $extensionData.GetEnumerator()) { # walk thru the hashtable
                                        if ($invocationName -eq $ed.Key) { # find out event source name
                                            $extensionCmd =
                                                if ($ed.Value -like '*.ps1') { # and map it to a script or command.
                                                    $getCmd.Invoke(
                                                        (Join-Path $thisModuleRoot $ed.Value),
                                                        'ExternalScript'
                                                    )
                                                } else {
                                                    $loadedModule.ExportedCommands[$ed.Value]
                                                }

                                            # If we could map it, return it before we keep looking thru modules.
                                            if ($extensionCmd) {
                                                return $extensionCmd
                                            }
                                        }
                                    }
                                }
                            }
                            elseif ($loadedModule.Tags -contains $myModuleName) {                                
                                foreach ($matchingFile in @(Get-ChildItem (Split-Path $loadedModule.Path) -Recurse) -match '\@\w' -match '\.ps1$') {
                                    if ($matchingFile.Name -eq $atFile) {
                                        return $getCmd.Invoke($matchingFile.FullName, 'ExternalScript')
                                    }
                                }
                            }
                        }
                    }


                }
            #endregion Find Event Source
            #region Map Dynamic Parameters
            if ($eventSource) {
                # We only need to map dynamic parameters if there is an event source.
                $eventSourceMetaData = [Management.Automation.CommandMetaData]$eventSource
                # Determine if we need to offset positional parameters,
                $positionOffset = [int]$SourceIDParameterCreated
                # then walk over the parameters from that event source.
                foreach ($kv in $eventSourceMetaData.Parameters.GetEnumerator()) {

                    $attributes =
                        if ($positionOffset) { # If we had to offset the position of a parameter
                            @(foreach ($attr in $kv.value.attributes) {
                                if ($attr -isnot [Management.Automation.ParameterAttribute] -or
                                    $attr.Position -lt 0
                                ) {
                                    # we can passthru any non-parameter attributes and parameter attributes without position,
                                    $attr
                                } else {
                                    # but parameter attributes with position need to copied and offset.
                                    $attrCopy = [Management.Automation.ParameterAttribute]::new()
                                    # (Side note: without a .Clone, copying is tedious.)
                                    foreach ($prop in $attrCopy.GetType().GetProperties('Instance,Public')) {
                                        if (-not $prop.CanWrite) { continue }
                                        if ($null -ne $attr.($prop.Name)) {
                                            $attrCopy.($prop.Name) = $attr.($prop.Name)
                                        }
                                    }


                                    # Once we have  a parameter copy, offset it's position.
                                    $attrCopy.Position+=$positionOffset
                                    $pos = $attrCopy.Position
                                    $attrCopy
                                }
                            })
                        } else {
                            $pos = foreach ($a in $kv.value.attributes) {
                                if ($a.position -ge 0) { $a.position ; break }
                            }
                            $kv.Value.Attributes
                        }

                    # Add the parameter and it's potentially modified attributes.
                    $DynamicParameters.Add($kv.Key,
                        [Management.Automation.RuntimeDefinedParameter]::new(
                            $kv.Value.Name, $kv.Value.ParameterType, $attributes
                        )
                    )
                    # If the parameter position was bigger than maxPosition, update maxPosition.
                    if ($pos -ge 0 -and $pos -gt $maxPosition) { $maxPosition = $pos }
                }
            }
            #endregion Map Dynamic Parameters
        }

        #endregion Find the Event Source and Map Dynamic Parameters


        

        #region Optionally Add Source Identifier
        # If we don't have an Event Source at this point and we haven't already,
        if (-not $eventSource -and -not $SourceIDParameterCreated) { # add the SourceIdentifier parameter.
            . $addSourceIdParameter
        }
        #endregion Optionally Add Source Identifier

        #region Optionally Add InputObject Parameter
        # Also, if we don't have an event source
        if (-not $eventSource) {
            # then we can add an InputObject parameter.
            $inputObjectParameter = [Management.Automation.ParameterAttribute]::new()
            $inputObjectParameter.ValueFromPipeline = $true
            $DynamicParameters.Add("InputObject",
                    [Management.Automation.RuntimeDefinedParameter]::new(
                        "InputObject", [PSObject], $inputObjectParameter
                    )
                )

        }
        #endregion Optionally Add InputObject Parameter

        #region Add Common Parameters
        # All calls will always have two additional parameters:        
        $thenParam = [Management.Automation.ParameterAttribute]::new()
        $thenParam.Mandatory = $false #* [ScriptBlock]$then
        $thenParam.Position = ++$maxPosition
        $thenActionAlias = [Management.Automation.AliasAttribute]::new("Action")
        $DynamicParameters.Add("Then",
                        [Management.Automation.RuntimeDefinedParameter]::new(
                            "Then", [ScriptBlock], @($thenParam, $thenActionAlias)
                        )
                    )
        
        $WhenParam = [Management.Automation.ParameterAttribute]::new()
        $whenParam.Position = ++$maxPosition #* [ScriptBlock]$when
        $DynamicParameters.Add("When",
                        [Management.Automation.RuntimeDefinedParameter]::new(
                            "When", [ScriptBlock], $WhenParam
                        )
                    )
        
        $MessageDataParam = [Management.Automation.ParameterAttribute]::new()
        $MessageDataParam.Position = ++$maxPosition #* [ScriptBlock]$when
        $DynamicParameters.Add("MessageData",
                        [Management.Automation.RuntimeDefinedParameter]::new(
                            "MessageData", [PSObject], $MessageDataParam
                        )
                    )
        
        $maxTriggerParam = [Management.Automation.ParameterAttribute]::new()
        $maxTriggerParam.Position = ++$maxPosition #* [int]$MaxTriggerCount
        $DynamicParameters.Add("MaxTriggerCount",
            [Management.Automation.RuntimeDefinedParameter]::new(
                "MaxTriggerCount", [int], @(
                    $maxTriggerParam,
                    [Management.Automation.AliasAttribute]::new("Max"),
                    [Management.Automation.AliasAttribute]::new("Count")
                )
            )
        )
        #endregion Add Common Parameters


        # Now that we've got all of the dynamic parameters ready
        $DynamicParameterNames = $DynamicParameters.Keys -as [string[]]
        return $DynamicParameters # return them.
        #endregion Handle Input Dynamically
    }



    process {

        $in = $_
        $registerCmd = $null
        $registerParams = @{}
        $parameterCopy = @{}  + $PSBoundParameters
        if ($DebugPreference -ne 'silentlycontinue') {
            Write-Debug @"
Watch-Event:
Dynamic Parameters: $DynamicParameterNames
Bound   Parameters:
$($parameterCopy | Out-String)
"@
        }

        #region Run Event Source and Map Parameters
        if ($eventSource) { # If we have an Event Source, now's the time to run it.
            $eventSourceParameter = [Ordered]@{} + $PSBoundParameters # Copy whatever parameters we have
            foreach ($toRemove in 'Then','When','SourceIdentifier','MessageData','MaxTriggerCount') {
                $eventSourceParameter.Remove($toRemove)
            }            
            $eventSourceOutput = & $eventSource @eventSourceParameter # Then run the generator.
            $null = $PSBoundParameters.Remove('SourceIdentifier')

            if ($eventSourceOutput.MessageData) {
                $registerParams['MessageData'] = $eventSourceOutput.MessageData
            }
            $eventSourceMaxTriggerCount = $eventSourceOutput.MaxTriggerCount,$eventSourceOutput.Max,$eventSourceOutput.TriggerCount -as [int[]] -gt 0
            
            if ($eventSourceMaxTriggerCount) {
                $registerParams['MaxTriggerCount'] = $eventSourceMaxTriggerCount[0]
            }

            if (-not $eventSourceOutput) { # If it didn't output,
                # we're gonna assume it it's gonna by signal by name.
                # Set it up so that later code will subscribe to this SourceIdentifier.
                $PSBoundParameters["SourceIdentifier"] = $eventSource.Name -replace
                    '^@' -replace '\.event\.ps1$' -replace '\.ps1$'
            }
            elseif ($eventSourceOutput.SourceIdentifier)
            {

                # If the eventSource said what SourceIdentifier(s) it will send, we will listen.
                $PSBoundParameters["SourceIdentifier"] = $eventSourceOutput.SourceIdentifier
            } else {
                # Otherwise, let's see if the eventSource returned an eventName
                $eventName = $eventSourceOutput.EventName

                if (-not $eventName) { # If it didn't,
                    $eventName =
                        # Look at the generator script block's attibutes
                        foreach ($attr in $eventSource.ScriptBlock.Attributes) {
                            if ($attr.TypeId.Name -eq 'EventSourceAttribute') {
                                # Return any [Diagnostics.Tracing.EventSource(Name='Value')]
                                $attr.Name
                            }
                        }
                }


                if (-not $eventName) { # If we still don't have an event name.
                    # check the output for events.
                    $eventNames = @(foreach ($prop in $eventSourceOutput.psobject.members) {
                        if ($prop.MemberType -eq 'event') {
                            $prop.Name
                        }
                    })

                    # If there was more than one
                    if ($eventNames.Count -gt 1) {
                        # Error out (but output the generator's output, in case that helps).
                        $eventSourceOutput
                        Write-Error "Source produced an object with multiple events, but did not specify a '[Diagnostics.Tracing.EventSource(Name=)]'."
                        return
                    }


                    $eventName = $eventNames[0]
                }

                # Default the Register- command to Register-ObjectEvent.
                $registerCmd = $ExecutionContext.SessionState.InvokeCommand.GetCommand('Register-ObjectEvent','Cmdlet')
                $registerParams['InputObject']= $eventSourceOutput # Map the InputObject
                $registerParams['EventName']  = $eventName            # and the EventName.
            }
        }
        #endregion Run Event Source and Map Parameters

        #region Handle -SourceIdentifier and -InputObject
        if ($PSBoundParameters['SourceIdentifier']) { # If we have a -SourceIdentifier
            if ($PSBoundParameters['InputObject'] -and -not $eventSource) { # and an -InputObject (but not not an eventsource)
                # then the register command is Register-ObjectEvent.
                $registerCmd = $ExecutionContext.SessionState.InvokeCommand.GetCommand('Register-ObjectEvent','Cmdlet')

                # We map our -SourceIdentifier to Register-ObjectEvent's -EventName,
                $registerParams['EventName'] = $PSBoundParameters['SourceIdentifier']
                # and Register-ObjectEvent's InputObject to -InputObject
                $registerParams['InputObject'] = $PSBoundParameters['InputObject']
            }
            else # If we have a -SourceIdentifier, but no -InputObject
            {
                # the register command is Register-EngineEvent.
                $registerCmd = $ExecutionContext.SessionState.InvokeCommand.GetCommand('Register-EngineEvent','Cmdlet')
                # and we map our -SourceIdentifier parameter to Register-EngineEvent's -SourceIdentifier.
                $registerParams['SourceIdentifier'] = $PSBoundParameters['SourceIdentifier']
            }
        }
        #endregion Handle -SourceIdentifier and -InputObject

        #region Handle When and Then
        # Assign When and Then for simplicity.
        $Then = $PSBoundParameters['Then']
        $when = $PSBoundParameters['When']

        if ($When) { # If -When was provided
            if ($when -is [ScriptBlock]) { # and it was a script
                # Rewrite -Then to include -When (this prevents debugging).
                # Run -When in a subexpression so it can return from the event handler (not itself)
                $then = [ScriptBlock]::Create(@"
`$shouldHandle = `$(
    $when
)
if (-not `$shouldHandle) { return }
$then
"@)
            }
        }

        if ("$then" -replace '\s') { # If -Then is not blank.
            $registerParams["Action"] = $Then # this maps to the -Action parameter the Register- comamnd.
        }
        #endregion Handle When and Then

        #region Handle MaxTriggerCount and MessageData
        if ($parameterCopy['MaxTriggerCount']) {
            $registerParams['MaxTriggerCount'] = $parameterCopy['MaxTriggerCount']
        }

        if ($parameterCopy['MessageData']) {
            $registerParams['MessageData'] = $parameterCopy['MessageData']
        }
        #endregion

        #region Subscribe to Event

        # Now we create the event subscription.
        $eventSubscription =


            # If there's a Register- command.
            if ($registerCmd) {
                if ($registerParams["EventName"]) { # and we have -EventName
                    $evtNames = $registerParams["EventName"]
                    $registerParams.Remove('EventName')

                    # Call Register-Object event once
                    foreach ($evtName in $evtNames) { # for each event name (
                        # give it a logical SourceIdentifier.
                        $sourceId = $registerParams["InputObject"].GetType().FullName + ".$evtName"
                        $existingSubscribers = @(Get-EventSubscriber -SourceIdentifier "${sourceID}*")
                        if ($existingSubscribers) { # (If subscribers exist, increment the source ID))
                            $maxSourceId = 0
                            foreach ($es in $existingSubscribers) {
                                if ($es.SourceIdentifier -match '\.\d+$') {
                                    $esId = [int]($matches.0 -replace '\.')
                                    if ($esId -gt $maxSourceId) {
                                        $maxSourceId = $esId
                                    }
                                }
                            }
                            $sourceID = $sourceId + ".$($maxSourceId + 1)"
                        }

                        # Then call Register-ObjectEvent
                        & $registerCmd @registerParams -EventName $evtName -SourceIdentifier $sourceId
                    }
                }
                elseif ($registerParams["SourceIdentifier"])  #
                {
                    $sourceIdList = $registerParams["SourceIdentifier"]
                    $null = $registerParams.Remove('SourceIdentifier')
                    # If we don't have an action, don't run anything (this will let the events "bubble up" to the runspace).
                    if ($registerParams.Action) {
                        # If we do have an action, call Register-Engine event with each source identifier.
                        foreach ($sourceId in $sourceIdList) {
                            & $registerCmd @registerParams -SourceIdentifier $sourceId
                        }
                    }
                }
            }
        #endregion Subscribe to Event


        #region Keep track of Subscriptions by EventSource
        # Before we're done, let's track what we subscribed to.

        if ($eventSource) {
            # Make sure a cache exists.
            if (-not $script:SubscriptionsByEventSource) {
                $script:SubscriptionsByEventSource = @{}
            }
            $eventSourceKey = # Then, if the event source was a script,
                if ($eventSource -is [Management.Automation.ExternalScriptInfo]) {
                    $eventSource.Path # the key is the path.
                } elseif ($eventSource.Module) { # If it was from a module
                    $eventSource.Module.ToString() + '\' + $eventSource.Name # it's the module qualified name.
                } else {
                    $eventSource.Name # Otherwise, it's just the function name.
                }
            $script:SubscriptionsByEventSource[$eventSourceKey] =
                if ($eventSubscription -is [Management.Automation.Job]) {
                    Get-EventSubscriber -SourceIdentifier $eventSubscription.Name -ErrorAction SilentlyContinue
                } else {
                    $eventSubscription
                }

            $eventSourceInitializeAttribute= $eventSource.ScriptBlock.Attributes |
                Where-Object TypeID -EQ ([ComponentModel.InitializationEventAttribute])
            if ($eventSourceOutput.InitializeEvent -and $eventSourceOutput.InitializeEvent -is [string]) {
                $eventSourceOutput.$($eventSourceOutput.InitializeEvent).Invoke()
            }
            elseif ($eventSourceOutput.InitializeEvent -and $eventSourceOutput.InitializeEvent -is [ScriptBlock]) {
                $this = $sender = $eventSourceOutput
                & ([ScriptBlock]::Create($eventSourceInitializeAttribute.EventName))
            }
            elseif ($eventSourceInitializeAttribute.EventName -match '^[\w\-]+$') {
                $eventSourceOutput.($eventSourceInitializeAttribute.EventName).Invoke()
            } else {
                $this = $sender = $eventSourceOutput
                & ([ScriptBlock]::Create($eventSourceInitializeAttribute.EventName))
            }
        }

        #endregion Keep track of Subscription


        #region Passthru if needed
        if ($myInv.PipelinePosition -lt $myInv.PipelineLength) { # If this is not the last step of the pipeline
            $in # pass down the original object.  (This would let one set of arguments pipe to multiple calls)
        }
        else {

        }
        #endregion Passthru if needed
    }
}