< Back
Register-PSFMessageEvent
Post
NAME Register-PSFMessageEvent
SYNOPSIS
Registers an event to when a message is written.
SYNTAX
Register-PSFMessageEvent -Name <String> -ScriptBlock <ScriptBlock> [-MessageFilter <String>] [-ModuleNameFilter
<String>] [-FunctionNameFilter <String>] [-TargetFilter <Object>] [-LevelFilter {Critical | Important | Output |
Host | Significant | VeryVerbose | Verbose | SomewhatVerbose | System | Debug | InternalComment | Warning}]
[-TagFilter <String[]>] [-RunspaceFilter <Guid>] [<CommonParameters>]
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.
PARAMETERS
-Name <String>
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.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ScriptBlock <ScriptBlock>
The scriptblock to execute.
It will receive the message entry (as returned by Get-PSFMessage) as its sole argument.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-MessageFilter <String>
Filter by message content. Understands wildcards, but not regex.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ModuleNameFilter <String>
Filter by Name of the module, from which the message comes. Understands wildcards, but not regex.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-FunctionNameFilter <String>
Filter by Name of the function, from which the message comes. Understands wildcards, but not regex.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-TargetFilter <Object>
Filter by target object. Performs equality comparison on an object level.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-LevelFilter
Include only messages of the specified levels.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-TagFilter <String[]>
Only include messages with any of the specified tags.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-RunspaceFilter <Guid>
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
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, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
-------------------------- EXAMPLE 1 --------------------------
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'
RELATED LINKS
SYNOPSIS
Registers an event to when a message is written.
SYNTAX
Register-PSFMessageEvent -Name <String> -ScriptBlock <ScriptBlock> [-MessageFilter <String>] [-ModuleNameFilter
<String>] [-FunctionNameFilter <String>] [-TargetFilter <Object>] [-LevelFilter {Critical | Important | Output |
Host | Significant | VeryVerbose | Verbose | SomewhatVerbose | System | Debug | InternalComment | Warning}]
[-TagFilter <String[]>] [-RunspaceFilter <Guid>] [<CommonParameters>]
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.
PARAMETERS
-Name <String>
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.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ScriptBlock <ScriptBlock>
The scriptblock to execute.
It will receive the message entry (as returned by Get-PSFMessage) as its sole argument.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-MessageFilter <String>
Filter by message content. Understands wildcards, but not regex.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ModuleNameFilter <String>
Filter by Name of the module, from which the message comes. Understands wildcards, but not regex.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-FunctionNameFilter <String>
Filter by Name of the function, from which the message comes. Understands wildcards, but not regex.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-TargetFilter <Object>
Filter by target object. Performs equality comparison on an object level.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-LevelFilter
Include only messages of the specified levels.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-TagFilter <String[]>
Only include messages with any of the specified tags.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-RunspaceFilter <Guid>
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
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, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
-------------------------- EXAMPLE 1 --------------------------
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'
RELATED LINKS