2.0 Migration Analyzer and codefixer with Agent update

[marcschier]

Proposed changes

Introduces OPCFoundation.NetStandard.Opc.Ua.MigrationAnalyzer — a single NuGet package that ships three coordinated DLLs to make the 1.5.378 → 2.0 upgrade as close to "install package, run dotnet format, remove package" as possible:

DLL	Where	Purpose
Opc.Ua.MigrationAnalyzer.dll	analyzers/dotnet/cs/	19 Roslyn analyzers (UA0001–UA0022) covering every breaking-change pattern in Docs/MigrationGuide.md. Built against the stable Roslyn 4.14 analyzer API — loads cleanly in csc.exe (no Microsoft.CodeAnalysis.Workspaces reference).
Opc.Ua.MigrationAnalyzer.CodeFixer.dll	analyzers/dotnet/cs/	14 companion CodeFixProviders; loaded only by Workspaces-aware hosts (Visual Studio, dotnet format analyzers).
Opc.Ua.MigrationAnalyzer.Core.dll	lib/<tfm>/ for net472, net48, netstandard2.1, net8.0, net9.0, net10.0	1.5.378 → 2.0 compatibility shim. Re-exposes the obsolete extension surface so 1.5.378-style call sites keep compiling against 2.0 with warnings instead of errors.

Migration workflow the package enables

1. Bump every OPCFoundation.NetStandard.Opc.Ua.* PackageReference to 2.0.*-*.
2. Add the migration package as a build-only dependency:

   <PackageReference Include="OPCFoundation.NetStandard.Opc.Ua.MigrationAnalyzer"
                     Version="2.0.*-*"
                     PrivateAssets="all" />

3. Run dotnet build. Most call sites that 1.6 made obsolete still compile because the Core (shim) DLL re-supplies them. What remains are [Obsolete] warnings + UA00xx analyzer diagnostics.
4. Apply auto-fixes in the IDE or from the command line:

   dotnet format analyzers <solution>.sln \
       --diagnostics UA0002 UA0003 UA0004 UA0005 UA0006 UA0007 UA0008 \
                     UA0009 UA0010 UA0012 UA0014 UA0019 UA0020 UA0022 \
       --severity warn

5. Walk the residual UA0001 / UA0011 / UA0015 / UA0018 / UA0021 diagnostics manually — they cover patterns that require human judgement (telemetry plumbing, async promotion, structural redesigns).
6. Remove the migration package. You are now on clean 2.0 with no shim dependency.

19-rule reference

Rule	Replaces	Default	Auto-fix
UA0001	Utils.Trace / Utils.LogX	Info	No (telemetry plumbing requires manual review)
UA0002	Removed <Type>Collection wrappers	Warning	Yes (→ List<T> / ArrayOf<T>)
UA0003	x == null on now-struct built-ins	Warning	Yes (→ x.IsNull)
UA0004	?. on now-struct built-ins	Warning	Yes (drop the ?)
UA0005	byte[] where ByteString is expected	Warning	Yes (append .ToByteString())
UA0006	new Variant(object|DateTime|Guid|byte[])	Warning	Yes (→ Variant.From(...))
UA0007	new NodeId(string) / new ExpandedNodeId(string)	Warning	Yes (→ Parse)
UA0008	Session.Call(..., params object[])	Warning	Yes (wrap with Variant.From)
UA0009	[DataContract] / [DataMember] on config extensions	Warning	Yes (→ [DataType] / [DataTypeField])
UA0010	using / Dispose on CertificateIdentifier / UserIdentity / IUserIdentityTokenHandler	Warning	Yes (drop the disposable)
UA0011	Sync IUserIdentityTokenHandler.{Encrypt,Decrypt,Sign,Verify}	Info	No (async promotion required)
UA0012	CertificateFactory.* static helpers	Warning	Yes (→ instance methods)
UA0014	DataValue.IsGood(dv) static helper	Warning	Yes (→ dv.IsGood)
UA0015	Sync / APM members on GDS / LDS clients	Info	No (async promotion required)
UA0018	CertificateIdentifier.Certificate getter	Info	No (→ LoadCertificate2Async)
UA0019	new DataValue(StatusCode[, ts])	Warning	Yes (→ object-initializer form)
UA0020	EncodeableFactory.GlobalFactory / Create()	Warning	Yes (→ ServiceMessageContext.Factory / Fork())
UA0021	CertificateValidator / CertificateValidationEventArgs (structural rename)	Info	No (see migration guide §Certificate validation)
UA0022	ApplicationConfiguration.CertificateValidator / ServerBase.CertificateValidator property rename	Warning	Yes (→ .CertificateManager)

