functions/message/Register-PSFMessageEvent.ps1
|
function Register-PSFMessageEvent { <# .SYNOPSIS Registers an event to when a message is written. .DESCRIPTION Registers an event to when a message is written. These events will fire whenever the written message fulfills the specified filter criteria. This allows integrating direct alerts and reactions to messages as they occur. Warnings: - Adding many subscriptions can impact overall performance, even without triggering. - Events are executed synchronously. executing complex operations may introduce a significant delay to the command execution. It is recommended to push processing that involves outside resources to a separate runspace, then use the event to pass the object as trigger. The TaskEngine component may prove to be just what is needed to accomplish this. .PARAMETER Name The name of the subscription. Each subscription must have a name, subscriptions of equal name will overwrite each other. This is in order to avoid having runspace uses explode the number of subscriptions on each invocation. .PARAMETER ScriptBlock The scriptblock to execute. It will receive the message entry (as returned by Get-PSFMessage) as its sole argument. .PARAMETER MessageFilter Filter by message content. Understands wildcards, but not regex. .PARAMETER ModuleNameFilter Filter by Name of the module, from which the message comes. Understands wildcards, but not regex. .PARAMETER FunctionNameFilter Filter by Name of the function, from which the message comes. Understands wildcards, but not regex. .PARAMETER TargetFilter Filter by target object. Performs equality comparison on an object level. .PARAMETER LevelFilter Include only messages of the specified levels. .PARAMETER TagFilter Only include messages with any of the specified tags. .PARAMETER RunspaceFilter Only include messages which were written by the specified runspace. You can find out the current runspace ID by running this: [System.Management.Automation.Runspaces.Runspace]::DefaultRunspace.InstanceId You can retrieve the primary runspace - the Guid used by the runspace the user sees - by running this: [PSFramework.Utility.UtilityHost]::PrimaryRunspace .EXAMPLE PS C:\> Register-PSFMessageEvent -Name 'Mymodule.OffloadTrigger' -ScriptBlock $ScriptBlock -Tag 'engine' -Module 'MyModule' -Level Warning Registers an event subscription ... - Under the name 'Mymodule.OffloadTrigger' ... - To execute $ScriptBlock ... - Whenever a message is written with the tag 'engine' by the module 'MyModule' at the level 'Warning' #> [CmdletBinding(PositionalBinding = $false, HelpUri = 'https://psframework.org/documentation/commands/PSFramework/Register-PSFMessageEvent')] Param ( [Parameter(Mandatory = $true)] [string] $Name, [Parameter(Mandatory = $true)] [System.Management.Automation.ScriptBlock] $ScriptBlock, [string] $MessageFilter, [string] $ModuleNameFilter, [string] $FunctionNameFilter, $TargetFilter, [PSFramework.Message.MessageLevel[]] $LevelFilter, [string[]] $TagFilter, [System.Guid] $RunspaceFilter ) $newName = $Name.ToLower() $eventSubscription = New-Object PSFramework.Message.MessageEventSubscription $eventSubscription.Name = $newName $eventSubscription.ScriptBlock = $ScriptBlock if (Test-PSFParameterBinding -ParameterName MessageFilter) { $eventSubscription.MessageFilter = $MessageFilter } if (Test-PSFParameterBinding -ParameterName ModuleNameFilter) { $eventSubscription.ModuleNameFilter = $ModuleNameFilter } if (Test-PSFParameterBinding -ParameterName FunctionNameFilter) { $eventSubscription.FunctionNameFilter = $FunctionNameFilter } if (Test-PSFParameterBinding -ParameterName TargetFilter) { $eventSubscription.TargetFilter = $TargetFilter } if (Test-PSFParameterBinding -ParameterName LevelFilter) { $eventSubscription.LevelFilter = $LevelFilter } if (Test-PSFParameterBinding -ParameterName TagFilter) { $eventSubscription.TagFilter = $TagFilter } if (Test-PSFParameterBinding -ParameterName RunspaceFilter) { $eventSubscription.RunspaceFilter = $RunspaceFilter } [PSFramework.Message.MessageHost]::Events[$newName] = $eventSubscription } |