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
InProgresswithout having run, and stayed so on 1.4.0 under the sameNodeIdentifier. Its log hasFailed to deserialize JSON payload as TimeTickerEntityfor 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 sameNodeIdentifier, 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
InProgresstime 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.- Time jobs that 1.2.3 had picked up were
A Redis store that was ever used by a version before 1.3.0 can still hold such
InProgresstime 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 theNodeIdentifierthat holds them, and run then, however old they are. Look for time jobs that areInProgresswith 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 stayedInProgress. 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 hasFailed to deserializewarnings for them. - From 1.5.0 (#146) these records are read. An instance that starts under the
NodeIdentifierthat 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) andtq: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:idsandtq:tt:pendingfor a time job;tq:co:ids,tq:co:pendingandtq:cron:<cron id>:occurrencesfor an occurrence.
- 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
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.EntityFrameworkCoreasks forFlexLabs.EntityFrameworkCore.Upsert8.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 staysInProgress, 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
JsonSerializerContextand 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
UpdatedAtwas a zero, which is about one job in ten and every one with a clock that gives whole milliseconds; the fallback started it, up toFallbackIntervalChecker(30 seconds by default) after its time, and it endedDueDone. There is no step to take. Jobs start earlier than they did, and fewer endDueDone.A delayed chain child or grandchild whose time is given as
DateTimeKind.LocalorUnspecified, from 1.5.2 (#81): its time is converted to UTC like the root's (Unspecifiedread in the scheduler time zone), and through the dashboard API atimeZoneIdapplies 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 anUnspecifiedvalue 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 itSkippedonly when the parent was skipped. Up to 1.5.1 it was alwaysSkipped, also when its run had been interrupted by a stopped node. A child 1.5.1 already recorded asSkippedstays 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, whichWithCronin 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 itsInProgressjobs, and releases theInProgressjobs 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 stayedInProgressuntil 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
InProgressunder 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 withStatus2 (InProgress) inTimeTickersandCronTickerOccurrences, with theirLockHolderandLockedAt. Delete the ones that should not run (Force delete on the dashboard for a time job), or upgrade withSetInProgressLease(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
LockedAtor no lock holder is not released by the lease. - For a job that is
InProgress,LockedAtand the dashboard's "Locked At" now show when the lock was last renewed.
- At the first pass after the upgrade, about a minute after the start, every job that is
With the EF Core store and
UseSharpTickerDbContext, from 1.6.0 (#89): the EF Core tools findSharpTickerDbContextin the application's services, sodotnet ef migrations addworks 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 forSharpTickerDbContext, the tools picked the application's context up to 1.5.2 when no--contextwas given; now they find both and stop withMore than one DbContext was found. Scripts that rundotnet ef database update,dotnet ef migrations scriptordotnet ef migrations bundlewithout--contextin such a project need--context AppDbContextafter the upgrade.Dashboard with a custom
ITickerPersistenceProvider, from 1.6.0 (#96): the status charts, the statistics and the jobs per node count throughTimeTickersQuery()andCronTickerOccurrencesQuery()withWhereandCountAsync. A provider whose query objects throw makes/time-tickers/graph-data,/cron-tickers/graph-data,/ticker/statuses/getand/ticker/machine/jobsfail; up to 1.5.2 these read the rows throughGetTimeTickersandGetAllCronTickerOccurrences.Dashboard, from 1.6.0 (#31): the Machines panel is called Lock holders. The answer of
/ticker/machine/jobsis 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 keepsitem1(the name) anditem2(the number of jobs) and addslastLockedAt(the latest lock, in UTC) andhasHeartbeat(with Redis whether the node has a heartbeat entry, otherwise null). A script that relies on the old order can sort byitem2itself.
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.