Skip to content

Schedules

A Schedule in Pode is a long-running async task, and unlike timers, when they trigger they are run in their own separate runspace - so they don't affect each other if they take a while to process. By default up to a maximum of 10 schedules can run concurrently, but this can be changed by using Set-PodeScheduleConcurrency.

Schedule triggers are defined using cron expressions, basic syntax is supported as well as some predefined expressions. Pode also has an inbuilt helper, New-PodeCron, to help with building cron expressions - as described here. Schedules can start immediately, have a delayed start time, and also have a defined end time.

Create a Schedule

You can create a new schedule using Add-PodeSchedule. To create a basic Schedule, the following example will work; this will trigger at '00:05' every Tuesday outputting the current date/time:

Add-PodeSchedule -Name 'date' -Cron '5 0 * * TUE' -ScriptBlock {
    Write-Host "$([DateTime]::Now)"
}

# or, using Pode's helper
$cron = New-PodeCron -Day Tuesday -Hour 0 -Minute 5

Add-PodeSchedule -Name 'date' -Cron $cron -ScriptBlock {
    Write-Host "$([DateTime]::Now)"
}

Whereas the following will create the same schedule, but will only trigger the schedule 4 times due to the -Limit value supplied:

Add-PodeSchedule -Name 'date' -Cron '5 0 * * TUE' -Limit 4 -ScriptBlock {
    Write-Host "$([DateTime]::Now)"
}

You can also supply multiple cron expressions for the same Schedule. For example, the following will trigger the same schedule every minute and every hour:

Add-PodeSchedule -Name 'date' -Cron @('@minutely', '@hourly') -ScriptBlock {
    Write-Host "$([DateTime]::Now)"
}

Usually all schedules are created within the main Start-PodeServer scope, however it is possible to create adhoc schedules with routes/etc. If you create adhoc schedules in this manner, you might notice that they don't run; this is because the Runspace that schedules use to run won't have been configured. You can configure by using -EnablePool on Start-PodeServer:

Start-PodeServer -EnablePool Schedules {
    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http

    Add-PodeRoute -Method Get -Path '/create-schedule' -ScriptBlock {
        Add-PodeSchedule -Name 'example' -Cron '@minutely' -ScriptBlock {
            # logic
        }
    }
}

Arguments

You can supply custom arguments to your schedules by using the -ArgumentList parameter. Unlike other features, for schedules the -ArgumentList is a hashtable; this is done because parameters to the -ScriptBlock are splatted in, and the parameter names are literal.

For example, the first parameter to a schedule is always $Event - this contains the .Lockable object. Other parameters come from any Key/Values contained with the optional -ArgumentList:

Add-PodeSchedule -Name 'date' -Cron '@minutely' -ArgumentList @{ Name = 'Rick'; Environment = 'Multiverse' } -ScriptBlock {
    param($Event, $Name, $Environment)
}

Important

In schedules, your scriptblock parameter names must be exact - including case-sensitivity. This is because the arguments are splatted into a runspace. If you pass in an argument called "Names", the param-block must have $Names exactly. Furthermore, the event parameter must be called $Event.

Delayed Start

The -StartTime <datetime> parameter will cause the Schedule to only be triggered after the date/time defined. For example, if you have a schedule set to trigger at 00:05 every Tuesday, and you pass -StartTime [DateTime]::Now.AddMonths(2), then the schedule will only start trigger on Tuesdays in 2 months time.

The following will create a Schedule that triggers at 16:00 every Friday, and is delayed by 1 year:

$start = [DateTime]::Now.AddYears(1)

Add-PodeSchedule -Name 'date' -Cron '0 16 * * FRI' -StartTime $start -ScriptBlock {
    Write-Host "$([DateTime]::Now)"
}

Defined End

The -EndTime <datetime> parameter will cause the Schedule to cease triggering after the date/time defined. For example, if you have a schedule set to trigger at 00:05 every Tuesday, and you pass -EndTime [DateTime]::Now.AddMonths(2), then the schedule will stop triggering in 2 months time.

The following will create a Schedule that triggers at 16:00 every Friday, and stops triggering in 1 year:

$end = [DateTime]::Now.AddYears(1)

