Table of Contents

Upgrading

All SharpTicker.* packages share one version number. Update them together.

None of the release notes so far asks for a schema migration: the EF Core schema and the MongoDB collections and indexes are those of 1.0.0, and the Redis store only gained keys. Releases did change what is done with stored rows (1.3.0 stores each chain child on Redis as a record of its own, 1.3.1 deletes copies of a seeded cron, 1.4.0 decides chain children that were left Idle, 1.5.0 reads the Redis records a version before 1.3.0 left) and they changed behaviour. Every release lists that in its notes.

This page points to those notes and names what needs a decision or a step from you. It is a summary; the release notes are the source.

Before you upgrade

  • Read the notes of every release between the version you run and the one you install, not only the last one.

  • Upgrade all instances together where you can. An instance of an earlier version behaves as that version did, so what a newer release changed does not apply to the jobs it runs.

  • Coming from a version before 1.3.0: upgrade all instances together, and do not go back below 1.3.0 once chains were added on the new version.

  • Coming from a version before 1.3.0 with Redis as the job store, two kinds of stored jobs did not carry over in a run that went from 1.2.3 to 1.4.0:

    • Time jobs that 1.2.3 had picked up were InProgress without having run, and stayed so on 1.4.0 under the same NodeIdentifier. Its log has Failed to deserialize JSON payload as TimeTickerEntity for them. A build with the fix for #144, which is in 1.5.0, read these rows in a run from 1.2.3: started under the same NodeIdentifier, it released them, and each ran once, late.
    • A chain stored by that version keeps its children inside the parent's record. On 1.4.0 the parent ran, and its children were not started. A build with the fix for #145, which is in 1.5.0, writes the children and grandchildren of such a chain as records of their own when it takes the parent to run it. In a run from 1.2.3 with that build, the children of the three stored chains then ran once each after their parents, by their run conditions, and the ones whose condition did not match were recorded as Skipped. What to know about it:
      • It applies to chains whose parent has not run yet. A chain whose parent already ended, on the earlier version or on 1.4.0, is left as it is, and its children are not run.
      • A child with a time of its own waits for that time from then on. A version before 1.3.0 ran it right after its parent.
      • An instance on 1.4.0 that takes such a parent still runs it without its children, so upgrade all instances together.
      • Updating a chain whose parent already ended (UpdateAsync, or saving it in the dashboard) wrote its children as records of their own up to 1.5.0; in a test, the fallback then ran the ones the parent's outcome lets run. Up to 1.5.0, delete such a chain instead of updating it when its children should not run. From 1.5.1 (#152) the update changes the parent's record only: the children stay inside it and are not run, and what the update carries for them is not stored.

    Look for both before the upgrade. On 1.4.0, delete such jobs and add them again afterwards. With the fix for #144, which is in 1.5.0, the InProgress time jobs ran after the upgrade in that run, so delete the ones that should not run any more. With the fix for #145, also in 1.5.0, the same holds for chains whose parent has not run yet: their children run after the upgrade, so delete the chains that should not run. A chain whose parent already ended still has to be deleted and added again for its children to run. See Scheduling.

  • A Redis store that was ever used by a version before 1.3.0 can still hold such InProgress time jobs, also when it has been on 1.3.x or 1.4.0 since. From 1.5.0 (#144) they are released when the instance starts under the NodeIdentifier that holds them, and run then, however old they are. Look for time jobs that are InProgress with no instance running them, and delete the ones that should not run.

  • With Redis as the job store and a ticker type of your own that has a collection property (#146):

    • Up to 1.4.0, a time job whose collection was empty was claimed and not handed out. It stayed held by its instance, mostly as InProgress.
    • Up to 1.4.0, an occurrence of a cron type whose collection is empty in a new instance of the type (for example List<string> Tags = []) ran while its outcome was not stored, and stayed InProgress. This does not depend on what the stored cron ticker holds, so it applies to every occurrence of such a type. The log of that version has Failed to deserialize warnings for them.
    • From 1.5.0 (#146) these records are read. An instance that starts under the NodeIdentifier that holds them, or another instance that finds their instance stopped, releases them, and they run then: the time jobs late, and every such occurrence still in the store one more time although it ran before, all of them together.
    • Before upgrading, delete the ones that should not run. A version up to 1.4.0 does not list these records, in its reads or in the dashboard, so look in Redis: the keys tq:tt:<id> (time jobs) and tq:co:<id> (occurrences) whose value has "Status":2, with no instance running them. Delete the key and take its id out of the index keys: tq:tt:ids and tq:tt:pending for a time job; tq:co:ids, tq:co:pending and tq:cron:<cron id>:occurrences for an occurrence.
  • With Redis as the job store, from 1.5.0 (#46): a node that cannot write its heartbeat for one heartbeat TTL (80 seconds with the default interval) asks its running jobs to stop, and they run again later. This also happens in a Redis outage that every instance sees, where the jobs ran on before. Check that your jobs honour their cancellation token and are safe to run twice. Jobs that must not be interrupted that way need StopJobsWhenHeartbeatIsLost = false; see When an instance stops.

  • A cron that takes its expression from configuration (%Key%), from 1.5.0 (#79): a value with five fields gets the seconds field, so a job that never ran up to 1.4.0 starts to run after the upgrade. A value that is not a cron expression, one of blanks only included, stops the startup with an error that names the function, the configuration key and the value; up to 1.4.0 the application started and the job never ran. Check the configured values before the upgrade. A key that is missing or empty is handled as before.

  • With the EF Core store and Redis next to it, from 1.5.0 (#93): the list of cron expressions kept in Redis is cleared when the crons defined in code are seeded at startup, and ends ten minutes after it was read. An entry written by 1.4.0 or earlier has no end. The first start on the new build clears it; if Redis does not answer at that moment (a warning in the log says so) or the application does not seed (IgnoreSeedDefinedCronTickers), it stays until a cron is added, changed or removed. An instance that still runs the earlier version writes the entry again without an end, so upgrade all instances together. After the upgrade a cron whose expression was changed in code runs on its new schedule, which it did not up to 1.4.0.

  • With the EF Core store on net8.0, from 1.5.0 (#91): SharpTicker.EntityFrameworkCore asks for FlexLabs.EntityFrameworkCore.Upsert 8.1.2 or later, where it asked for 8.0.0 or later. A project that pins that package below 8.1.2 gets a restore error until the pin is raised. With 8.1.2 the crons run on the official MySQL provider (MySql.EntityFrameworkCore) on net8.0, where they did not run up to 1.4.0; see Storage for the providers the tests run on.

  • With the EF Core store and no Redis, from 1.5.0 (#24): a starting instance writes one Information entry that names the other node identifiers holding jobs that are InProgress (the ten with the most such jobs, each with its count, and how many more names there are). Nothing is released by it. A job held under a name no instance starts with again stays InProgress, as before; see When an instance stops for what a stable name is and what to do with such a job.

  • With Redis as the job store and a ticker type of your own, from 1.5.0 (#162): such an application can add its jobs and they run, without a JsonSerializerContext and with a source-generated one. Up to 1.4.0 adding a job failed without a context, and with one the scheduler loop and the fallback failed on reading the jobs. The limits that remain for such types (empty collections, values of abstract types; numbers with more than 14 digits up to 1.5.1) are in Storage.

  • With Redis as the job store, from 1.5.0 (#176): a time job that is added or changed shortly before it is due is started at its time. Up to 1.4.0 the scheduler loop did not take such a job when the last digit of its UpdatedAt was a zero, which is about one job in ten and every one with a clock that gives whole milliseconds; the fallback started it, up to FallbackIntervalChecker (30 seconds by default) after its time, and it ended DueDone. There is no step to take. Jobs start earlier than they did, and fewer end DueDone.

  • A delayed chain child or grandchild whose time is given as DateTimeKind.Local or Unspecified, from 1.5.2 (#81): its time is converted to UTC like the root's (Unspecified read in the scheduler time zone), and through the dashboard API a timeZoneId applies to every time of the chain. Up to 1.5.1 it was stored as given, so on a machine not on UTC such a child ran hours off. Times already stored are not changed. A caller that built an Unspecified value meaning UTC on such a machine now gets it shifted, as the root's always was.

  • A chain child that starts with its parent (RunCondition.InProgress, no time of its own) and still waits after its parent ended, from 1.5.2 (#158): the fallback runs it when the parent started (Done, DueDone, Failed, Cancelled) and records it Skipped only when the parent was skipped. Up to 1.5.1 it was always Skipped, also when its run had been interrupted by a stopped node. A child 1.5.1 already recorded as Skipped stays so; nothing is run again for it.

  • With Redis as the job store, from 1.5.2 (#151): claims, releases and skips write a record with the serializer that wrote it, so a number of 15 digits or more in a ticker type of your own is kept and the job runs. Upgrade all instances together: an instance still on 1.5.1 rewrites a record when it claims it. A record 1.5.1 already wrote back in exponent form is not repaired; it is named in a warning with its key, so delete or update that job. A record that cannot be read is no longer taken by the fallback and left InProgress; it stays as it is and is named on each read.

  • A cron whose expression matches no date (such as 0 0 0 30 2 *), from 1.5.2 (#194): the scheduler skips it and plans the other jobs, and adding or updating one is refused. Up to 1.5.1 such a cron ticker, which WithCron in code accepts, made the scheduler loop fail on every pass, so no job started on time while it was stored. From 1.5.2 (#79) each enabled cron ticker whose expression has no next occurrence is named in a Warning at startup; correct or remove it.

  • With the EF Core store, from 1.6.0 (#24): a new option, SetInProgressLease(TimeSpan), is on by default with 5 minutes. A running instance renews the lock of its InProgress jobs, and releases the InProgress jobs of other instance names whose lock was not renewed for the lease, so that they run again; see Storage and When an instance stops. Up to 1.5.2 such a job stayed InProgress until an instance started under the name that held it. What to know about it:

    • At the first pass after the upgrade, about a minute after the start, every job that is InProgress under a name no running instance renews is released and runs again, however old it is: jobs left by replaced containers or pods can be weeks old. A chain child waiting for such a job follows by its run condition. This includes cron occurrences, which run late.
    • Look for these jobs before the upgrade. The startup log of 1.5.0 and later names the instance names that hold them (Information, category SharpTicker.EntityFrameworkCore.StartupRelease). In the database they are the rows with Status 2 (InProgress) in TimeTickers and CronTickerOccurrences, with their LockHolder and LockedAt. Delete the ones that should not run (Force delete on the dashboard for a time job), or upgrade with SetInProgressLease(TimeSpan.Zero) and turn the lease on once they are dealt with.
    • Upgrade all instances together, and set the same lease on all of them, or turn it off on all of them. An instance of an earlier version, or one with the lease off, does not renew its locks, so an instance with the lease on releases the jobs it runs for longer than the lease, and they run twice. With different values, the shorter lease releases the jobs of the others earlier than their lease expects.
    • A row with no LockedAt or no lock holder is not released by the lease.
    • For a job that is InProgress, LockedAt and the dashboard's "Locked At" now show when the lock was last renewed.
  • With the EF Core store and UseSharpTickerDbContext, from 1.6.0 (#89): the EF Core tools find SharpTickerDbContext in the application's services, so dotnet ef migrations add works in a project that has no migrations for it yet. In a project that also registers a context of its own (AddDbContext<AppDbContext>) and has no migrations for SharpTickerDbContext, the tools picked the application's context up to 1.5.2 when no --context was given; now they find both and stop with More than one DbContext was found. Scripts that run dotnet ef database update, dotnet ef migrations script or dotnet ef migrations bundle without --context in such a project need --context AppDbContext after the upgrade.

  • Dashboard with a custom ITickerPersistenceProvider, from 1.6.0 (#96): the status charts, the statistics and the jobs per node count through TimeTickersQuery() and CronTickerOccurrencesQuery() with Where and CountAsync. A provider whose query objects throw makes /time-tickers/graph-data, /cron-tickers/graph-data, /ticker/statuses/get and /ticker/machine/jobs fail; up to 1.5.2 these read the rows through GetTimeTickers and GetAllCronTickerOccurrences.

  • Dashboard, from 1.6.0 (#31): the Machines panel is called Lock holders. The answer of /ticker/machine/jobs is ordered by the latest lock of each name, latest first, where up to 1.5.2 it was ordered by the number of jobs. It keeps item1 (the name) and item2 (the number of jobs) and adds lastLockedAt (the latest lock, in UTC) and hasHeartbeat (with Redis whether the node has a heartbeat entry, otherwise null). A script that relies on the old order can sort by item2 itself.

Release by release

Version What its notes ask you to look at Step
1.1.0 Source generator diagnostics are ST001 to ST011 (were TQ001 to TQ011). A cron with a backwards range such as 22-2 is refused when added or updated. Updating a ticker that does not exist fails on every store. How a cancelled job and a timed-out HTTP call inside a job are recorded. At a stop, the scheduler waits for running jobs. Update NoWarn, .editorconfig and #pragma lines that name the old diagnostic ids.
1.2.0 The priority on [TickerFunction] takes effect. Dashboard: status of a chain, columns, wording, statistics. None.
1.2.1, 1.2.2, 1.2.3 Fixes; their notes list no behaviour change to check. None.
1.3.0 On EF Core and MongoDB, the chain rules also apply to rows stored before the upgrade. An inline child is InProgress while it runs. UpdatedAt of a running job holds its claim marker. An ended job is not run again by saving it. Filters on DueDone see fewer rows. Custom persistence providers keep the behaviour of 1.2.3 for the fenced writes. Redis stores each chain child as a record of its own. Upgrade all instances together. Do not go back to 1.2.3 or earlier once chains exist. With Redis as the job store, give every running instance its own NodeIdentifier: an instance that starts now releases what an earlier run under its name left locked.
1.3.1 Stored copies of a cron seeded from code are deleted at the first start, with their occurrence history; one of them stays. A chain child without a registered function ends Failed. UpdateAsync keeps the parent of a stored child. None.
1.4.0 Chain children without a time that earlier versions left Idle after their parent ended are run or skipped by the first fallback pass, however old they are; one that runs ends DueDone. Some log texts changed. Redis keeps one more key, tq:tt:waiting-children. Before upgrading, delete the Idle children you do not want to run.
1.5.0 Redis as the job store: a node that cannot write its heartbeat for one heartbeat TTL stops its jobs and they run again (#46); an application's own ticker types work (#162); records a version before 1.3.0 left are read (#144, #145, #146, #150); a job added shortly before it is due starts at its time (#176). A cron from configuration with five fields runs, and a value that is not a cron expression stops the startup (#79). EF Core with Redis: the cached cron list follows the seed (#93). EF Core on net8.0 asks for FlexLabs.EntityFrameworkCore.Upsert 8.1.2 or later (#91). EF Core without Redis: a starting instance logs the other node names that hold InProgress jobs (#24). Check that jobs honour their cancellation token and are safe to run twice, or set StopJobsWhenHeartbeatIsLost = false. Check configured cron values. Raise a pin of the upsert package below 8.1.2. Upgrade all instances together. Delete stored jobs that should not run (see "Before you upgrade").
1.5.1 Redis as the job store: an update of a chain stored before 1.3.0 whose parent already ended changes the parent's record only; its children stay inside it and are not run (#152). A job added while the scheduler loop reads its next plan (#78), and, with EF Core or MongoDB and the Redis heartbeat, a job waiting while a stopped node is released (#90), starts at its time where it could start up to FallbackIntervalChecker late and end DueDone. None.
1.5.2 Times of delayed chain children are converted to UTC like the root's (#81). A chain child that starts with its parent and was left waiting runs when its parent started, where it was Skipped (#158). Redis as the job store: numbers of 15 digits or more in a ticker type of your own are kept (#151). A cron whose expression matches no date no longer stops the scheduler loop, and is refused when added (#194). A stored cron ticker that never runs is named in a Warning at startup (#79). Check delayed child times given as Local or Unspecified. With Redis, upgrade all instances together and delete or update records named as unreadable. Correct or remove cron tickers named in the startup warning.
1.6.0 EF Core: a new option, SetInProgressLease(TimeSpan), on by default with 5 minutes: a running instance releases the InProgress jobs of other instance names whose lock was not renewed for the lease, and they run again; at the first pass after the upgrade this includes old jobs of replaced containers or pods (#24). EF Core with UseSharpTickerDbContext: dotnet ef finds SharpTickerDbContext, and in a project that also registers a context of its own it needs --context (#89). Dashboard: lists, add and update work with ticker types of your own and show their public properties (#95); the status counts are counted by the store (#96); the Machines panel is called Lock holders, and /ticker/machine/jobs is ordered by the latest lock and has two more fields (#31). A ticker added after UseSharpTicker and before the host starts finds its function (#75). Before upgrading, look for InProgress jobs under names no instance runs and delete the ones that should not run, or upgrade with the lease off. Upgrade all instances together, with the same lease. Add --context to dotnet ef commands in a project with a context of its own.
1.6.1 Redis as the job store, chains stored before 1.3.0: when the fallback or run-now of an instance takes such a parent while the scheduling loop of the same instance writes its children as records, the parent runs with the children written by then, where up to 1.6.0 it could run with only those written before it read them (#154); a delete of such a chain while its children are written as records removes those records as well (#153). Upgrade all instances together, as before.

Coming from the project SharpTicker was forked from: see the migration guide.