What the Core (shim) DLL covers

Opc.Ua.MigrationAnalyzer.Core.dll ships obsolete extension members (using the C# 14 extension keyword) so 1.5.378 call sites continue to compile:

• Moved obsolete extensions the 1.6 libraries no longer carry inline: NodeId / Variant / DataValue null-check helpers, Session sync helpers, Subscription sync helpers, ApplicationInstance helpers, ServerBase.Start / Stop, TransportChannel APM (BeginX / EndX), ChannelBase static factory methods, etc.
• New shims for genuinely-removed members: EncodeableFactory.GlobalFactory, CertificateIdentifier.Certificate (throws), sync wrappers for IUserIdentityTokenHandler.{Encrypt,Decrypt,Sign,Verify}, sync + APM wrappers for the GDS / LDS client APIs, GlobalDiscoverySampleServer 1.5.378-shape ctor (in-tree Libraries/Opc.Ua.Gds.Server.Common/).

⚠️ The sync shims wrap their *Async counterparts via Task.Run(…).GetAwaiter().GetResult(). Intended as a migration aid only — port to await before shipping.

What the shim cannot cover

Source-level changes the shim has no syntactic foothold for — use the listed analyzer fix:

• == null / != null on now-struct types — UA0003
• ?. on now-struct types — UA0004
• using var x = new CertificateIdentifier(...) — UA0010
• [DataContract] / [DataMember] on configuration extensions — UA0009
• Removed <Type>Collection wrappers — UA0002
• CertificateValidator type rename — UA0021 (manual — structural rewrite)

Repo layout

Tools/Opc.Ua.MigrationAnalyzer/                # analyzer DLL
  Analyzers/UA00xxAnalyzer.cs                  # 19 DiagnosticAnalyzer impls
  Diagnostics/{DiagnosticIds,Descriptors,WellKnownProperties}.cs
  Helpers/{SymbolExtensions,UaSymbols}.cs
  Opc.Ua.MigrationAnalyzer.nuspec              # ships all 3 DLLs
  OPCFoundation.NetStandard.Opc.Ua.MigrationAnalyzer.props
  NugetREADME.md

Tools/Opc.Ua.MigrationAnalyzer.CodeFixer/      # code-fix DLL
  CodeFixes/UA00xxCodeFix.cs                   # 14 CodeFixProvider impls
  (shares Diagnostics + Helpers via <Compile Link=...> to avoid restore cycle)

Tools/Opc.Ua.MigrationAnalyzer.Core/           # shim DLL (multi-TFM)
  Client/, Configuration/, Core/, Gds.Client.Common/, Types/
  Marker/OpcUaShimAttribute.cs                 # tags each shim member with its UA rule id
  Properties/, readme.md

Tools/Roslyn.slnx                              # solution for SourceGen + MigrationAnalyzer projects

Tests/Opc.Ua.MigrationAnalyzer.Tests/          # 107 analyzer tests (NUnit + Microsoft.CodeAnalysis.Testing)
Tests/Opc.Ua.MigrationAnalyzer.Core.Tests/     # 13 shim tests (10 active + 3 environment-skipped)

Documentation updates

• Docs/MigrationGuide.md — adds a "Automate the migration" callout pointing at the new package.
• .github/agents/opcua-v20-migration.agent.md — rewritten so the first step is installing the migration package; the 14-section categorical reference is preserved as a fallback for patterns the analyzers can't cover. Adds a TreatWarningsAsErrors recipe and a "known compatibility gaps" section for legacy .NET Framework WinForms projects (which don't honour Directory.Build.targets PackageReference injection).

Central package pinning

Directory.Packages.props pins Microsoft.CodeAnalysis.* (Common, CSharp, CSharp.Workspaces, Workspaces.Common) to 4.14.0 — the stable analyzer API surface. The earlier 5.3 pin was the csc-internal version, which is not safe for analyzer hosts.

Dogfooded against OPCFoundation/UA-.NETStandard-Samples

The full 42-sample dogfood pass surfaced a critical analyzer-loader bug: the analyzer DLL initially co-shipped its code-fix providers in one assembly, which transitively referenced Microsoft.CodeAnalysis.Workspaces.dll. csc.exe's analyzer host ships only Microsoft.CodeAnalysis.dll + CSharp.dll in its bincore and silently swallows load failures — net result: zero diagnostics across all samples even though /analyzer: was on the csc command line. Fix landed in commit 861fa6ee1:

