opcua-v20-migration

OPC UA .NET Standard 1.5.378 → 2.0 Migration

Upgrade existing OPC UA .NET Standard consumer projects from 1.5.378 (master378) to 2.0.x (master). The skill assumes you already have a working 1.5.378 codebase; it does not teach OPC UA from scratch.

Migration sub-doc index — load only what you need

Context-efficiency rule. The full migration content is no longer in a single ~150 KB document; it is split across 12 thematic sub-docs under docs/migrate/2.0.x/. Do not load docs/MigrationGuide.md into context — it is now a thin landing page. Instead, match the user's symptom to a row below and load the single sub-doc named in that row.

If the user's symptom does not obviously map to one row, read docs/migrate/2.0.x/README.md (small — the same table plus a short intro) and pick from there. Avoid loading multiple sub-docs unless the symptom genuinely spans two areas (for example, node-states.md and types.md when a NodeManager runs into both INodeManager3 adoption and Variant-for-object API changes).

Level 1: Quick Start (5 minutes)

What you'll do

Install one NuGet, bump the OPC UA package versions, build once, apply the analyzer auto-fixes, walk the handful of manual residuals, then remove the migration NuGet. The package ships three Roslyn components and a runtime compat shim that together cover most mechanical migration patterns automatically.

Core principles

• Install before editing. Get the migration NuGet into the project before you start fixing build errors. The source generator turns CS0246 ("type <Type>Collection not found") into [Obsolete] warnings + UA0002 diagnostics, and the runtime shim turns "method removed" errors into [Obsolete] warnings too. Edit a working build, not a broken one.
• Let tooling do the mechanical work. 14 of the 19 UA00xx rules have auto-fixes — apply them via the IDE quick-fix or dotnet format analyzers before opening a single file by hand.
• Reserve human judgement for the 5 manual rules — UA0001 (telemetry plumbing), UA0011 / UA0015 (sync→async promotion), UA0018 (cert load refactor), UA0021 (CertificateValidator structural rewrite).
• Remove the migration NuGet at the end. It is a PrivateAssets="all" build-only dependency; once warning-free, drop the reference and you're on clean 2.0 with zero shim dependency.

Quick reference

<!-- 1. In every csproj that references OPCFoundation.NetStandard.Opc.Ua.*, bump
        the OPC UA package version and add this one extra reference: -->
<ItemGroup>
  <PackageReference Include="OPCFoundation.NetStandard.Opc.Ua.MigrationAnalyzer"
                    Version="2.0.*-*"
                    PrivateAssets="all" />
</ItemGroup>

# 2. Restore + build. Code that was hard-broken on 1.5.378 → 2.0 now compiles
#    with [Obsolete] warnings + UA00xx + (rarely) MIG01 diagnostics.
dotnet restore
dotnet build

# 3. Apply all auto-fix rules in one pass:
dotnet format analyzers <YourSolution>.sln \
    --diagnostics UA0002 UA0003 UA0004 UA0005 UA0006 UA0007 UA0008 \
                  UA0009 UA0010 UA0012 UA0014 UA0019 UA0020 UA0022 \
    --severity warn

# 4. Walk the residual UA0001 / UA0011 / UA0015 / UA0018 / UA0021 by hand.
#    See references/migration-patterns.md for the categorical playbook.

# 5. Once the build is warning-free, drop the package reference. You're done.

Essential checklist

• Every <PackageReference Include="OPCFoundation.NetStandard.Opc.Ua.*"> bumped to 2.0.*-*
• OPCFoundation.NetStandard.Opc.Ua.MigrationAnalyzer added as PrivateAssets="all" build-only dependency in every consumer project
• dotnet build succeeds (warnings allowed, errors fixed)
• dotnet format analyzers --diagnostics UA0002 … applied
• UA0001/UA0011/UA0015/UA0018/UA0021 manual residuals resolved
• [Obsolete] (CS0612/CS0618) warnings fixed, not suppressed
• MigrationAnalyzer package reference removed before merging

Common pitfalls

• Do not suppress [Obsolete] or UA00xx warnings. Obsolete API will be removed in the next minor 2.0 release; if you <NoWarn> it now, your build will break on upgrade.
• Public APIs returning a generated <Type>Collection shim trip CS0050 ("inconsistent accessibility"). The generator emits internal types by design. The fix is to migrate the public-API signature to List<T> / ArrayOf<T> first; internal call sites can keep the shim while you iterate.
• Legacy .NET Framework xmlns="http://schemas.microsoft.com/developer/msbuild/2003" projects ignore Directory.Build.targets <PackageReference> injection. Add the migration package directly into the legacy csproj's existing <ItemGroup>.
• TreatWarningsAsErrors=true blocks the warning-driven workflow. Use the NoWarn recipe in assets/Directory.Build.targets.example.xml for the migration window, then peel each entry back as you fix the rule.
• The legacy Quickstarts.Servers meta-package does not exist on 2.0. If your project depends on it, switch to a <ProjectReference> to samples/Quickstarts.Servers or to an equivalent project of your own.

---

Level 2: Implementation (30 minutes)

What the migration package ships

The single OPCFoundation.NetStandard.Opc.Ua.MigrationAnalyzer NuGet contains three Roslyn components plus a runtime compat shim:

The 19 analyzer rules at a glance

The full table with default severity, replaces, auto-fix status, and before/after examples lives in references/analyzer-rules.md. One-line summary of where each lands in the workflow:

