ContextQMD
Back to Aspnetcore

Breaking change: ISystemClock is obsolete

aspnetcore/breaking-changes/8/isystemclock-obsolete.md

latest8.3 KB
Original Source

ISystemClock is obsolete

xref:Microsoft.AspNetCore.Authentication.ISystemClock?displayProperty=fullName has been used by ASP.NET Core's authentication and identity components since version 1.0 to enable unit testing of time-related functionality, like expiration checking. .NET 8 includes a suitable abstraction, xref:System.TimeProvider?displayProperty=fullName, that provides the same functionality and much more. We're taking this opportunity to obsolete xref:Microsoft.AspNetCore.Authentication.ISystemClock and replace it with xref:System.TimeProvider throughout the ASP.NET Core libraries.

Version introduced

ASP.NET Core 8.0 Preview 5

Previous behavior

xref:Microsoft.AspNetCore.Authentication.ISystemClock was injected into the constructors of the authentication and identity components by dependency injection (DI) and could be overridden for testing.

The default xref:Microsoft.AspNetCore.Authentication.SystemClock implementation truncated to the nearest second for easier formatting.

New behavior

xref:Microsoft.AspNetCore.Authentication.ISystemClock, xref:Microsoft.AspNetCore.Authentication.SystemClock, and the authentication handler constructors that have an xref:Microsoft.AspNetCore.Authentication.ISystemClock parameter have been marked obsolete. Using these APIs in code will generate a warning at compile time.

xref:Microsoft.AspNetCore.Authentication.ISystemClock remains in the dependency injection container but is no longer used. It may be removed from the container in a future version.

xref:System.TimeProvider is now a settable property on the Options classes for the authentication and identity components. It can be set directly or by registering a provider in the dependency injection container.

xref:System.TimeProvider does not truncate to the nearest second. Consumers are expected to correctly format the time as needed.

Type of breaking change

This change affects source compatibility.

Reason for change

This change was made to unify time abstraction across the stack for easier testing.

If you have components that derive from xref:Microsoft.AspNetCore.Authentication.AuthenticationHandler%601?displayProperty=fullName or xref:Microsoft.AspNetCore.Identity.SecurityStampValidator%601?displayProperty=fullName, remove the xref:Microsoft.AspNetCore.Authentication.ISystemClock constructor parameter and call the new base constructor accordingly.

diff
- public BasicAuthenticationHandler(IOptionsMonitor<AuthenticationSchemeOptions> options, ILoggerFactory logger, UrlEncoder encoder, ISystemClock clock)
-     : base(options, logger, encoder, clock)
+ public BasicAuthenticationHandler(IOptionsMonitor<AuthenticationSchemeOptions> options, ILoggerFactory logger, UrlEncoder encoder)
+     : base(options, logger, encoder)

Similarly, derived implementations that reference the Clock property on these types should reference the new TimeProvider property instead.

diff
- var currentUtc = Clock.UtcNow;
+ var currentUtc = TimeProvider.GetUtcNow();

You can set TimeProvider for testing on the options or via DI.

Affected APIs