[Breaking change]: ISystemClock obsolete and replaced by TimeProvider

[Tratcher]

Description

Microsoft.AspNetCore.Authentication.ISystemClock has been used by the authentication and identity components since AspNetCore 1.0 to enable unit testing of time related functionality like expiration checking. .NET 8 now includes a suitable abstraction System.TimeProvider that provides the same functionality and much more. We're taking this opportunity to obsolete ISystemClock and replace it with TimeProvider throughout AspNetCore.

See dotnet/aspnetcore#47717 for additional details.

Version

.NET 8 Preview 5

Previous behavior

ISystemClock was injected into the constructors by Dependency Injection and could be overridden for testing.

Note the default SystemClock implementation would truncate to the nearest second for easier formatting.

New behavior

ISystemClock remains in the Dependency Injection container but is no longer used. It may be removed from the container in a future version.

TimeProvider is now a settable property on the Options classes for these types. It can be set directly or by registering a provider in the Dependency Injection container.

TimeProvider does not truncate to the nearest second, consumers are expected to correctly format the time as needed.

Type of breaking change

• Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code may require source changes to compile successfully.
• Behavioral change: Existing binaries may behave differently at run time.

Reason for change

Unifying the time abstraction across the stack for easier testing.

Recommended action

Components that derive from Microsoft.AspNetCore.Authentication.AuthenticationHandler<TOptions> or Microsoft.AspNetCore.Identity.SecurityStampValidator<TUser> should remove their ISystemClock constructor parameter and call the new base constructor accordingly. Similarly, derived implementations that reference the Clock property on these types should reference the new TimeProvider property instead. TimeProvider is now settable for testing on the options or via DI.

-    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)

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

Affected APIs

• ISystemClock
• SystemClock
• AuthenticationHandler<TOptions>
• AuthenticationHandler<TOptions>.Clock
• CookieAuthenticationHandler
• FacebookHandler
• GoogleHandler
• JwtBearerHandler
• MicrosoftAccountHandler
• NegotiateHandler
• OAuthHandler<TOptions>
• OpenIdConnectHandler
• PolicySchemeHandler
• RemoteAuthenticationHandler<TOptions>
• SignInAuthenticationHandler<TOptions>
• SignOutAuthenticationHandler<TOptions>
• TwitterHandler
• WsFederationHandler
• SecurityStampValidator<TUser>
• TwoFactorSecurityStampValidator<TUser>