Plus one generator-only diagnostic:

Source-generated <Type>Collection shims

When 2.0 deleted the <Type>Collection wrapper types, every consumer call site like new Int32Collection { 1, 2, 3 } and IList<NodeIdCollection> nodes became a hard CS0246 ("type or namespace not found"). The package's source generator (MigrationGenerator) closes this gap: for every short name ending in Collection that doesn't bind, it emits an internal sealed [Obsolete] class <Name>Collection : List<TElement> into the consumer's compilation.

• Built-in catalog (rename overrides) pins element types that renamed across the 1.5.378 → 2.0 boundary, where semantic lookup would resolve to the wrong type or fail with ambiguity: DateTime→DateTimeUtc, Guid→Uuid, byte[]→ByteString, XmlElement→System.Xml.XmlElement (the latter disambiguates against the new Opc.Ua.XmlElement). The generator uses these over whatever the consumer's compilation resolves.
• Arbitrary <UserType>Collection patterns (model-compiler output, vendor structures, etc.) are resolved by stripping the Collection suffix and looking up the resulting short name in the consumer's compilation via Compilation.GetSymbolsWithName. Exactly one match → emit; zero or many → MIG01.
• Implicit conversion to ArrayOf<TElement> on every generated type so 2.0 APIs that took ArrayOf<T> keep accepting the shim instance.
• internal sealed — the shim never leaks through the consumer's public API surface (intentional; see "Common pitfalls" above for the CS0050 consequence).

Deep-dive: references/source-generator.md.

Runtime compatibility shim

Opc.Ua.MigrationAnalyzer.Core.dll re-exposes the 1.5.378 obsolete extension surface (via C# 14 extension members) so 1.5.378-style call sites continue to compile. Coverage and the sync-over-async caveat are documented in references/runtime-shim.md.

Manual residuals — priority order

For the 5 rules without auto-fixes and the patterns the analyzer doesn't catch at all (e.g. Variant.Value setter type changes, BaseVariableState.Value becoming Variant, INodeManager covariant return changes), apply fixes in this order to minimize cascading errors:

1. Source generation project-file changes (remove pre-generated .Classes.cs, add <AdditionalFiles> for design files)
2. Null comparisons on now-struct types (UA0003 / UA0004 cover most; manual for unusual patterns)
3. Collection types (UA0002 covers most; manual for IList<T> → ArrayOf<T> signature shape)
4. Built-in type replacements (DateTime→DateTimeUtc, Guid→Uuid, byte[]→ByteString)
5. Variant / DataValue / ExtensionObject API changes
6. Encoder / Decoder signature updates (generic methods + ByteString)
7. NodeState generic PropertyState<T> → builder pattern
8. Server-side NodeManager migration to AsyncCustomNodeManager
9. Client-side Session / Subscription changes
10. User identity token handler pattern (AsTokenHandler() + disposable handlers)

Full categorical playbook for each layer is in references/migration-patterns.md.

TreatWarningsAsErrors recipe

If your project sets <TreatWarningsAsErrors>true</TreatWarningsAsErrors> and you can't relax it during the migration window, exclude the migration diagnostics from the failure set in your Directory.Build.targets:

<PropertyGroup>
  <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  <NoWarn>$(NoWarn);CS0612;CS0618;MIG01;UA0001;UA0002;UA0003;UA0004;UA0005;UA0006;UA0007;UA0008;UA0009;UA0010;UA0011;UA0012;UA0014;UA0015;UA0018;UA0019;UA0020;UA0021;UA0022</NoWarn>
</PropertyGroup>

Pasteable file at assets/Directory.Build.targets.example.xml. Peel each entry back as you fix the rule; drop the whole block once the MigrationAnalyzer package is removed.

Known compatibility gaps

• Legacy .NET Framework WinForms projects in pre-SDK MSBuild XML format (xmlns="…/2003") — <PackageReference> injection via Directory.Build.targets is silently ignored; the migration package must be added inline to each csproj.
• The OPCFoundation.NetStandard.Opc.Ua.Quickstarts.Servers meta-package is not published on 2.0 — consumers must switch to a <ProjectReference> to samples/Quickstarts.Servers or an equivalent first-party project.
• Public APIs returning a <Type>Collection will hit CS0050 because the generator's shim is internal by design — migrate the public surface to List<T> / ArrayOf<T> first.

Full list of dogfood-discovered gaps in references/known-gaps.md.

Compatibility matrix

Target framework, .NET SDK, and Roslyn API requirements (and how to verify analyzers actually loaded under csc.exe) are documented in references/compatibility-matrix.md.

---

Level 3: Mastery (Extended Learning)

The references/ and scripts/ folders in this skill contain the extended material. Load them on demand via your agent runtime's read_skill_resource / run_skill_script tools:

References (load via read_skill_resource)

Scripts (invoke via run_skill_script)

Assets (pasteable templates)

Canonical upstream docs

• docs/MigrationGuide.md — the human-facing migration guide landing page (~3 KB; intentionally small, just an index across versions).
• docs/migrate/2.0.x/README.md — the 2.0 migration index + the same symptom → sub-doc table this skill uses.
• docs/migrate/2.0.x/ — the 12 thematic sub-docs (telemetry, packages, source-generation, types, encoders, node-states, identity, certificates, configuration, sessions-subscriptions, alarms-model-change, timeprovider).
• tools/Opc.Ua.MigrationAnalyzer/NugetREADME.md — the package's own README, shipped inside the NuGet.