1. Split the assembly: analyzer in Opc.Ua.MigrationAnalyzer.dll (Workspaces-free, csc-safe), code-fixes in Opc.Ua.MigrationAnalyzer.CodeFixer.dll (Workspaces-aware, loaded only in IDE / dotnet format).
2. Downgrade to Roslyn 4.14 — the stable analyzer API. Microsoft.CodeAnalysis.CSharp 5.x is the csc compiler version and not appropriate for analyzers.
3. /p:ReportAnalyzer=true confirms all 19 analyzers initialise and execute on real consumer code.

Additional dogfood findings documented in the migration agent's "known compatibility gaps" section:

• Legacy WinForms .Net4 sample projects use pre-SDK MSBuild XML (xmlns="…/2003") and ignore Directory.Build.targets <PackageReference> injection — consumers in this format must add the migration package to their csproj inline. The dotnet build resx-tooling failure (MSB3822 / MSB3823) on these projects is unrelated to this PR; users must build them with full MSBuild.exe.
• Reference Server.csproj depends on the unpublished OPCFoundation.NetStandard.Opc.Ua.Quickstarts.Servers meta-package; consumers must switch to a ProjectReference against Applications/Quickstarts.Servers.

Packaging design notes

• Hand-authored nuspec (because the SDK-pack flow can't ship two analyzer DLLs + a six-TFM shim from a single csproj). All 6 OPC UA runtime package dependencies are declared per-TFM-group.
• build/OPCFoundation.NetStandard.Opc.Ua.MigrationAnalyzer.props is auto-imported by NuGet (file name must match package id exactly) and injects both analyzer DLLs as <Analyzer> items — this works around the hand-authored nuspec not auto-registering analyzers/dotnet/cs/ assets.
• DiagnosticIds.cs / DiagnosticDescriptors.cs / WellKnownProperties.cs / Helpers/*.cs are shared via <Compile Link=…> between the analyzer and code-fixer projects to break what would otherwise be a NuGet restore cycle (CodeFixer ProjectReferences the analyzer for shared constants; analyzer's pack pipeline MSBuild-invokes the CodeFixer build).
• Opc.Ua.MigrationAnalyzer.Core is multi-TFM (net472, net48, netstandard2.1, net8.0, net9.0, net10.0) and non-packable on its own; the parent migration package's nuspec consumes each TFM's DLL by path.

Verification

• dotnet build UA.slnx -c Debug — 0 errors (572 pre-existing CA2007 / NU1702 warnings).
• dotnet test Tests/Opc.Ua.MigrationAnalyzer.Tests — 107 / 107 analyzer + code-fix tests pass on net10.0.
• dotnet test Tests/Opc.Ua.MigrationAnalyzer.Core.Tests — 10 / 10 active shim tests + 3 skipped (environment-dependent).
• dotnet pack Tools/Opc.Ua.MigrationAnalyzer/Opc.Ua.MigrationAnalyzer.csproj — produces a single .nupkg with analyzers/dotnet/cs/{Opc.Ua.MigrationAnalyzer.dll, Opc.Ua.MigrationAnalyzer.CodeFixer.dll} + 6-TFM lib/<tfm>/Opc.Ua.MigrationAnalyzer.Core.dll.
• Analyzer DLL ref check confirms it references only Microsoft.CodeAnalysis 4.14.0 + Microsoft.CodeAnalysis.CSharp 4.14.0 — Workspaces-free, csc-safe.

Types of changes

• New feature (non-breaking change which adds functionality)
• Documentation update
• Bug fix
• Breaking change

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ marcschier
❌ Copilot
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[codecov]

Codecov Report

❌ Patch coverage is 70.49180% with 18 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.12%. Comparing base (01d7162) to head (0a019c8).

Files with missing lines	Patch %	Lines
Libraries/Opc.Ua.Server/Server/StandardServer.cs	0.00%	7 Missing ⚠️
...ore/Security/Certificates/CertificateIdentifier.cs	0.00%	4 Missing ⚠️
...raries/Opc.Ua.Configuration/ApplicationInstance.cs	57.14%	1 Missing and 2 partials ⚠️
...igrationAnalyzer.Core/Marker/OpcUaShimAttribute.cs	0.00%	3 Missing ⚠️
...yzer.Core/Core/Types/Encoders/EncodeableFactory.cs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3820      +/-   ##
==========================================
- Coverage   71.13%   71.12%   -0.01%     
==========================================
  Files         778      781       +3     
  Lines      143274   143329      +55     
  Branches    24234    24241       +7     
==========================================
+ Hits       101918   101946      +28     
- Misses      33005    33026      +21     
- Partials     8351     8357       +6     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.