OPCFoundation · marcschier · May 28, 2026 · May 29, 2026 · May 29, 2026 · May 29, 2026
diff --git a/.github/agents/opcua-v20-migration.agent.md b/.github/agents/opcua-v20-migration.agent.md
@@ -9,13 +9,111 @@ You are an expert migration agent for upgrading OPC UA .NET Standard application
 
 ## Strategy
 
-1. **Build first**: Run `dotnet build` to identify all errors.
-2. **Categorize errors**: Group errors by type (struct nullability, collection types, Variant/object, encoder/decoder, etc.).
-3. **Fix in order**: Apply fixes in the priority order defined below — some fixes resolve cascading errors.
-4. **Rebuild and iterate**: After each batch of fixes, rebuild to verify progress and catch new errors.
-5. **Do not suppress warnings**: Fix [Obsolete] warnings properly using the replacement API, do not add `#pragma warning disable`.
+**Start with the MigrationAnalyzer NuGet package** — it ships an analyzer + code-fix set (UA0001–UA0022) and a compatibility shim DLL that together handle most mechanical migrations automatically. Only fall back to the manual rules below for patterns the analyzers do not cover or that require structural redesign.
 
-## Priority Order for Fixes
+1. **Install the migration package**: Add the `OPCFoundation.NetStandard.Opc.Ua.MigrationAnalyzer` NuGet to every project that references an `OPCFoundation.NetStandard.Opc.Ua.*` package, as a build-only dependency:
+
+   ```xml
+   <PackageReference Include="OPCFoundation.NetStandard.Opc.Ua.MigrationAnalyzer"
+                     Version="2.0.*-*"
+                     PrivateAssets="all" />
+   ```
+
+   The package bundles two payloads:
+   - **Analyzer + code-fix DLLs** (`Opc.Ua.MigrationAnalyzer.dll`, `Opc.Ua.MigrationAnalyzer.CodeFixer.dll`) loaded into csc.exe and the IDE.
+   - **Compatibility shim** (`Opc.Ua.MigrationAnalyzer.Core.dll`) that re-exposes the 1.5.378 obsolete extension surface so 1.5.378-style call sites compile against 2.0 with warnings instead of errors.
+
+2. **Bump the OPC UA package versions to `2.0.*-*`** in every consumer project. Do NOT remove existing `OPCFoundation.NetStandard.Opc.Ua.*` references — just update their `Version` attribute.
+
+3. **Run `dotnet restore` then `dotnet build`**. The shim usually gets the project to compile; what remains are `[Obsolete]` warnings (CS0618) and `UA0001`–`UA0022` analyzer diagnostics that point at the patterns still using the old surface.
+
+4. **Apply analyzer auto-fixes**: in Visual Studio, hover each `UA00xx` diagnostic and apply the offered Quick Fix. From the command line, run:
+
+   ```bash
+   dotnet format analyzers <solution>.sln \
+       --diagnostics UA0002 UA0003 UA0004 UA0005 UA0006 UA0007 UA0008 \
+                     UA0009 UA0010 UA0012 UA0014 UA0019 UA0020 UA0022 \
+       --severity warn
+   ```
+
+   The 14 listed rules ship batch code-fixes. The remaining `UA0001`/`UA0011`/`UA0015`/`UA0018`/`UA0021` are diagnostic-only — they require manual judgement.
+
+5. **Walk the remaining manual patterns** — anything the analyzers did not flag is covered by the categorical rules below.
+
+6. **Remove the MigrationAnalyzer package** once the project is warning-free. You are then on clean 2.0 with no shim dependency.
+
+7. **Do not suppress `[Obsolete]` or `UA00xx` warnings.** Fix them using the documented replacement; obsolete API will be removed in the next minor release.
+
+## What the MigrationAnalyzer package covers
+
+| ID     | Default  | Auto-fix | Replaces                                                                                |
+| ------ | -------- | -------- | --------------------------------------------------------------------------------------- |
+| UA0001 | Info     | No       | `Utils.Trace` / `Utils.LogX` — manually inject `ILogger` via `ITelemetryContext`        |
+| UA0002 | Warning  | Yes      | Removed `<Type>Collection` wrappers → `ArrayOf<T>` / `List<T>`                          |
+| UA0003 | Warning  | Yes      | `x == null` on now-struct built-in types → `x.IsNull`                                   |
+| UA0004 | Warning  | Yes      | `?.` on now-struct built-in types → direct access                                       |
+| UA0005 | Warning  | Yes      | `byte[]` where `ByteString` is expected → `.ToByteString()`                             |
+| UA0006 | Warning  | Yes      | `new Variant(object\|DateTime\|Guid\|byte[])` → `Variant.From(...)`                     |
+| UA0007 | Warning  | Yes      | `new NodeId(string)` / `new ExpandedNodeId(string)` → `Parse(...)`                      |
+| UA0008 | Warning  | Yes      | `Session.Call(..., params object[])` → wrap args with `Variant.From`                    |
+| UA0009 | Warning  | Yes      | `[DataContract]`/`[DataMember]` on config extensions → `[DataType]`/`[DataField]`        |
+| UA0010 | Warning  | Yes      | `using`/`Dispose` on `CertificateIdentifier`/`UserIdentity`/`IUserIdentityTokenHandler`  |
+| UA0011 | Info     | No       | Sync `IUserIdentityTokenHandler.Encrypt/Decrypt/Sign/Verify` → await `*Async`           |
+| UA0012 | Warning  | Yes      | `CertificateFactory.*` static helpers → instance methods                                |
+| UA0014 | Warning  | Yes      | `DataValue.IsGood(dv)` static helper → `dv.IsGood`                                      |
+| UA0015 | Info     | No       | Sync / APM members on GDS / LDS clients → await `*Async`                                |
+| UA0018 | Info     | No       | `CertificateIdentifier.Certificate` getter → `LoadCertificate2Async`                    |
+| UA0019 | Warning  | Yes      | `new DataValue(StatusCode[, ts])` → `new DataValue { StatusCode = ..., ... }`           |
+| UA0020 | Warning  | Yes      | `EncodeableFactory.GlobalFactory` / `Create()` → `ServiceMessageContext.Factory` / `Fork()` |
+| UA0021 | Info     | No       | `CertificateValidator` / `CertificateValidationEventArgs` (structural rename — see §X) |
+| UA0022 | Warning  | Yes      | `ApplicationConfiguration.CertificateValidator` / `ServerBase.CertificateValidator` → `.CertificateManager` |
+
+## What the shim covers
+
+`Opc.Ua.MigrationAnalyzer.Core.dll` re-exposes the 1.5.378 surface as C# 14 `extension` members so 1.5.378 call sites continue to compile:
+
+- **Moved obsolete extensions**: `NodeId` / `Variant` / `DataValue` null-check helpers, `Session` sync helpers, `Subscription` sync helpers, `ApplicationInstance` helpers, `ServerBase.Start` / `Stop`, `TransportChannel` APM, `ChannelBase` static factory methods, and similar surface.
+- **New shims for genuinely-removed members**: `EncodeableFactory.GlobalFactory`, `CertificateIdentifier.Certificate` (throws), sync wrappers for `IUserIdentityTokenHandler.{Encrypt,Decrypt,Sign,Verify}`, sync + APM wrappers for GDS / LDS client APIs.
+
+## What the shim does NOT cover
+
+These changes are source-level only; no extension method can paper over them. Use the listed analyzer fix.
+
+- `== null` / `!= null` on now-struct types — use the **UA0003** fixer (auto).
+- `?.` member access on now-struct types — use the **UA0004** fixer (auto).
+- `using var x = new CertificateIdentifier(...)` — use **UA0010** to drop the `using`.
+- `[DataContract]`/`[DataMember]` on configuration extensions — use **UA0009**.
+- Removed `<Type>Collection` wrappers — use **UA0002**.
+- `CertificateValidator` type rename — see §Certificate validation pipeline below (manual).
+- Removed pre-generated source-generator output — see §Source Generation (manual).
+
+## Sync-over-async caveat
+
+The sync shims (e.g. `handler.Encrypt(bytes)`, `gdsClient.RegisterApplication(...)`, the `Session` / `Subscription` sync helpers) wrap their `*Async` counterparts via `Task.Run(() => …Async(...)).GetAwaiter().GetResult()`. This is intended as a **migration aid only**: it keeps legacy call sites compiling while you port them to `async`/`await`. Do not leave these calls on production hot paths — follow the `UA0011` / `UA0015` guidance and switch to the async APIs.
+
+## TreatWarningsAsErrors recipe
+
+If your project sets `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>` and you cannot relax it during the migration window, exclude the migration diagnostics from the failure set:
+
+```xml
+<PropertyGroup>
+  <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+  <NoWarn>$(NoWarn);CS0618;UA0001;UA0002;UA0003;UA0004;UA0005;UA0006;UA0007;UA0008;UA0009;UA0010;UA0011;UA0012;UA0014;UA0015;UA0018;UA0019;UA0020;UA0021;UA0022</NoWarn>
+</PropertyGroup>
+```
+
+Remove each entry as you finish fixing the corresponding rule, and drop the whole block once the MigrationAnalyzer package is removed.
+
+## Known compatibility gaps
+
+- **Legacy `.NET Framework` projects using the pre-SDK `xmlns="http://schemas.microsoft.com/developer/msbuild/2003"` format** do not honour `PackageReference` injection via `Directory.Build.targets`. To get the analyzer / shim into a legacy WinForms project, add the `<PackageReference Include="OPCFoundation.NetStandard.Opc.Ua.MigrationAnalyzer" ...>` directly to the project file's existing `<ItemGroup>`.
+- **Projects with `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>` and 100+ migration errors** may abort csc.exe before the analyzer reaches some patterns. Apply the `<NoWarn>` recipe above, run the analyzer, then re-enable warnings-as-errors.
+
+## Manual migration rules (anything the analyzers / shim do not cover)
+
+The sections below remain the canonical reference for patterns that require human judgement. Apply them in the priority order shown — some fixes resolve cascading errors.
+
+### Priority order for fixes
 
 Apply changes in this order to minimize cascading errors:
 

