Skip to content
Shiny.NET

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 null period fires once, then the reminder is removed.
  • UnregisterReminderAsync(name) removes one, and GetRemindersAsync() 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.DueAt tells 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.

On a phone, the OS suspends or kills apps, so a reminder can come due while nothing is running. Add Shiny.Actors.Jobs:

Terminal window
dotnet add package Shiny.Actors.Jobs
builder.Services.AddShinyActors(x => x.UseBackgroundReminders()); // a Shiny.Jobs IJob: BGTaskScheduler / WorkManager

The job fires everything that’s due, then deactivates the actors it woke so their state is written before the app is suspended again.

Add Shiny.Actors.Notifications and give the reminder a notification:

Terminal window
dotnet add package Shiny.Actors.Notifications
builder.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);

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.

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.