< Back
Register-PSFTaskEngineTask
Post
NAME Register-PSFTaskEngineTask
SYNOPSIS
Allows scheduling PowerShell tasks, that are perfomed in the background.
SYNTAX
Register-PSFTaskEngineTask -Name <String> [-Description <String>] -ScriptBlock <ScriptBlock> -Once [-Delay
<TimeSpanParameter>] [-Priority {Trivial | Low | Medium | High | Critical}] [-ResetTask] [-EnableException]
[<CommonParameters>]
Register-PSFTaskEngineTask -Name <String> [-Description <String>] -ScriptBlock <ScriptBlock> -Interval
<TimeSpanParameter> [-Delay <TimeSpanParameter>] [-Priority {Trivial | Low | Medium | High | Critical}]
[-ResetTask] [-EnableException] [<CommonParameters>]
DESCRIPTION
Allows scheduling PowerShell tasks, that are perfomed in the background.
All scriptblocks scheduled like this will be performed on a separate runspace.
None of the scriptblocks will affect the main session (so you cannot manipulate variables, etc.)
This system is designed for two use-cases:
- Reducing module import time by off-loading expensive one-time actions (such as building a cache) in the
background
- Scheduling periodic script executions that should occur while the process is running (e.g.: continuous
maintenance, cache updates, ...)
It also avoids overloading the client computer by executing too many tasks at the same time, as multiple modules
running code in the background might.
Instead tasks that are due simultaneously are processed by priority.
PARAMETERS
-Name <String>
The name of the task.
Must be unique, otherwise it will update the existing task.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Description <String>
Description of the task.
Helps documenting the task and what it is supposed to be doing.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ScriptBlock <ScriptBlock>
The task/scriptblock that should be performed as a background task.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Once [<SwitchParameter>]
Whether the task should be performed only once.
Required? true
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-Interval <TimeSpanParameter>
The interval at which the task should be repeated.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Delay <TimeSpanParameter>
How far after the initial registration should the task script wait before processing this.
This can be used to delay background stuff that should not content with items that would be good to have as
part of the module import.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Priority
How important is this task?
If multiple tasks are due at the same maintenance cycle, the more critical one will be processed first.
Required? false
Position? named
Default value Medium
Accept pipeline input? false
Accept wildcard characters? false
-ResetTask [<SwitchParameter>]
If the task already exists, it will be reset by setting this parameter (this switch is ignored when creating
new tasks).
This allows explicitly registering tasks for re-execution, even though they were set to execute once only.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-EnableException [<SwitchParameter>]
This parameters disables user-friendly warnings and enables the throwing of exceptions.
This is less user friendly, but allows catching exceptions in calling scripts.
Required? false
Position? named
Default value False
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-PSFTaskEngineTask -Name 'mymodule.buildcache' -ScriptBlock $ScriptBlock -Once -Description 'Builds
the object cache used by the mymodule module'
Registers the task contained in $ScriptBlock under the name 'mymodule.buildcache' to execute once at the system's
earliest convenience in a medium (default) priority.
-------------------------- EXAMPLE 2 --------------------------
PS C:\\>Register-PSFTaskEngineTask -Name 'mymodule.maintenance' -ScriptBlock $ScriptBlock -Interval "00:05:00"
-Delay "00:01:00" -Priority Critical -Description 'Performs critical system maintenance in order for the mymodule
module to function'
Registers the task contained in $ScriptBlock under the name 'mymodule.maintenance'
- Sets it to execute every 5 minutes
- Sets it to wait for 1 minute after registration before starting the first execution
- Sets it to priority "Critical", ensuring it takes precedence over most other tasks.
RELATED LINKS
SYNOPSIS
Allows scheduling PowerShell tasks, that are perfomed in the background.
SYNTAX
Register-PSFTaskEngineTask -Name <String> [-Description <String>] -ScriptBlock <ScriptBlock> -Once [-Delay
<TimeSpanParameter>] [-Priority {Trivial | Low | Medium | High | Critical}] [-ResetTask] [-EnableException]
[<CommonParameters>]
Register-PSFTaskEngineTask -Name <String> [-Description <String>] -ScriptBlock <ScriptBlock> -Interval
<TimeSpanParameter> [-Delay <TimeSpanParameter>] [-Priority {Trivial | Low | Medium | High | Critical}]
[-ResetTask] [-EnableException] [<CommonParameters>]
DESCRIPTION
Allows scheduling PowerShell tasks, that are perfomed in the background.
All scriptblocks scheduled like this will be performed on a separate runspace.
None of the scriptblocks will affect the main session (so you cannot manipulate variables, etc.)
This system is designed for two use-cases:
- Reducing module import time by off-loading expensive one-time actions (such as building a cache) in the
background
- Scheduling periodic script executions that should occur while the process is running (e.g.: continuous
maintenance, cache updates, ...)
It also avoids overloading the client computer by executing too many tasks at the same time, as multiple modules
running code in the background might.
Instead tasks that are due simultaneously are processed by priority.
PARAMETERS
-Name <String>
The name of the task.
Must be unique, otherwise it will update the existing task.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Description <String>
Description of the task.
Helps documenting the task and what it is supposed to be doing.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ScriptBlock <ScriptBlock>
The task/scriptblock that should be performed as a background task.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Once [<SwitchParameter>]
Whether the task should be performed only once.
Required? true
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-Interval <TimeSpanParameter>
The interval at which the task should be repeated.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Delay <TimeSpanParameter>
How far after the initial registration should the task script wait before processing this.
This can be used to delay background stuff that should not content with items that would be good to have as
part of the module import.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Priority
How important is this task?
If multiple tasks are due at the same maintenance cycle, the more critical one will be processed first.
Required? false
Position? named
Default value Medium
Accept pipeline input? false
Accept wildcard characters? false
-ResetTask [<SwitchParameter>]
If the task already exists, it will be reset by setting this parameter (this switch is ignored when creating
new tasks).
This allows explicitly registering tasks for re-execution, even though they were set to execute once only.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-EnableException [<SwitchParameter>]
This parameters disables user-friendly warnings and enables the throwing of exceptions.
This is less user friendly, but allows catching exceptions in calling scripts.
Required? false
Position? named
Default value False
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-PSFTaskEngineTask -Name 'mymodule.buildcache' -ScriptBlock $ScriptBlock -Once -Description 'Builds
the object cache used by the mymodule module'
Registers the task contained in $ScriptBlock under the name 'mymodule.buildcache' to execute once at the system's
earliest convenience in a medium (default) priority.
-------------------------- EXAMPLE 2 --------------------------
PS C:\\>Register-PSFTaskEngineTask -Name 'mymodule.maintenance' -ScriptBlock $ScriptBlock -Interval "00:05:00"
-Delay "00:01:00" -Priority Critical -Description 'Performs critical system maintenance in order for the mymodule
module to function'
Registers the task contained in $ScriptBlock under the name 'mymodule.maintenance'
- Sets it to execute every 5 minutes
- Sets it to wait for 1 minute after registration before starting the first execution
- Sets it to priority "Critical", ensuring it takes precedence over most other tasks.
RELATED LINKS