Add-PodeSchedule -Name 'date' -Cron '0 16 * * FRI' -EndTime $end -ScriptBlock {
    Write-Host "$([DateTime]::Now)"
}

Script from File

You normally define a schedule's script using the -ScriptBlock parameter however, you can also reference a file with the required scriptblock using -FilePath. Using the -FilePath parameter will dot-source a scriptblock from the file, and set it as the schedule's script.

For example, to create a schedule from a file that will output Hello, world every minute:

  • File.ps1 

    {
    'Hello, world!' | Out-PodeHost
}

  • Schedule 

    Add-PodeSchedule -Name 'from-file' -Cron '@minutely' -FilePath './Schedules/File.ps1'

Getting Schedules

The Get-PodeSchedule helper function will allow you to retrieve a list of schedules configured within Pode. You can use it to retrieve all of the schedules, or supply filters to retrieve specific ones.

To retrieve all of the schedules, you can call the function will no parameters. To filter, here are some examples:

# one schedule by name
Get-PodeSchedule -Name Name1

# multiple schedules by name
Get-PodeSchedule -Name Name1, Name2

Getting Schedule Processes

You can retrieve a list of processes triggered by Schedules via Get-PodeScheduleProcess - this will return processes created either by a Schedule's natural time-based trigger, or via Invoke-PodeSchedule.

You can either retrieve all processes, or filter them by Schedule Name, or Process ID/Status:

# retrieves all schedule processes
Get-PodeScheduleProcess

# retrieves all schedule processes for the "ScheduleName" process
Get-PodeScheduleProcess -Name 'ScheduleName'

# retrieves the schedule process with ID "ScheduleId"
Get-PodeScheduleProcess -Id 'ScheduleId'

# retrieves all running schedule processes
Get-PodeScheduleProcess -State 'Running'

# retrieves all pending schedule processes for "ScheduleName"
Get-PodeScheduleProcess -Name 'ScheduleName' -State 'Running'

Next Trigger Time

When you retrieve a Schedule using Get-PodeSchedule, each Schedule object will already have its next trigger time as NextTriggerTime. However, if you want to get a trigger time further ino the future than this, then you can use the Get-PodeScheduleNextTrigger function.

This function takes the Name of a Schedule, as well as a custom DateTime and will return the next trigger time after that DateTime. If no DateTime is supplied, then the Schedule's StartTime is used (or the current time if no StartTime).

# just get the next time
$time = Get-PodeScheduleNextTrigger -Name Schedule1

# get the next time after a date
$time = Get-PodeScheduleTriggerTime -Name Schedule1 -DateTime [datetime]::new(2020, 3, 20)

Manual Trigger

You can manually trigger a schedule by using Invoke-PodeSchedule. This will run the schedule immediately, and will not count towards a schedule's run limit:

Invoke-PodeSchedule -Name 'schedule-name'

You can also pass further optional arguments that will be supplied to the schedules's scriptblock by using -ArgumentList, which is a hashtable of parameters that will be supplied:

Add-PodeSchedule -Name 'date' -Cron '@minutely' -ScriptBlock {
    param($Date)
    Write-Host $Date
}

Invoke-PodeSchedule -Name 'date' -ArgumentList @{ Date = [DateTime]::Now }

Note

Remember that names of items in the hashtable, and the name of the parameter in the scriptblock must be identical.

Schedule Object

Warning

Be careful if you choose to edit these objects, as they will affect the server.

The following is the structure of the Schedule object internally, as well as the object that is returned from Get-PodeSchedule:

Name Type Description
Name string The name of the Schedule
StartTime datetime The delayed start time of the Schedule
EndTime datetime The end time of the Schedule
Crons hashtable[] The cron expressions of the Schedule, but parsed into an internal format
CronsRaw string[] The raw cron expressions that were supplied
Limit int The number of times the Schedule should run - 0 if running infinitely
Count int The number of times the Schedule has run
LastTriggerTime datetime The datetime the Schedule was last triggered
NextTriggerTime datetime The datetime the Schedule will next be triggered
Script scriptblock The scriptblock of the Schedule
Arguments hashtable The arguments supplied from ArgumentList
OnStart bool Should the Schedule run once when the server is starting, or once the server has fully loaded
Completed bool Has the Schedule completed all of its runs