UtcMilliTime 3.1.0

UtcMilliTime

UtcMilliTime is a lightweight C# library that provides reliable Unix millisecond timestamps (long), similar to JavaScript's Date.now(). It includes built-in NTP synchronization, high-resolution monotonic time, and strong support for unit testing.

Version 3.1 introduces TestClock — a fully controllable clock designed for deterministic unit testing of time-dependent code.

On NuGet at: https://www.nuget.org/packages/UtcMilliTime/
On GitHub at: https://github.com/JPKusumi/UtcMilliTime-3.x

What's New in v3.1

• TestClock — a controllable implementation of ITime for unit testing
• AdvanceDays(), AdvanceWeeks(), AdvanceMonths(), and AdvanceYears() methods
• RaiseNetworkTimeAcquired() methods to simulate NTP events in tests
• Improved testability for timeouts, expirations, retries, and scheduled logic

See the CHANGELOG for the full version history.

Overview

UtcMilliTime provides long timestamps (milliseconds since 1970-01-01 UTC). It starts with device time and can optionally synchronize with NTP servers. The main entry point is the Clock singleton, which implements the ITime interface.

Installation

dotnet add package UtcMilliTime --version 3.1.0

Basic Usage

using UtcMilliTime;

var clock = Clock.Time;
clock.SuppressNetworkCalls = false;   // Enable NTP synchronization

long timestamp = clock.Now;
string iso = timestamp.ToIso8601String();

// Cryptographic helper (v3.0+)
byte[] nonce = clock.NowNonce();
long ts = clock.TimestampFromNowNonce(nonce);
uint entropy = clock.EntropyFromNowNonce(nonce);

API Reference

Core API (Clock / ITime)

TestClock API (v3.1+)

TestClock is a controllable implementation of ITime designed for unit testing. Time only advances when explicitly instructed.

Example:

var clock = new TestClock(1_700_000_000_000_000); // Start at a specific time
var clock = TestClock.FromCurrentTime();          // Start from real current time

clock.SetTime(1_800_000_000_000_000);

clock.Advance(TimeSpan.FromMinutes(30));
clock.AdvanceMilliseconds(5000);
clock.AdvanceSeconds(45);
clock.AdvanceMinutes(10);
clock.AdvanceHours(2);
clock.AdvanceDays(5);
clock.AdvanceWeeks(2);
clock.AdvanceMonths(1);
clock.AdvanceYears(1);

// Simulate an NTP sync in a test
clock.RaiseNetworkTimeAcquired("pool.ntp.org", latency: 45, skew: 12);

Thread Safety (v3)

Version 3 includes thread safety improvements across the Clock singleton, particularly around concurrent access and NTP synchronization.

Notes

• By default, SuppressNetworkCalls = true (uses only device time).
• Set SuppressNetworkCalls = false or call SelfUpdateAsync() to enable NTP synchronization.
• The NetworkTimeAcquired event fires after successful NTP syncs.

Resources

• Website: JPKusumi.com
• Discussions & Feedback: GitHub Discussions

License

MIT License