functions/flowcontrol/Register-PSFCallback.ps1

function Register-PSFCallback
{
<#
    .SYNOPSIS
        Registers a scriptblock to execute when a command calls Invoke-PSFCallback.
     
    .DESCRIPTION
        Registers a scriptblock to execute when a command calls Invoke-PSFCallback.
        The basic concept of this feature is for a module to offer a registration point,
        where foreign modules - even those unknown to the implementing module - can register
        scriptblocks as delegates. These will then be executed in the implementing module's commands,
        where those call Invoke-PSFCallback.
     
        When designing a callback, keep in mind, that it will be executed on all applicable commmands.
        A major aspect to consider here is the execution time, as this will get added on top of each applicable execution.
     
    .PARAMETER Name
        Name of the callback.
        Must be unique.
     
    .PARAMETER ModuleName
        The name of the module from which Invoke-PSFCallback is being called.
     
    .PARAMETER CommandName
        Name of the command calling Invoke-PSFCallback.
        Allows wildcard matching.
     
    .PARAMETER ScriptBlock
        The scriptblock to execute as callback action.
        This scriptblock will receive a single argument: A hashtable.
        That hashtable will contain the following keys:
        - Command: Name of the command calling Invoke-PSFCallback
        - ModuleName: Name of the module the command calling Invoke-PSFCallback is part of.
        - CallerFunction: Name of the command calling the command calling Invoke-PSFCallback
        - CallerModule: Name of the module of the command calling the command calling Invoke-PSFCallback
        - Data: Additional data specified by the command calling Invoke-PSFCallback
     
    .PARAMETER Scope
        Whether the callback script is valid in this runspace only (default) or process-wide.
     
    .PARAMETER BreakAffinity
        By default, the callback scriptblock is being executed in the runspace that defined it.
        Setting this parameter, the callback scriptblock is instead being executed in whatever
        runspace it is being triggered from.
     
    .EXAMPLE
        PS C:\> Register-PSFCallback -Name 'MyModule.Configuration' -ModuleName 'DomainManagement' -CommandName '*' -ScriptBlock $ScriptBlock
     
        Defines a callback named 'MyModule.Configuration'.
        This callback scriptblock will be triggered from all commands of the DomainManagement module,
        however only from the current runspace.
#>

    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)]
        [string]
        $Name,
        
        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)]
        [string]
        $ModuleName,
        
        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)]
        [string]
        $CommandName,
        
        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)]
        [scriptblock]
        $ScriptBlock,
        
        [Parameter(ValueFromPipelineByPropertyName = $true)]
        [ValidateSet('CurrentRunspace', 'Process')]
        [string]
        $Scope = 'CurrentRunspace',
        
        [Parameter(ValueFromPipelineByPropertyName = $true)]
        [switch]
        $BreakAffinity
    )
    
    process
    {
        $callback = New-Object PSFramework.Flowcontrol.Callback -Property @{
            Name          = $Name
            ModuleName    = $ModuleName
            CommandName   = $CommandName
            BreakAffinity = $BreakAffinity
            ScriptBlock   = $ScriptBlock
        }
        if ($Scope -eq 'CurrentRunspace') { $callback.Runspace = [System.Management.Automation.Runspaces.Runspace]::DefaultRunspace.InstanceId }
        [PSFramework.FlowControl.CallbackHost]::Add($callback)
    }
}