TimerInfo.ScheduleStatus.Next does not indicate the next occurence

[Archomeda]

I've noticed with our timer triggered function, that the TimerInfo.ScheduleStatus.Next value always seems to be the current trigger time, and not the next. The documentation also says "Gets or sets the expected next schedule occurrence".

So I'm expecting the following when the cron is set to 0 */10 * * * *, and the function is triggered at 2022-07-01T09:30:00.0024370+00:00:

• Last: 7/1/2022 9:20:00 AM
• Next: 7/1/2022 9:40:00 AM

But instead I'm seeing the following:

• Last: 7/1/2022 9:20:00 AM
• Next: 7/1/2022 9:30:00 AM

Looking at this, for me last means the previous run, and next means the next run. In this case, I'm actually missing a current property.

The documentation seems to be very ambiguous in this regard. Can someone clarify what is intended here, and possibly update the documentation? Or, even better, consider adding Current and change Last to Previous.

[fabiocav]

We'll investigate this. It's likely this would be something with the way the trigger/host is passing this information to the worker, so the issue would need to be fixed there. We'll create the issues in the appropriate repos based on the results of our investigation.

[fabiocav]

Investigation on this is in progress. Moving to sprint 128 so we can continue to track.

[mathewc]

ScheduleStatus is a structure persisted to storage to aid in detection of past due schedule invocations. As the class xml doc says, Next is “the next schedule occurrence”. So on startup, if schedule monitoring is active, we’ll load the ScheduleStatus (code here) and use Next to determine how long to wait before the next invocation (Next - Now). Thus, when this duration expires, we’ll invoke the function and Next will equal Now.

So Next isn’t the next schedule time from the current invocation – it’s the value that was used to determine when to invoke the current invocation. The naming of the properties of ScheduleStatus are from the perspective of the scheduler, not from the perspective of the current invocation. This is by design, though I can appreciate why there may be some confusion.

If the goal is to determine the next expected invocation from the time of the current invocation, the schedule can be used as follows to determine that:

public static void CronJob([TimerTrigger("*/15 * * * * *")] TimerInfo timerInfo)
{
    var schedule = timerInfo.Schedule as CronSchedule;
    var next = schedule.GetNextOccurrence(DateTime.UtcNow);

    . . .
}

If this explanation isn't clear or if we keep getting customer confusion on this, we can consider updating the xml doc for these properties to clarify this.

[mathewc]

I have a PR Azure/azure-webjobs-sdk-extensions#797 with a proposed update - if this helps we can make it.

[mathewc]

Closing as by design, as per the above explanations. We've also made an update to the xml doc.