diff --git a/Applications/ConsoleReferenceClient/Program.cs b/Applications/ConsoleReferenceClient/Program.cs
@@ -295,7 +295,17 @@ public static Task<int> Main(string[] args)
                         );
                         config.TraceConfiguration.DeleteOnLoad = true;
 #pragma warning disable CS0618 // Type or member is obsolete
-                        config.TraceConfiguration.ApplySettings();
+                        {
+                            TraceConfiguration traceConfiguration = config.TraceConfiguration;
+                            if (traceConfiguration.OutputFilePath != null)
+                            {
+                                Utils.SetTraceLog(traceConfiguration.OutputFilePath, traceConfiguration.DeleteOnLoad);
+                            }
+                            Utils.SetTraceMask(traceConfiguration.TraceMasks);
+                            Utils.SetTraceOutput(traceConfiguration.TraceMasks == 0
+                                ? Utils.TraceOutput.Off
+                                : Utils.TraceOutput.DebugAndFile);
+                        }
 #pragma warning restore CS0618 // Type or member is obsolete
                     }
 

diff --git a/Directory.Packages.props b/Directory.Packages.props
@@ -20,7 +20,9 @@
     <PackageVersion Include="Microsoft.Bcl.TimeProvider" Version="10.0.8" />
     <PackageVersion Include="Microsoft.CodeAnalysis.Analyzers" Version="4.14.0" />
     <PackageVersion Include="Microsoft.CodeAnalysis.Common" Version="4.14.0" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="5.3.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.14.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.14.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.Common" Version="4.14.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.8" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.Abstractions" Version="10.0.8" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.8" />

