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

The plugin bundles a snapshot of every thematic migration sub-doc under references/stack-migration/. Use those local resources for the migration workflow; they remain available offline and do not change underneath an installed plugin. The upstream links at the end are optional references for checking newer repository changes.

Context-efficiency rule. The full migration content is no longer in a single document; it is split across thematic sub-docs in references/stack-migration/. Match the user's symptom to a row below and load the single sub-doc named in that row. For UA0024–UA0026 or UA0028, load only the matching section of references/analyzer-rules.md; it contains the cross-cutting exposed-lock guidance without loading the entire Migration Guide.

If the user's symptom does not obviously map to one row, read references/stack-migration/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 26 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 12 manual rules — UA0001 (telemetry plumbing), UA0011 / UA0015 (sync→async promotion), UA0018 (cert load refactor), UA0021 (CertificateValidator structural rewrite), and UA0023–UA0028 plus UA0030 (PubSub, removed exposed-lock APIs, and the internalized server subscription publish pipeline).
• Treat UA0029-tagged obsolete warnings as manual work too. The runtime shim marks moved SecurityPolicies statics, but no analyzer currently emits UA0029; migrate the CS0618 sites to ISecurityPolicyRegistry.
• 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.0-preview.*"
                    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 UA0001 / UA0011 / UA0015 / UA0018 / UA0021, UA0023-UA0028, and
#    UA0030 by hand, plus CS0618 SecurityPolicies calls tagged UA0029.
#    See references/migration-patterns.md and the bundled sessions/subscriptions
#    guide for the categorical playbooks.

# 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.0-preview.*
• 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, UA0023–UA0028, and UA0030 manual residuals resolved
• SecurityPolicies obsolete warnings tagged UA0029 migrated manually
• [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.
• Generated <Type>Collection shims are temporary public types. They keep legacy public signatures compiling during migration, but disappear when the analyzer package is removed. Migrate every public signature and call site to List<T> / ArrayOf<T> before removing the package.
• 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.

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 26 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:

Runtime-shim-only migration marker:

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 a public 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.
• Consumer-source <UserType>Collection patterns (model-compiler output, application-defined structures, etc.) are resolved by stripping the Collection suffix and looking up the short name across source declarations via Compilation.GetSymbolsWithName. Standard metadata then falls back to exact System.<Type> and Opc.Ua.<Type> names. Other metadata, zero matches, or multiple source matches produce MIG01.
• Implicit conversion to ArrayOf<TElement> on every generated type so 2.0 APIs that took ArrayOf<T> keep accepting the shim instance.
• public sealed — legacy public signatures continue compiling while the package is installed. The type remains [Obsolete] and must not become a permanent public dependency.

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 11 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;UA0023;UA0024;UA0025;UA0026;UA0027;UA0028;UA0030</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.
• Public APIs can continue returning a generated <Type>Collection while the package is installed, but those temporary types disappear with the package. Migrate the public surface to List<T> / ArrayOf<T> before removal.

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)

Optional current upstream docs

• docs/MigrationGuide.md — current human-facing landing page and cross-cutting notes.
• docs/migrate/2.0.x/README.md — current upstream migration index.
• docs/migrate/2.0.x/ — current versions of the thematic docs bundled under references/stack-migration/.
• tools/Opc.Ua.MigrationAnalyzer/NugetREADME.md — the package's own README, shipped inside the NuGet.