KZDev.SystemClock.PrimeTime — usage guide
Package ID: KZDev.SystemClock.PrimeTime
Namespace: KZDev.SystemClock.PrimeTime
This guide describes the BCL / TimeProvider foundation package: same names (IPrimeClock, PrimeClock, PrimeTestClock, …) as the superset where they overlap, using only BCL types and minimal dependencies.
When to use this package
- You standardize on
DateTimeOffset,TimeSpan, andTimeProvider. - You want to minimize dependencies (no NodaTime required).
- You want
IPrimeClock.LocalScheduleTimeZonefor local calendar time-of-day behavior (see API docs).
If you also need Instant, Duration, or LocalTime extensions on IPrimeClock, use KZDev.PrimeTime which includes all SystemClock functionality plus NodaTime support.
Install
dotnet add package KZDev.SystemClock.PrimeTime
Target frameworks shipped by this repository: net10.0, net8.0, netstandard2.0.
Dependency injection
using KZDev.SystemClock.PrimeTime;
using Microsoft.Extensions.DependencyInjection;
IServiceCollection services = new ServiceCollection();
services.AddPrimeClock();
AddPrimeClock registers:
| Service | Default implementation | Notes |
|---|---|---|
TimeProvider |
TimeProvider.System |
Skipped if you already registered TimeProvider. |
IPrimeClock |
PrimeClock singleton |
Uses the registered TimeProvider. |
IPrimeTime |
same instance as IPrimeClock |
Resolved via factory. |
Using the clock
Prefer IPrimeClock in application code. Typical members include UTC and local projections using BCL types (for example UtcNowDateTimeOffset), plus timer registration methods. Exact members depend on target framework; see the API reference for this stack.
Time-of-day timers
On supported targets, use RegisterTimeOfDay / RegisterAsyncTimeOfDay with LocalTimeOfDay / UtcTimeOfDay wrappers and DayTimeTimerOptions for DST policy. See Timers, daylight saving, and testing.
Virtual time tests
Use PrimeTestClock and IPrimeTestClock. Constructors are BCL-first (for example starting from a DateTimeOffset). Advance virtual time to exercise timers without wall-clock delays.
Runnable examples
Self-contained snippets for this stack live under System Clock examples. Each page reproduces the relevant code in the documentation site so you do not need to navigate the repository to read it. Highlights:
- DI registration — what
AddPrimeClockregisters and how to resolve it. - "Now" surfaces —
LocalNow*andUtcNow*BCL projections. - Persistence and conversions — BCL schedule-zone projection from persisted UTC offsets (see also testing).
- Sleep, delay, and cancellation —
Sleep,DelayAsync, and time-based cancellation tokens. - Interval timers and time-of-day & DST — production wall-clock scheduling.
- Testing counterparts: Interval (testing), Time-of-day & DST (testing), and the cross-track DI replacement and test-clock control pages.
The production DST examples are environment-aware so they can adapt to machine timezone capabilities. The testing examples show deterministic virtual-time patterns for reliable assertions.