diff --git a/Docs/MigrationGuide.md b/Docs/MigrationGuide.md
@@ -89,7 +89,7 @@ This document outlines the breaking changes introduced from version to version.
 
 ## Migrating from 1.5.378 to 2.0.x
 
-> **Automate the migration.** Add the `OPCFoundation.NetStandard.Opc.Ua.CodeFixers` analyzer package to your projects to receive analyzer warnings and one-click fixes for the patterns in this guide. Rule IDs `UA0001`-`UA0020` map directly to the sections below.
+> **Automate the migration.** Add the `OPCFoundation.NetStandard.Opc.Ua.MigrationAnalyzer` analyzer package to your projects to receive analyzer warnings and one-click fixes for the patterns in this guide. Rule IDs `UA0001`-`UA0020` map directly to the sections below.
 
 Version 2.0 introduces a major architectural change from pre-generated code files to runtime source generation and more efficient memory use with a several major Breaking Changes requiring changes to your applications.
 

diff --git a/Libraries/Opc.Ua.Configuration/ApplicationConfigurationBuilder.cs b/Libraries/Opc.Ua.Configuration/ApplicationConfigurationBuilder.cs
@@ -365,7 +365,18 @@ ApplicationType.Client or ApplicationType.ClientAndServer &&
             }
 
 #pragma warning disable CS0618 // Type or member is obsolete
