Reminders
A reminder is a persistent timer. It survives deactivation and restarts, and activates the actor when it is due. For a timer that only lives as long as the activation, see Timers.
public class Billing : Actor<BillingState>, IBilling, IRemindable{ public Task Start() => RegisterReminderAsync("invoice", TimeSpan.FromHours(1), TimeSpan.FromDays(1)).AsTask();
public ValueTask ReceiveReminderAsync(ReminderTick tick, CancellationToken ct) { var late = tick.FiredAt - tick.DueAt; ... }}- The actor must implement
IRemindable. Registering an existing name replaces the reminder. - A
nullperiod fires once, then the reminder is removed. UnregisterReminderAsync(name)removes one, andGetRemindersAsync()lists this actor’s reminders.- While the app runs, reminders fire on time.
- Missed ticks (the app wasn’t running) coalesce into one, and
tick.DueAttells you how late it is. - At least once. A reminder only moves on after its actor handled it, and a failure is retried within a minute.
Reminders persist in the IActorReminderStore. UseFileStorage(dir) keeps them in dir/reminders.json, and
Shiny.DocumentDb keeps them alongside state.
In the background
Section titled “In the background”On a phone, the OS suspends or kills apps, so a reminder can come due while nothing is running. Add
Shiny.Actors.Jobs:
dotnet add package Shiny.Actors.Jobsbuilder.Services.AddShinyActors(x => x.UseBackgroundReminders()); // a Shiny.Jobs IJob: BGTaskScheduler / WorkManagerThe job fires everything that’s due, then deactivates the actors it woke so their state is written before the app is suspended again.
On time, even when the app is dead
Section titled “On time, even when the app is dead”Add Shiny.Actors.Notifications and give the reminder a notification:
dotnet add package Shiny.Actors.Notificationsbuilder.Services.AddShinyActors(x => x.UseReminderNotifications()); // registers Shiny.Notifications too
await RegisterReminderAsync("standup", TimeSpan.FromHours(1), notification: new ReminderNotification("Standup", "Starts in 5 minutes") { Channel = "alerts" });Each such reminder becomes an OS-scheduled local notification on iOS, Android, Mac and Windows:
- A repeating reminder keeps its next few occurrences scheduled (
UpcomingOccurrences, 3 by default), topped up each time it fires, so the OS keeps showing them even if the app doesn’t run for a while. - Removing the reminder cancels the occurrences still pending. A notification the OS has already shown stays in Notification Center until the user dismisses it, even after the reminder fires in-process.
- A failing reminder’s retries don’t post new notifications. Neither do runs that only re-sync at startup.
- The OS shows it on time whether or not the app is running.
- Tapping it opens the app, where the overdue reminder fires.
x.UseReminderNotifications(o => o.UpcomingOccurrences = 5);Handling taps
Section titled “Handling taps”An actor that implements IReminderNotificationHandler hears about taps on its reminders’ notifications, as a normal
turn. It’s activated if it needs to be:
public class StandupActor : Actor, IStandup, IRemindable, IReminderNotificationHandler{ public ValueTask OnReminderNotificationTappedAsync(ReminderNotificationTap tap, CancellationToken ct) { // tap.Reminder, tap.DueAt (the occurrence), tap.ActionIdentifier (null for a plain tap), tap.Text return default; }}UseReminderNotifications() registers the delegate that routes them next to the app’s own INotificationDelegates.
Notifications that aren’t for reminders are left alone.
Channel is an Android notification channel the app has created. Without it, the default channel is used.
Observing reminders
Section titled “Observing reminders”IActorReminderObserver is told about every reminder that is scheduled (registered, advanced, or loaded at startup)
and every one that is removed, one at a time and in the order they happened. Retries of a failed delivery aren’t
reported. That’s how the notifications package works, and you can use it to mirror reminders
anywhere else:
actors.AddReminderObserver<CalendarMirror>(); // created by the container
public sealed class CalendarMirror : IActorReminderObserver{ public ValueTask OnScheduledAsync(ActorReminder reminder, CancellationToken ct) { ... } public ValueTask OnRemovedAsync(ActorReminder reminder, CancellationToken ct) { ... }}Calls must be idempotent. A failure is logged and never thrown.


