mirror of
https://github.com/OPCFoundation/UA-.NETStandard.git
synced 2026-10-18 22:55:08 +08:00
Marc Schier
dbc09b8e22
# Description Adopt [`System.TimeProvider`](https://learn.microsoft.com/dotnet/api/system.timeprovider) across the stack so that every place that creates timers, runs duration math, or schedules periodic work is mockable, deterministic in tests, and immune to wall-clock changes. The migration touches Core, Core.Types, Server, Client, PubSub, Configuration, Gds (server + client), Lds, and the Quickstarts/Console reference apps. Per-component changes follow the same pattern: 1. Add a `private readonly TimeProvider m_timeProvider;` field. 2. Accept a nullable `TimeProvider? timeProvider = null` as the **last** constructor parameter (new overload; legacy constructor stays for binary compatibility and delegates with `timeProvider: null`). 3. Initialise the field with `m_timeProvider = timeProvider ??= TimeProvider.System;`. 4. Replace `new Timer(...)`, `Stopwatch`, `HiResClock.*`, `DateTime.UtcNow`-based duration math, and `Task.Delay(delay, ct)` in timing loops with the matching `m_timeProvider` API (`CreateTimer`, `GetTimestamp` / `GetElapsedTime`, `GetUtcNow().UtcDateTime`, `Task.Delay(delay, m_timeProvider, ct)`). 5. Wire the provider through DI: `AddOpcUaServerBuilder` / `AddOpcUaClientBuilder` register `TimeProvider.System` via `TryAddSingleton<TimeProvider>()` so tests can swap in `Microsoft.Extensions.Time.Testing.FakeTimeProvider`. `HiResClock` itself is kept (so the `ApplicationConfiguration.DisableHiResClock` schema flag still round-trips), but **every public member** is now `[Obsolete]` with a single shared message pointing to the new migration-guide section. The few internal call sites that still need to set/read `HiResClock` are wrapped with `#pragma warning disable CS0618`. ### Highlights per component - **Core / Stack** — `Opc.Ua.Core`, `Opc.Ua.Core.Types`, channel pipeline (`UaSCBinaryClientChannel`, `ChannelToken`, `UaSCBinaryChannel`), `ApplicationConfiguration`, certificate validators, `JwksIssuerKeyResolver`, `TimeProviderExtensions` polyfills (`GetTimestampMilliseconds`, `GetTickCount`, `CancellationTokenSource(timeout, timeProvider)`, `Task.Delay(delay, provider, ct)` polyfill for older TFMs). - **Server** — session lockout, subscription pipeline (publish/sample/keep-alive/lifetime), `MonitoredItemQueue`, alarm sampling rate, `IntervalRunner`, server diagnostics, configuration state machines, hosted services. - **Client** — `Session`, managed/V2 subscription engines, reconnect handlers, channel keep-alive, periodic publishing, complex-type discovery polling. - **PubSub** — `IntervalRunner` pipeline, message-receive timers, MQTT/UDP keep-alive, publishers/readers. - **Gds / Lds** — `LdsServer`, `LinqApplicationsDatabase` expiry housekeeping, GDS clients (push, pull), `DirectoryCertificateStore`, `ConnectionStateMachine`, classic subscription engine. - **Quickstarts / Console samples** — `SampleNodeManager`, `ReferenceNodeManager`, `AlarmNodeManager`, `BoilerState`, `MemoryBufferState`, `PublishedValuesWrites`. Samples resolve via `(Server as ITimeProviderProvider)?.TimeProvider ?? TimeProvider.System` so existing ctor signatures stay binary-compatible. - **Tests** — `Opc.Ua.PubSub.Tests` adds `IntervalRunnerTests`; existing `SubscriptionTests`, `UaPublisherTests`, and `TestDataSystem` move off `HiResClock`. Added `Microsoft.Extensions.TimeProvider.Testing` package for `FakeTimeProvider` (project-load warning surfaces on net48/net472 only — runtime is .NET 8+). ### Migration guide New section [**Time and Timer abstraction (`TimeProvider`)**](Docs/MigrationGuide.md#time-and-timer-abstraction-timeprovider) documents: - The canonical replacement table (`HiResClock.UtcNow` → `timeProvider.GetUtcNow().UtcDateTime`, `HiResClock.TickCount64` → `timeProvider.GetTimestamp()`, `new Timer` → `timeProvider.CreateTimer`, `Task.Delay(delay, ct)` → `Task.Delay(delay, timeProvider, ct)`, …). - The `TimeProvider? timeProvider = null` + `??=` constructor pattern. - DI wiring and how to swap in `FakeTimeProvider` in tests. - Before/after snippets for `HiResClock.TickCount64`, `HiResClock.UtcNow`, and `new Timer(...)`. ## Related Issues - Fixes #2458 ## Checklist - [x] I have signed the [CLA](https://opcfoundation.org/license/cla/ContributorLicenseAgreementv1.0.pdf) and read the [CONTRIBUTING](https://github.com/OPCFoundation/UA-.NETStandard/blob/master/CONTRIBUTING.md) doc. - [x] I have added tests that prove my fix is effective or that my feature works and increased code coverage. - [x] I have added all necessary documentation. - [x] I have verified that my changes do not introduce (new) build or analyzer warnings. - [ ] I ran **all** tests locally using the **UA.slnx** solution against at least .net **framework** and .net **10**, and all passed. - [ ] I fixed **all** failing and flaky tests in the CI pipelines and **all** CodeQL warnings. - [ ] I have addressed **all** PR feedback received.
OPC UA .NET Standard stack documentation
Here is a list of available documentation for different topics:
UA Core stack related
- OPC UA Profiles and Facets - Overview of supported OPC UA profiles, facets, security policies, and transport protocols.
- Migration Guide - How to migrate from a previous version.
- Sessions, Reconnection, and Subscription Engines - Architectural overview of
Session,ManagedSession,SessionReconnectHandler, and the classic / V2 subscription engines, including guidance on which to use. - About .NET platform support, Nuget packages and versioning.
- How X.509 Certificates are used in the certificate stores.
- Using the Reverse Connect for the UA-TCP transport.
- Support for the TransferSubscriptions service set.
- Observability support in the stack.
- Support for WellKnownRoles & RoleBasedUserManagement.
- Pluggable Identity Providers — interfaces (
IClientIdentityProvider,IUserTokenAuthenticator,IAccessTokenProvider,ITokenIssuer,IIdentityClaims) plus the OPC 10000-6 §6.5.2.2IssuerEndpointUrlJSON parser for OAuth2 / OIDC / Entra / JWT flows. - Support for ECC Certificates.
- Working with ComplexTypes - Custom structures and enumerations.
- Client-based NodeSet Export - Export server address space to NodeSet2 XML.
- Source generated [DataTypes] - How to annotate POCO classes and let the source generator generate the
IEncodeableimplementation. - Source generated NodeManagers - Emit an
AsyncCustomNodeManagerfrom a model design XML and wire callbacks via the fluentINodeManagerBuilderAPI; supports NativeAOT single-file servers (sample: MinimalBoilerServer). - Alias Names - Full server + client support for the OPC UA Part 17 alias-name model (
AliasNameType,AliasNameCategoryType,FindAlias,FindAliasVerbose,AddAliasesToCategory,DeleteAliasesFromCategory,LastChange). - Alarms and Conditions - Full server + client support for OPC UA Part 9. Server-side state types for latched/silenced/out-of-service alarms, alarm groups and suppression engine, alarm rate metrics. Client-side
AlarmClient, typed alarm event records, fluentAlarmEventFilterBuilder,IAsyncEnumerablealarm streaming viaAlarmStreamExtensions. - Streaming Subscriptions -
IAsyncEnumerable-based subscription API for state-machine waits and short-lived monitoring (IStreamingSubscription,ManagedSession.DefaultStreaming,TakeUntilAsync/WithTimeoutAsynchelpers). - State Machines - Generic, extensible Part 16 state-machine API. Client side: streaming + read helpers on the source-generated
*TypeClientproxies (GetCurrentFiniteStateAsync,ObserveFiniteTransitionsAsync,WaitForStateAsync). Server side: unified fluentStateMachineBuilderwith two complementary modes — definition (Create(...)+AddState/AddTransition/OnCausefor ad-hoc machines viaFluentFiniteStateMachineState) and lifecycle (For(...)/INodeBuilder.AsStateMachine()+OnEnterState/WithCause/WithTimedTransitionto attach behavior to stack-shipped or generator-emitted FSMs). Vendor state machines inherit both ends of the API automatically. - Model Change Tracking - Client-side address-space change tracking with per-node
INodeCacheinvalidation; server-sideModelChangeAggregatorand auto-emittedGeneralModelChangeEventfromCustomNodeManager.CreateNode/DeleteNode. - Dependency Injection - The unified
services.AddOpcUa()/IOpcUaBuildersurface for hosting OPC UA components inMicrosoft.Extensions.DependencyInjection/ the .NET Generic Host (servers asIHostedService, options viaAction<T>orIConfiguration, AOT-friendly). - AuthorizationService - Modern Part 12
StartRequestToken/FinishRequestToken,ITokenIssuer, and GDS token issuance. - KeyCredentialService - Pull, Push, and experimental bridge guidance for Part 12 KeyCredential flows.
Reference application related
- Reference Client documentation for configuration of the console reference client using parameters.
- Reference Server documentation for running against CTT.
- Provisioning Mode for secure certificate provisioning and initial server configuration.
- Using the Container support of the Reference Server in Visual Studio 2026 and for local testing.
Starting with version 1.5.375.XX the Windows Forms reference client & reference server were moved to the OPC UA .NET Standard Samples repository.
For the PubSub support library
- The PubSub library with samples.
- The ConsoleReferencePublisher documentation.
- The ConsoleReferenceSubscriber documentation.
Global Discovery Server (GDS)
- GDS Developer Guide — Application registration, certificate management (pull & push models), roles and authorization, provider implementation, end-to-end examples.
- KeyCredentialService — Credential issuance for non-OPC UA services (MQTT, REST), IKeyCredentialRequestStore provider guide, ISecretStore integration.
- AuthorizationService — OAuth2-style access token issuance, IAccessTokenProvider implementation guide.
- Role-Based Security — Part 18 roles and claim-based identity-mapping rules.
- Identity Providers — server and client identity-provider architecture.
- Dependency Injection — dependency injection hosting and identity registration extensions.