-            ApplicationConfiguration.TraceConfiguration?.ApplySettings();
+            TraceConfiguration? traceConfiguration = ApplicationConfiguration.TraceConfiguration;
+            if (traceConfiguration != null)
+            {
+                if (traceConfiguration.OutputFilePath != null)
+                {
+                    Utils.SetTraceLog(traceConfiguration.OutputFilePath, traceConfiguration.DeleteOnLoad);
+                }
+                Utils.SetTraceMask(traceConfiguration.TraceMasks);
+                Utils.SetTraceOutput(traceConfiguration.TraceMasks == 0
+                    ? Utils.TraceOutput.Off
+                    : Utils.TraceOutput.DebugAndFile);
+            }
 #pragma warning restore CS0618 // Type or member is obsolete
 
             await ApplicationConfiguration.ValidateAsync(ApplicationInstance.ApplicationType, ct)

diff --git a/Libraries/Opc.Ua.Configuration/ApplicationInstance.cs b/Libraries/Opc.Ua.Configuration/ApplicationInstance.cs
@@ -171,7 +171,7 @@ public ValueTask StopAsync(CancellationToken ct = default)
         [Obsolete("Use StopAsync")]
         public void Stop()
         {
-            Server?.Stop();
+            Server?.StopAsync().AsTask().GetAwaiter().GetResult();
         }
 
         /// <inheritdoc/>
@@ -293,7 +293,15 @@ public IApplicationConfigurationBuilderTypes Build(string applicationUri, string
 
             // Trace off
 #pragma warning disable CS0618 // Type or member is obsolete
-            ApplicationConfiguration.TraceConfiguration.ApplySettings();
+            TraceConfiguration traceConfiguration = ApplicationConfiguration.TraceConfiguration;
+            if (traceConfiguration.OutputFilePath != null)
+            {
+                Utils.SetTraceLog(traceConfiguration.OutputFilePath, traceConfiguration.DeleteOnLoad);
+            }
+            Utils.SetTraceMask(traceConfiguration.TraceMasks);
+            Utils.SetTraceOutput(traceConfiguration.TraceMasks == 0
+                ? Utils.TraceOutput.Off
+                : Utils.TraceOutput.DebugAndFile);
 #pragma warning restore CS0618 // Type or member is obsolete
 
             return new ApplicationConfigurationBuilder(this);

diff --git a/Libraries/Opc.Ua.Configuration/Opc.Ua.Configuration.csproj b/Libraries/Opc.Ua.Configuration/Opc.Ua.Configuration.csproj
@@ -12,6 +12,7 @@
   </PropertyGroup>
   <ItemGroup>
     <InternalsVisibleTo Include="Opc.Ua.Configuration.Tests" />
+    <InternalsVisibleTo Include="Opc.Ua.MigrationAnalyzer.Core" />
   </ItemGroup>
   <PropertyGroup Condition="'$(Configuration)' == 'Debug'">
     <PackageId>$(PackageId).Debug</PackageId>

diff --git a/Libraries/Opc.Ua.Gds.Server.Common/GlobalDiscoverySampleServer.cs b/Libraries/Opc.Ua.Gds.Server.Common/GlobalDiscoverySampleServer.cs
@@ -74,6 +74,27 @@
             m_autoApprove = autoApprove;
         }
 
