Main | Contact | Blog | Documentation

PowerShell Framework

The project dedicated to empowering your PowerShell scripting.

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 <MessageLevel[]>] [-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:

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.

EXAMPLES

EXAMPLE 1

Register-PSFMessageEvent -Name 'Mymodule.OffloadTrigger' -ScriptBlock $ScriptBlock -Tag 'engine' -Module 'MyModule' -Level Warning

Registers an event subscription …

PARAMETERS

-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.

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ScriptBlock

The scriptblock to execute. It will receive the message entry (as returned by Get-PSFMessage) as its sole argument.

Type: ScriptBlock
Parameter Sets: (All)
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-MessageFilter

Filter by message content. Understands wildcards, but not regex.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ModuleNameFilter

Filter by Name of the module, from which the message comes. Understands wildcards, but not regex.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-FunctionNameFilter

Filter by Name of the function, from which the message comes. Understands wildcards, but not regex.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-TargetFilter

Filter by target object. Performs equality comparison on an object level.

Type: Object
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-LevelFilter

Include only messages of the specified levels.

Type: MessageLevel[]
Parameter Sets: (All)
Aliases:
Accepted values: Critical, Important, Output, Host, Significant, VeryVerbose, Verbose, SomewhatVerbose, System, Debug, InternalComment, Warning, Error

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-TagFilter

Only include messages with any of the specified tags.

Type: String[]
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-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

Type: Guid
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

OUTPUTS

NOTES