Testing code that depends on DateTime.Now or DateTime.UtcNow is a nightmare. .NET 9’s TimeProvider solves this elegantly.
The Problem – Untestable Time:
// Hard to test
public class OrderService
{
public bool IsOrderExpired(Order order)
{
// ❌ Always uses current time
return order.CreatedDate.AddDays(1) < DateTime.UtcNow;
}
}
// Test failure:
// - Test at 23:59: Runs correctly
// - Test at 00:01: Fails!
// - Test on different timezone: Different results!
The Solution – TimeProvider:
// .NET 9: TimeProvider
public class OrderService
{
private readonly TimeProvider _timeProvider;
public OrderService(TimeProvider timeProvider)
{
_timeProvider = timeProvider;
}
public bool IsOrderExpired(Order order)
{
// ✅ Uses injected time provider
return order.CreatedDate.AddDays(1) < _timeProvider.GetUtcNow();
}
}
// Test:
var fakeTime = new FakeTimeProvider(new DateTime(2024, 1, 1, 12, 0, 0, DateTimeKind.Utc));
var service = new OrderService(fakeTime);
// Order created at 2024-01-01 00:00:00
// Should expire after 24 hours
var order = new Order { CreatedDate = new DateTime(2024, 1, 1, 0, 0, 0, DateTimeKind.Utc) };
// Test at exactly 24 hours
fakeTime.Advance(TimeSpan.FromHours(24));
Assert.True(service.IsOrderExpired(order)); // ✅ Passes!
// Test at 23 hours 59 minutes
fakeTime.Reset(); // Reset to original time
fakeTime.Advance(TimeSpan.FromHours(23).Add(TimeSpan.FromMinutes(59)));
Assert.False(service.IsOrderExpired(order)); // ✅ Passes!
FakeTimeProvider Implementation:
public class FakeTimeProvider : TimeProvider
{
private DateTimeOffset _currentTime;
public FakeTimeProvider(DateTimeOffset startTime)
{
_currentTime = startTime;
}
public override DateTimeOffset GetUtcNow() => _currentTime;
public void Advance(TimeSpan delta)
{
_currentTime = _currentTime.Add(delta);
}
public void SetTime(DateTimeOffset newTime)
{
_currentTime = newTime;
}
public void Reset()
{
// Reset to initial time
}
}
Real-World Usage – Cache Expiry:
public class CacheService<T>
{
private readonly Dictionary<string, (T Value, DateTimeOffset Expiry)> _cache = new();
private readonly TimeProvider _timeProvider;
private readonly TimeSpan _defaultTtl;
public CacheService(TimeProvider timeProvider, TimeSpan defaultTtl)
{
_timeProvider = timeProvider;
_defaultTtl = defaultTtl;
}
public void Set(string key, T value, TimeSpan? ttl = null)
{
ttl ??= _defaultTtl;
var expiry = _timeProvider.GetUtcNow().Add(ttl.Value);
_cache[key] = (value, expiry);
}
public bool TryGet(string key, out T value)
{
if (_cache.TryGetValue(key, out var entry))
{
if (entry.Expiry > _timeProvider.GetUtcNow())
{
value = entry.Value;
return true;
}
_cache.Remove(key); // Expired
}
value = default;
return false;
}
}
// Test:
[Fact]
public void Cache_Expires_After_TTL()
{
var time = new FakeTimeProvider(DateTimeOffset.UtcNow);
var cache = new CacheService<string>(time, TimeSpan.FromMinutes(5));
cache.Set("key", "value");
Assert.True(cache.TryGet("key", out _)); // ✅ Exists
time.Advance(TimeSpan.FromMinutes(6)); // Advance 6 minutes
Assert.False(cache.TryGet("key", out _)); // ✅ Expired
}
TimeProvider vs ITimer:
// Old way: System.Timers.Timer - Hard to test
public class HeartbeatService
{
private readonly Timer _timer;
public HeartbeatService()
{
_timer = new Timer(1000);
_timer.Elapsed += (s, e) => SendHeartbeat();
_timer.Start();
}
}
// New way: TimeProvider.CreateTimer() - Testable!
public class HeartbeatService
{
private readonly TimeProvider _timeProvider;
private readonly ITimer _timer;
public HeartbeatService(TimeProvider timeProvider)
{
_timeProvider = timeProvider;
_timer = _timeProvider.CreateTimer(
callback: _ => SendHeartbeat(),
state: null,
dueTime: TimeSpan.Zero,
period: TimeSpan.FromSeconds(1)
);
}
public void Stop() => _timer.Change(Timeout.InfiniteTimeSpan, Timeout.InfiniteTimeSpan);
}
// Test:
[Fact]
public void Heartbeat_Sends_Every_Second()
{
var time = new FakeTimeProvider(DateTimeOffset.UtcNow);
var service = new HeartbeatService(time);
// Simulate 10 seconds passing
for (int i = 0; i < 10; i++)
{
time.Advance(TimeSpan.FromSeconds(1));
// Assert heartbeat was sent
}
}
TimeProvider with Dependency Injection:
// Program.cs builder.Services.AddSingleton(TimeProvider.System); // Real time provider // In production: Uses real time // In tests: Injects FakeTimeProvider
TimeZone Support:
// Local time with timezone
var timeProvider = TimeProvider.System;
var localTime = timeProvider.GetLocalNow();
// Custom timezone provider
public class CustomTimeZoneProvider : TimeProvider
{
private readonly TimeZoneInfo _timeZone;
public CustomTimeZoneProvider(TimeZoneInfo timeZone)
{
_timeZone = timeZone;
}
public override TimeZoneInfo LocalTimeZone => _timeZone;
}
Best Practices:
✅ Inject TimeProvider into all services ✅ Use GetUtcNow() for UTC time operations ✅ Use GetLocalNow() for user-facing times ✅ Use CreateTimer() instead of System.Timers.Timer ✅ Use FakeTimeProvider for unit tests ✅ Use TimeProvider.System in DI for production ❌ Don't use DateTime.Now/UtcNow directly ❌ Don't use DateTimeOffset.Now/UtcNow directly ❌ Don't use System.Timers.Timer in new code