+        /// <summary>
+        /// Back-compat ctor matching the 1.5.378 signature (no <see cref="ITelemetryContext"/>).
+        /// Forwards to the modern ctor with a null telemetry context.
+        /// </summary>
+        /// <remarks>
+        /// Preserved so 1.5.378-style sample code (`new GlobalDiscoverySampleServer(database,
+        /// request, certificateGroup, userDatabase, autoApprove)`) continues to compile against
+        /// 2.0 without re-ordering the call site. Consumers should pass an explicit
+        /// <see cref="ITelemetryContext"/> via the non-obsolete ctor.
+        /// </remarks>
+        [Obsolete("Use the constructor that takes an ITelemetryContext parameter instead.")]
+        public GlobalDiscoverySampleServer(
+            IApplicationsDatabase database,
+            ICertificateRequest request,
+            ICertificateGroup certificateGroup,
+            IUserDatabase userDatabase,
+            bool autoApprove = true)
+            : this(database, request, certificateGroup, userDatabase, telemetry: null!, autoApprove)
+        {
+        }
+
         /// <summary>
         /// Called before the server starts. Registers GDS-specific
         /// encodeable types in the server's message context factory,
@@ -137,7 +158,7 @@

            // create master node manager.
            return new ValueTask<IMasterNodeManager>(
                new MasterNodeManager(server, configuration, null, nodeManagers));
        }

        /// <summary>

diff --git a/Libraries/Opc.Ua.Server/Server/StandardServer.cs b/Libraries/Opc.Ua.Server/Server/StandardServer.cs
@@ -2759,7 +2759,17 @@ await CertificateManager.UpdateAsync(
                     new TraceConfiguration();
 
 #pragma warning disable CS0618 // Type or member is obsolete
-                currentConfiguration.TraceConfiguration.ApplySettings();
+                {
+                    TraceConfiguration traceConfiguration = currentConfiguration.TraceConfiguration;
+                    if (traceConfiguration.OutputFilePath != null)
+                    {
+                        Utils.SetTraceLog(traceConfiguration.OutputFilePath, traceConfiguration.DeleteOnLoad);
+                    }
+                    Utils.SetTraceMask(traceConfiguration.TraceMasks);
+                    Utils.SetTraceOutput(traceConfiguration.TraceMasks == 0
+                        ? Utils.TraceOutput.Off
+                        : Utils.TraceOutput.DebugAndFile);
+                }
 #pragma warning restore CS0618 // Type or member is obsolete
             }
             catch (Exception e)

diff --git a/Stack/Opc.Ua.Core/Opc.Ua.Core.csproj b/Stack/Opc.Ua.Core/Opc.Ua.Core.csproj
@@ -17,6 +17,7 @@
     <InternalsVisibleTo Include="Opc.Ua.Core.TestFramework" />
     <InternalsVisibleTo Include="Opc.Ua.Core.Encoders.Tests" />
     <InternalsVisibleTo Include="Opc.Ua.Security.Certificates.Tests" />
+    <InternalsVisibleTo Include="Opc.Ua.MigrationAnalyzer.Core" />
   </ItemGroup>
   <PropertyGroup Condition="'$(Configuration)' == 'Debug'">
     <PackageId>$(PackageId).Debug</PackageId>