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.
| When the user hits… |
Load only |
CS0029 / CS1503 / CS0266 on NodeId, Variant, DataValue, ExtensionObject, QualifiedName, LocalizedText, ArrayOf<T> / MatrixOf<T>, ByteString, StatusCode, XmlElement, EnumValue, or [Obsolete] on built-in type APIs (analyzers UA0002–UA0008, UA0014, UA0019) |
types.md |
Utils.LogX, Utils.Trace, static logger helpers (Utils.SetLogger / Utils.SetLogLevel removed), ITelemetryContext constructor parameter shape per type, OLD-vs-NEW logger snippets, fluent AddOpcUa().AddLogging().AddMetrics() registration, breaking-changes inventory across Core / Configuration / Client / Server / PubSub / Certificate / Transport, migration utilities (DefaultTelemetry, Telemetry.NullLogger, Utils.Fallback.Logger) |
telemetry.md |
Package upgrades, TFM changes, Newtonsoft.Json removal from Opc.Ua.Core, new published packages |
packages.md |
Source-generated *Collection shims, NodeManager generator, default of bool properties, project structure |
source-generation.md |
IEncodeableFactoryBuilder, IType, JSON / XML / binary encoders, EncodeableFactory.GlobalFactory, IJsonEncodeable, ComplexTypes namespace move |
encoders.md |
Custom NodeManagers, NodeState clone / read / write helpers, Clone → CreateCopy, OnAfterCreate(CancellationToken), FindChild / CreateChild NodeId assignment, INodeManager3, INodeCache.InvalidateNode, generics on BaseVariableState / BaseVariableTypeState, predefined-node processing, lock (node) on a NodeState, NodeBrowser.DataLock (UA0027) |
node-states.md |
IUserIdentityTokenHandler, IClientIdentityProvider, IUserTokenAuthenticator, IAccessTokenProvider, ITokenIssuer, IIdentityClaims, caller-supplied secrets, secret store |
identity.md |
CertificateValidator rename (UA0021), ref-counted Certificate wrapper, CertificateManager, ICertificateProvider, obsoleted X509Certificate2 direct-exposure APIs, PushManagement transactions (ApplyChanges-gated TrustList updates) |
certificates.md |
ApplicationConfiguration changes, Data-Contract serializer removal, MinMetadataSamplingInterval → MinSupportedSamplingInterval, ParseExtension / UpdateExtension signature, session / browser state persistence |
configuration.md |
Session → ManagedSession, V2 subscription engine, GDS-client Task → ValueTask modernisation, removed obsolete GDS APIs, durable subscriptions, removed ReverseConnectClientCollection, IMessageSocket, or TransportBindings APIs |
sessions-subscriptions.md |
UaPubSubApplication.Create*, IUaPubSubConnection, UaPubSubConfigurator, IUaPublisher, AMQP transport, JsonEncodingMode.Reversible / NonReversible, PubSub JSON encoder changes, DataSetFieldContentMask RawData / timestamp behaviour |
pubsub.md |
AlarmConditionState state-transition behaviour, auto-emitted GeneralModelChangeEvent, ModelChangeAggregator, INodeCache.InvalidateNode triggered by model change |
alarms-model-change.md |
DateTime.UtcNow, Timer, deterministic-time tests, System.TimeProvider adoption |
timeprovider.md |
ITransportListener.Open / Close removed, ReverseConnectManager.StartService / Dispose obsolete, reverse-connect DI/provider migration, custom ITransportListenerFactory / ITransportListenerCertificateRotation implementers need the new async method names |
transport-listener-async.md |
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
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:
| Component |
Where |
Loaded by |
Purpose |
Opc.Ua.MigrationAnalyzer.dll |
analyzers/dotnet/roslyn4.14/cs/ and roslyn5.0/cs/ |
csc.exe and IDE |
26 DiagnosticAnalyzers through UA0030 (excluding UA0013, UA0016, UA0017, and UA0029). No Workspaces reference, csc-safe. |
Opc.Ua.MigrationAnalyzer.CodeFixer.dll |
analyzers/dotnet/roslyn4.14/cs/ and roslyn5.0/cs/ |
Workspaces-aware hosts only (Visual Studio, Rider, dotnet format analyzers) |
14 CodeFixProviders. |
Opc.Ua.MigrationAnalyzer.Generator.dll |
analyzers/dotnet/roslyn4.14/cs/ and roslyn5.0/cs/ |
csc.exe and IDE |
IIncrementalGenerator that emits public sealed [Obsolete] class <Name>Collection : List<TElement> shims into the consumer compilation for every <Type>Collection reference that fails to bind. |
Opc.Ua.MigrationAnalyzer.Core.dll |
lib/<tfm>/ × 6 TFMs (net472, net48, netstandard2.1, net8.0, net9.0, net10.0) |
Runtime |
Re-supplies the obsolete extension surface 2.0 moved or removed so 1.5.378 call sites continue to compile with [Obsolete] warnings. |
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:
| Rule |
Default |
Auto-fix |
One-liner |
| UA0001 |
Info |
— |
Utils.Trace → ILogger via ITelemetryContext (manual: pick log level + category) |
| UA0002 |
Warning |
✅ |
<Type>Collection → List<T>; manually use ArrayOf<T> at applicable API boundaries |
| UA0003 |
Warning |
✅ |
x == null on now-struct built-ins → x.IsNull |
| UA0004 |
Warning |
✅ |
x?.M() on now-struct built-ins → drop the ? |
| UA0005 |
Warning |
✅ |
byte[] where ByteString expected → .ToByteString() |
| UA0006 |
Warning |
✅ |
new Variant(object|DateTime|Guid|byte[]) → Variant.From(...) |
| UA0007 |
Warning |
✅ |
new NodeId(string) / new ExpandedNodeId(string) → Parse |
| UA0008 |
Warning |
✅ |
Session.Call(..., params object[]) → wrap each arg with Variant.From |
| UA0009 |
Warning |
✅ |
[DataContract]/[DataMember] → [DataType]/[DataTypeField] on config |
| UA0010 |
Warning |
✅ |
using/Dispose on CertificateIdentifier/UserIdentity/IUserIdentityTokenHandler → drop disposable |
| UA0011 |
Info |
— |
Sync IUserIdentityTokenHandler.{Encrypt,Decrypt,Sign,Verify} → *Async (manual: async promotion) |
| UA0012 |
Warning |
✅ |
CertificateFactory.* static → DefaultCertificateFactory.Instance.* |
| UA0014 |
Warning |
✅ |
DataValue.IsGood(dv) static → dv.IsGood property |
| UA0015 |
Info |
— |
Sync / APM members on GDS / LDS clients → *Async (manual: async promotion) |
| UA0018 |
Info |
— |
CertificateIdentifier.Certificate getter → CertificateIdentifierResolver.ResolveAsync |
| UA0019 |
Warning |
✅ |
new DataValue(StatusCode[, ts]) → DataValue.FromStatusCode(...) |
| UA0020 |
Warning |
✅ |
EncodeableFactory.GlobalFactory / .Create() → ServiceMessageContext.Factory / .Fork() |
| UA0021 |
Info |
— |
CertificateValidator / CertificateValidationEventArgs (structural rename — see manual playbook) |
| UA0022 |
Warning |
✅ |
ApplicationConfiguration.CertificateValidator / ServerBase.CertificateValidator → .CertificateManager |
| UA0023 |
Warning |
— |
Legacy PubSub top-level types → IPubSubApplication / builder and DI APIs |
| UA0024 |
Warning |
— |
Exposed diagnostics locks → owner-side update/read methods |
| UA0025 |
Warning |
— |
ILocalNode.DataLock / Node.DataLock → node-owned synchronization |
| UA0026 |
Warning |
— |
BaseVariableValue.Lock → caller-owned System.Threading.Lock |
| UA0027 |
Warning |
— |
NodeBrowser.DataLock → single-consumer browser without external locking |
| UA0028 |
Warning |
— |
ApplicationConfiguration.PropertiesLock → concurrent properties APIs |
| UA0030 |
Warning |
— |
Server ISubscription publish-pipeline members / SessionPublishQueue → service and manager APIs |
Runtime-shim-only migration marker:
| Marker |
Signal |
Auto-fix |
One-liner |
| UA0029 |
CS0618 from shim |
— |
SecurityPolicies lookup/crypto statics → ISecurityPolicyRegistry or SecurityPolicies.Default; no analyzer currently reports UA0029 |
Plus one generator-only diagnostic:
| ID |
Source |
Default |
Triggers |
| MIG01 |
Opc.Ua.MigrationAnalyzer.Generator |
Warning |
The generator can't uniquely resolve the element type for a <Foo>Collection reference. It discovers consumer source declarations plus exact System.<Type> / Opc.Ua.<Type> metadata names; other zero/ambiguous cases require a manual List<T> / ArrayOf<T> migration or an explicitly defined wrapper. See references/source-generator.md. |
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:
- Source generation project-file changes (remove pre-generated
.Classes.cs, add <AdditionalFiles> for design files)
- Null comparisons on now-struct types (
UA0003 / UA0004 cover most; manual for unusual patterns)
- Collection types (
UA0002 covers most; manual for IList<T> → ArrayOf<T> signature shape)
- Built-in type replacements (
DateTime→DateTimeUtc, Guid→Uuid, byte[]→ByteString)
Variant / DataValue / ExtensionObject API changes
- Encoder / Decoder signature updates (generic methods +
ByteString)
- NodeState generic
PropertyState<T> → builder pattern
- Server-side NodeManager migration to
AsyncCustomNodeManager
- Client-side
Session / Subscription changes
- 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)
| File |
Token budget |
When to load |
references/package-install.md |
~1.5K |
When the user asks "how do I install" or hits PackageReference / Directory.Build.targets resolution issues |
references/analyzer-rules.md |
~3K |
When the user asks about a specific UA00xx warning or wants the full rule reference |
references/source-generator.md |
~2K |
When MIG01 fires or the user asks how the <Type>Collection shims work |
references/runtime-shim.md |
~2K |
When a 1.5.378 extension call still compiles but is flagged [Obsolete], or when async-promotion guidance is needed |
references/migration-patterns.md |
~5K |
The categorical playbook for the 14 manual layers — primary fallback for residuals |
references/known-gaps.md |
~1.5K |
When legacy WinForms, generated-shim lifetime, or analyzer-loading issues surface |
references/compatibility-matrix.md |
~1K |
When verifying the analyzer actually loaded under csc.exe vs IDE, or when picking a TFM |
references/stack-migration/README.md |
index |
Bundled offline snapshot of all 15 thematic migration docs; load only the symptom-matched file |
Scripts (invoke via run_skill_script)
| File |
Purpose |
scripts/apply-codefixes.ps1 |
PowerShell wrapper around dotnet format analyzers --diagnostics UA0002 … --severity warn. Auto-discovers .sln/.slnx, reports before/after warning counts. |
Assets (pasteable templates)
| File |
Purpose |
assets/PackageReference.example.xml |
Single <PackageReference> snippet for a consumer csproj. |
assets/Directory.Build.targets.example.xml |
Multi-project <NoWarn> recipe for TreatWarningsAsErrors=true. |
Optional current upstream docs
1---2name: opcua-v20-migration3description: |4 Migrate OPC UA .NET Standard applications from version 1.5.378 to5 version 2.0.x. Walks consumers through installing the6 OPCFoundation.NetStandard.Opc.Ua.MigrationAnalyzer NuGet (26 analyzers through7 UA0030, with UA0029 reserved for runtime-shim guidance, source-generated8 <Type>Collection shims, runtime compat shim), running9 `dotnet format analyzers` to apply auto-fixes, and walking the residual manual10 patterns. Use when asked to "migrate to v20", "update from 1.5.378", "fix11 v20 build errors", "migrate OPC UA code to 2.0", "update to new Variant API",12 "fix ArrayOf migration", "update NodeId readonly struct", "migrate from object13 to Variant", "fix CS0246 on <Type>Collection wrappers", "fix CS0246 on14 CertificateValidator", or "address UA00xx / MIG01 warnings". Sample triggers:15 user says "my project targets 1.5.378 and I need to update to v20"; user16 provides build errors after updating NuGet packages to 2.0; user asks "how do17 I update my custom NodeManager for v20?"; user says "fix all the CS002918 errors after upgrading to v20".19license: MIT20compatibility: |21 Requires .NET SDK 9.0.300+ (10.0.300+ for the `dotnet format analyzers`22 auto-fix pass), a C# project, and resolvable access to the23 OPCFoundation.NetStandard.Opc.Ua.MigrationAnalyzer NuGet package24 (v2.0.0-preview.*).25 IDE auto-fixes need a Workspaces-aware host (Visual Studio, Rider, or26 `dotnet format`). Generator + analyzers load in csc.exe too.27metadata:28 source: https://skillmd.com/skills/opcfoundation/opcua-v20-migration29 author: OPC Foundation30 version: "1.0.0"31 upstream: https://github.com/OPCFoundation/UA-.NETStandard32 canonical-docs: >-33 https://github.com/OPCFoundation/UA-.NETStandard/blob/master/docs/MigrationGuide.md;34 https://github.com/OPCFoundation/UA-.NETStandard/blob/master/docs/migrate/2.0.x/README.md;35 https://github.com/OPCFoundation/UA-.NETStandard/tree/master/docs/migrate/2.0.x;36 https://github.com/OPCFoundation/UA-.NETStandard/blob/master/tools/Opc.Ua.MigrationAnalyzer/NugetREADME.md37---3839# OPC UA .NET Standard 1.5.378 → 2.0 Migration4041Upgrade existing OPC UA .NET Standard consumer projects from 1.5.37842(`master378`) to 2.0.x (`master`). The skill assumes you already have a working431.5.378 codebase; it does not teach OPC UA from scratch.4445## Migration sub-doc index — load only what you need4647The plugin bundles a snapshot of every thematic migration sub-doc under48[`references/stack-migration/`](references/stack-migration/README.md). Use49those local resources for the migration workflow; they remain available50offline and do not change underneath an installed plugin. The upstream links51at the end are optional references for checking newer repository changes.5253**Context-efficiency rule.** The full migration content is no longer in54a single document; it is split across thematic sub-docs in55[`references/stack-migration/`](references/stack-migration/README.md).56Match the user's symptom to a row below and load the **single** sub-doc named57in that row. For `UA0024`–`UA0026` or `UA0028`, load only the matching section58of [`references/analyzer-rules.md`](references/analyzer-rules.md); it contains59the cross-cutting exposed-lock guidance without loading the entire Migration60Guide.6162| When the user hits… | Load only |63| --- | --- |64| `CS0029` / `CS1503` / `CS0266` on `NodeId`, `Variant`, `DataValue`, `ExtensionObject`, `QualifiedName`, `LocalizedText`, `ArrayOf<T>` / `MatrixOf<T>`, `ByteString`, `StatusCode`, `XmlElement`, `EnumValue`, or `[Obsolete]` on built-in type APIs (analyzers `UA0002`–`UA0008`, `UA0014`, `UA0019`) | [`types.md`](references/stack-migration/types.md) |65| `Utils.LogX`, `Utils.Trace`, static logger helpers (`Utils.SetLogger` / `Utils.SetLogLevel` removed), `ITelemetryContext` constructor parameter shape per type, OLD-vs-NEW logger snippets, fluent `AddOpcUa().AddLogging().AddMetrics()` registration, breaking-changes inventory across Core / Configuration / Client / Server / PubSub / Certificate / Transport, migration utilities (`DefaultTelemetry`, `Telemetry.NullLogger`, `Utils.Fallback.Logger`) | [`telemetry.md`](references/stack-migration/telemetry.md) |66| Package upgrades, TFM changes, `Newtonsoft.Json` removal from `Opc.Ua.Core`, new published packages | [`packages.md`](references/stack-migration/packages.md) |67| Source-generated `*Collection` shims, NodeManager generator, default of `bool` properties, project structure | [`source-generation.md`](references/stack-migration/source-generation.md) |68| `IEncodeableFactoryBuilder`, `IType`, JSON / XML / binary encoders, `EncodeableFactory.GlobalFactory`, `IJsonEncodeable`, `ComplexTypes` namespace move | [`encoders.md`](references/stack-migration/encoders.md) |69| Custom NodeManagers, `NodeState` clone / read / write helpers, `Clone` → `CreateCopy`, `OnAfterCreate(CancellationToken)`, `FindChild` / `CreateChild` NodeId assignment, `INodeManager3`, `INodeCache.InvalidateNode`, generics on `BaseVariableState` / `BaseVariableTypeState`, predefined-node processing, `lock (node)` on a `NodeState`, `NodeBrowser.DataLock` (`UA0027`) | [`node-states.md`](references/stack-migration/node-states.md) |70| `IUserIdentityTokenHandler`, `IClientIdentityProvider`, `IUserTokenAuthenticator`, `IAccessTokenProvider`, `ITokenIssuer`, `IIdentityClaims`, caller-supplied secrets, secret store | [`identity.md`](references/stack-migration/identity.md) |71| `CertificateValidator` rename (`UA0021`), ref-counted `Certificate` wrapper, `CertificateManager`, `ICertificateProvider`, obsoleted `X509Certificate2` direct-exposure APIs, PushManagement transactions (`ApplyChanges`-gated TrustList updates) | [`certificates.md`](references/stack-migration/certificates.md) |72| `ApplicationConfiguration` changes, Data-Contract serializer removal, `MinMetadataSamplingInterval` → `MinSupportedSamplingInterval`, `ParseExtension` / `UpdateExtension` signature, session / browser state persistence | [`configuration.md`](references/stack-migration/configuration.md) |73| `Session` → `ManagedSession`, V2 subscription engine, GDS-client `Task` → `ValueTask` modernisation, removed obsolete GDS APIs, durable subscriptions, removed `ReverseConnectClientCollection`, `IMessageSocket`, or `TransportBindings` APIs | [`sessions-subscriptions.md`](references/stack-migration/sessions-subscriptions.md) |74| `UaPubSubApplication.Create*`, `IUaPubSubConnection`, `UaPubSubConfigurator`, `IUaPublisher`, AMQP transport, `JsonEncodingMode.Reversible` / `NonReversible`, PubSub JSON encoder changes, `DataSetFieldContentMask` RawData / timestamp behaviour | [`pubsub.md`](references/stack-migration/pubsub.md) |75| `AlarmConditionState` state-transition behaviour, auto-emitted `GeneralModelChangeEvent`, `ModelChangeAggregator`, `INodeCache.InvalidateNode` triggered by model change | [`alarms-model-change.md`](references/stack-migration/alarms-model-change.md) |76| `DateTime.UtcNow`, `Timer`, deterministic-time tests, `System.TimeProvider` adoption | [`timeprovider.md`](references/stack-migration/timeprovider.md) |77| `ITransportListener.Open` / `Close` removed, `ReverseConnectManager.StartService` / `Dispose` obsolete, reverse-connect DI/provider migration, custom `ITransportListenerFactory` / `ITransportListenerCertificateRotation` implementers need the new async method names | [`transport-listener-async.md`](references/stack-migration/transport-listener-async.md) |7879If the user's symptom does not obviously map to one row, read80[`references/stack-migration/README.md`](references/stack-migration/README.md) (small —81the same table plus a short intro) and pick from there. Avoid loading82multiple sub-docs unless the symptom genuinely spans two areas (for83example, `node-states.md` *and* `types.md` when a NodeManager runs into84both `INodeManager3` adoption and `Variant`-for-`object` API changes).8586## Level 1: Quick Start (5 minutes)8788### What you'll do8990Install one NuGet, bump the OPC UA package versions, build once, apply the91analyzer auto-fixes, walk the handful of manual residuals, then remove the92migration NuGet. The package ships **three Roslyn components and a runtime93compat shim** that together cover most mechanical migration patterns94automatically.9596### Core principles9798- **Install before editing.** Get the migration NuGet into the project *before*99 you start fixing build errors. The source generator turns `CS0246` ("type100 `<Type>Collection` not found") into `[Obsolete]` warnings + `UA0002`101 diagnostics, and the runtime shim turns "method removed" errors into102 `[Obsolete]` warnings too. Edit a working build, not a broken one.103- **Let tooling do the mechanical work.** 14 of the 26 `UA00xx` rules have104 auto-fixes — apply them via the IDE quick-fix or `dotnet format analyzers`105 before opening a single file by hand.106- **Reserve human judgement for the 12 manual rules** — `UA0001` (telemetry107 plumbing), `UA0011` / `UA0015` (sync→async promotion), `UA0018` (cert load108 refactor), `UA0021` (`CertificateValidator` structural rewrite), and109 `UA0023`–`UA0028` plus `UA0030` (PubSub, removed exposed-lock APIs, and the110 internalized server subscription publish pipeline).111- **Treat `UA0029`-tagged obsolete warnings as manual work too.** The runtime112 shim marks moved `SecurityPolicies` statics, but no analyzer currently emits113 `UA0029`; migrate the `CS0618` sites to `ISecurityPolicyRegistry`.114- **Remove the migration NuGet at the end.** It is a `PrivateAssets="all"`115 build-only dependency; once warning-free, drop the reference and you're on116 clean 2.0 with zero shim dependency.117118### Quick reference119120```xml121<!-- 1. In every csproj that references OPCFoundation.NetStandard.Opc.Ua.*, bump122 the OPC UA package version and add this one extra reference: -->123<ItemGroup>124 <PackageReference Include="OPCFoundation.NetStandard.Opc.Ua.MigrationAnalyzer"125 Version="2.0.0-preview.*"126 PrivateAssets="all" />127</ItemGroup>128```129130```bash131# 2. Restore + build. Code that was hard-broken on 1.5.378 → 2.0 now compiles132# with [Obsolete] warnings + UA00xx + (rarely) MIG01 diagnostics.133dotnet restore134dotnet build135136# 3. Apply all auto-fix rules in one pass:137dotnet format analyzers <YourSolution>.sln \138 --diagnostics UA0002 UA0003 UA0004 UA0005 UA0006 UA0007 UA0008 \139 UA0009 UA0010 UA0012 UA0014 UA0019 UA0020 UA0022 \140 --severity warn141142# 4. Walk UA0001 / UA0011 / UA0015 / UA0018 / UA0021, UA0023-UA0028, and143# UA0030 by hand, plus CS0618 SecurityPolicies calls tagged UA0029.144# See references/migration-patterns.md and the bundled sessions/subscriptions145# guide for the categorical playbooks.146147# 5. Once the build is warning-free, drop the package reference. You're done.148```149150### Essential checklist151152- [ ] Every `<PackageReference Include="OPCFoundation.NetStandard.Opc.Ua.*">` bumped to `2.0.0-preview.*`153- [ ] `OPCFoundation.NetStandard.Opc.Ua.MigrationAnalyzer` added as `PrivateAssets="all"` build-only dependency in every consumer project154- [ ] `dotnet build` succeeds (warnings allowed, errors fixed)155- [ ] `dotnet format analyzers --diagnostics UA0002 …` applied156- [ ] `UA0001`/`UA0011`/`UA0015`/`UA0018`/`UA0021`, `UA0023`–`UA0028`, and `UA0030` manual residuals resolved157- [ ] `SecurityPolicies` obsolete warnings tagged `UA0029` migrated manually158- [ ] `[Obsolete]` (CS0612/CS0618) warnings fixed, **not** suppressed159- [ ] `MigrationAnalyzer` package reference removed before merging160161### Common pitfalls162163- **Do not suppress `[Obsolete]` or `UA00xx` warnings.** Obsolete API will be164 removed in the next minor 2.0 release; if you `<NoWarn>` it now, your build165 will break on upgrade.166- **Generated `<Type>Collection` shims are temporary public types.** They keep167 legacy public signatures compiling during migration, but disappear when the168 analyzer package is removed. Migrate every public signature and call site to169 `List<T>` / `ArrayOf<T>` before removing the package.170- **Legacy `.NET Framework` `xmlns="http://schemas.microsoft.com/developer/msbuild/2003"`171 projects ignore `Directory.Build.targets` `<PackageReference>` injection.** Add172 the migration package directly into the legacy csproj's existing `<ItemGroup>`.173- **`TreatWarningsAsErrors=true` blocks the warning-driven workflow.** Use the174 `NoWarn` recipe in `assets/Directory.Build.targets.example.xml` for the175 migration window, then peel each entry back as you fix the rule.176---177178## Level 2: Implementation (30 minutes)179180### What the migration package ships181182The single `OPCFoundation.NetStandard.Opc.Ua.MigrationAnalyzer` NuGet contains183**three Roslyn components plus a runtime compat shim**:184185| Component | Where | Loaded by | Purpose |186|---|---|---|---|187| `Opc.Ua.MigrationAnalyzer.dll` | `analyzers/dotnet/roslyn4.14/cs/` and `roslyn5.0/cs/` | csc.exe and IDE | 26 `DiagnosticAnalyzer`s through UA0030 (excluding UA0013, UA0016, UA0017, and UA0029). No `Workspaces` reference, csc-safe. |188| `Opc.Ua.MigrationAnalyzer.CodeFixer.dll` | `analyzers/dotnet/roslyn4.14/cs/` and `roslyn5.0/cs/` | Workspaces-aware hosts only (Visual Studio, Rider, `dotnet format analyzers`) | 14 `CodeFixProvider`s. |189| `Opc.Ua.MigrationAnalyzer.Generator.dll` | `analyzers/dotnet/roslyn4.14/cs/` and `roslyn5.0/cs/` | csc.exe and IDE | `IIncrementalGenerator` that emits `public sealed [Obsolete] class <Name>Collection : List<TElement>` shims into the consumer compilation for every `<Type>Collection` reference that fails to bind. |190| `Opc.Ua.MigrationAnalyzer.Core.dll` | `lib/<tfm>/` × 6 TFMs (`net472`, `net48`, `netstandard2.1`, `net8.0`, `net9.0`, `net10.0`) | Runtime | Re-supplies the obsolete extension surface 2.0 moved or removed so 1.5.378 call sites continue to compile with `[Obsolete]` warnings. |191192### The 26 analyzer rules at a glance193194The full table with default severity, replaces, auto-fix status, and195before/after examples lives in196[`references/analyzer-rules.md`](references/analyzer-rules.md). One-line summary197of where each lands in the workflow:198199| Rule | Default | Auto-fix | One-liner |200|---|---|---|---|201| **UA0001** | Info | — | `Utils.Trace` → `ILogger` via `ITelemetryContext` (manual: pick log level + category) |202| **UA0002** | Warning | ✅ | `<Type>Collection` → `List<T>`; manually use `ArrayOf<T>` at applicable API boundaries |203| **UA0003** | Warning | ✅ | `x == null` on now-struct built-ins → `x.IsNull` |204| **UA0004** | Warning | ✅ | `x?.M()` on now-struct built-ins → drop the `?` |205| **UA0005** | Warning | ✅ | `byte[]` where `ByteString` expected → `.ToByteString()` |206| **UA0006** | Warning | ✅ | `new Variant(object\|DateTime\|Guid\|byte[])` → `Variant.From(...)` |207| **UA0007** | Warning | ✅ | `new NodeId(string)` / `new ExpandedNodeId(string)` → `Parse` |208| **UA0008** | Warning | ✅ | `Session.Call(..., params object[])` → wrap each arg with `Variant.From` |209| **UA0009** | Warning | ✅ | `[DataContract]`/`[DataMember]` → `[DataType]`/`[DataTypeField]` on config |210| **UA0010** | Warning | ✅ | `using`/`Dispose` on `CertificateIdentifier`/`UserIdentity`/`IUserIdentityTokenHandler` → drop disposable |211| **UA0011** | Info | — | Sync `IUserIdentityTokenHandler.{Encrypt,Decrypt,Sign,Verify}` → `*Async` (manual: async promotion) |212| **UA0012** | Warning | ✅ | `CertificateFactory.*` static → `DefaultCertificateFactory.Instance.*` |213| **UA0014** | Warning | ✅ | `DataValue.IsGood(dv)` static → `dv.IsGood` property |214| **UA0015** | Info | — | Sync / APM members on GDS / LDS clients → `*Async` (manual: async promotion) |215| **UA0018** | Info | — | `CertificateIdentifier.Certificate` getter → `CertificateIdentifierResolver.ResolveAsync` |216| **UA0019** | Warning | ✅ | `new DataValue(StatusCode[, ts])` → `DataValue.FromStatusCode(...)` |217| **UA0020** | Warning | ✅ | `EncodeableFactory.GlobalFactory` / `.Create()` → `ServiceMessageContext.Factory` / `.Fork()` |218| **UA0021** | Info | — | `CertificateValidator` / `CertificateValidationEventArgs` (structural rename — see manual playbook) |219| **UA0022** | Warning | ✅ | `ApplicationConfiguration.CertificateValidator` / `ServerBase.CertificateValidator` → `.CertificateManager` |220| **UA0023** | Warning | — | Legacy PubSub top-level types → `IPubSubApplication` / builder and DI APIs |221| **UA0024** | Warning | — | Exposed diagnostics locks → owner-side update/read methods |222| **UA0025** | Warning | — | `ILocalNode.DataLock` / `Node.DataLock` → node-owned synchronization |223| **UA0026** | Warning | — | `BaseVariableValue.Lock` → caller-owned `System.Threading.Lock` |224| **UA0027** | Warning | — | `NodeBrowser.DataLock` → single-consumer browser without external locking |225| **UA0028** | Warning | — | `ApplicationConfiguration.PropertiesLock` → concurrent properties APIs |226| **UA0030** | Warning | — | Server `ISubscription` publish-pipeline members / `SessionPublishQueue` → service and manager APIs |227228Runtime-shim-only migration marker:229230| Marker | Signal | Auto-fix | One-liner |231|---|---|---|---|232| **UA0029** | `CS0618` from shim | — | `SecurityPolicies` lookup/crypto statics → `ISecurityPolicyRegistry` or `SecurityPolicies.Default`; no analyzer currently reports `UA0029` |233234Plus one generator-only diagnostic:235236| ID | Source | Default | Triggers |237|---|---|---|---|238| **MIG01** | `Opc.Ua.MigrationAnalyzer.Generator` | Warning | The generator can't uniquely resolve the element type for a `<Foo>Collection` reference. It discovers consumer source declarations plus exact `System.<Type>` / `Opc.Ua.<Type>` metadata names; other zero/ambiguous cases require a manual `List<T>` / `ArrayOf<T>` migration or an explicitly defined wrapper. See [`references/source-generator.md`](references/source-generator.md). |239240### Source-generated `<Type>Collection` shims241242When 2.0 deleted the `<Type>Collection` wrapper types, every consumer call site243like `new Int32Collection { 1, 2, 3 }` and `IList<NodeIdCollection> nodes`244became a hard `CS0246` ("type or namespace not found"). The package's source245generator (`MigrationGenerator`) closes this gap: for every short name ending in246`Collection` that doesn't bind, it emits a `public sealed [Obsolete] class247<Name>Collection : List<TElement>` into the consumer's compilation.248249- **Built-in catalog (rename overrides)** pins element types that **renamed**250 across the 1.5.378 → 2.0 boundary, where semantic lookup would resolve to251 the wrong type or fail with ambiguity: `DateTime→DateTimeUtc`, `Guid→Uuid`,252 `byte[]→ByteString`, `XmlElement→System.Xml.XmlElement` (the latter253 disambiguates against the new `Opc.Ua.XmlElement`). The generator uses these254 *over* whatever the consumer's compilation resolves.255- **Consumer-source `<UserType>Collection`** patterns (model-compiler output,256 application-defined structures, etc.) are resolved by stripping the257 `Collection` suffix and looking up the short name across source declarations258 via `Compilation.GetSymbolsWithName`. Standard metadata then falls back to259 exact `System.<Type>` and `Opc.Ua.<Type>` names. Other metadata, zero260 matches, or multiple source matches produce `MIG01`.261- **Implicit conversion** to `ArrayOf<TElement>` on every generated type so262 2.0 APIs that took `ArrayOf<T>` keep accepting the shim instance.263- **`public sealed`** — legacy public signatures continue compiling while the264 package is installed. The type remains `[Obsolete]` and must not become a265 permanent public dependency.266267Deep-dive: [`references/source-generator.md`](references/source-generator.md).268269### Runtime compatibility shim270271`Opc.Ua.MigrationAnalyzer.Core.dll` re-exposes the 1.5.378 obsolete extension272surface (via C# 14 `extension` members) so 1.5.378-style call sites continue to273compile. Coverage and the sync-over-async caveat are documented in274[`references/runtime-shim.md`](references/runtime-shim.md).275276### Manual residuals — priority order277278For the 11 rules without auto-fixes and the patterns the analyzer doesn't catch279at all (e.g. `Variant.Value` setter type changes, `BaseVariableState.Value`280becoming `Variant`, `INodeManager` covariant return changes), apply fixes in281this order to minimize cascading errors:2822831. **Source generation** project-file changes (remove pre-generated `.Classes.cs`, add `<AdditionalFiles>` for design files)2842. **Null comparisons** on now-struct types (`UA0003` / `UA0004` cover most; manual for unusual patterns)2853. **Collection types** (`UA0002` covers most; manual for `IList<T>` → `ArrayOf<T>` signature shape)2864. **Built-in type replacements** (`DateTime`→`DateTimeUtc`, `Guid`→`Uuid`, `byte[]`→`ByteString`)2875. **`Variant` / `DataValue` / `ExtensionObject`** API changes2886. **Encoder / Decoder** signature updates (generic methods + `ByteString`)2897. **NodeState** generic `PropertyState<T>` → builder pattern2908. **Server-side NodeManager** migration to `AsyncCustomNodeManager`2919. **Client-side `Session` / `Subscription`** changes29210. **User identity token handler** pattern (`AsTokenHandler()` + disposable handlers)293294Full categorical playbook for each layer is in295[`references/migration-patterns.md`](references/migration-patterns.md).296297### TreatWarningsAsErrors recipe298299If your project sets `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>` and300you can't relax it during the migration window, exclude the migration diagnostics301from the failure set in your `Directory.Build.targets`:302303```xml304<PropertyGroup>305 <TreatWarningsAsErrors>true</TreatWarningsAsErrors>306 <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>307</PropertyGroup>308```309310Pasteable file at [`assets/Directory.Build.targets.example.xml`](assets/Directory.Build.targets.example.xml).311Peel each entry back as you fix the rule; drop the whole block once the312MigrationAnalyzer package is removed.313314### Known compatibility gaps315316- Legacy `.NET Framework` WinForms projects in pre-SDK MSBuild XML format317 (`xmlns="…/2003"`) — `<PackageReference>` injection via318 `Directory.Build.targets` is silently ignored; the migration package must be319 added inline to each csproj.320- Public APIs can continue returning a generated `<Type>Collection` while the321 package is installed, but those temporary types disappear with the package.322 Migrate the public surface to `List<T>` / `ArrayOf<T>` before removal.323324Full list of dogfood-discovered gaps in325[`references/known-gaps.md`](references/known-gaps.md).326327### Compatibility matrix328329Target framework, .NET SDK, and Roslyn API requirements (and how to verify330analyzers actually loaded under csc.exe) are documented in331[`references/compatibility-matrix.md`](references/compatibility-matrix.md).332333---334335## Level 3: Mastery (Extended Learning)336337The `references/` and `scripts/` folders in this skill contain the extended338material. Load them on demand via your agent runtime's339`read_skill_resource` / `run_skill_script` tools:340341### References (load via `read_skill_resource`)342343| File | Token budget | When to load |344|---|---|---|345| [`references/package-install.md`](references/package-install.md) | ~1.5K | When the user asks "how do I install" or hits PackageReference / `Directory.Build.targets` resolution issues |346| [`references/analyzer-rules.md`](references/analyzer-rules.md) | ~3K | When the user asks about a specific `UA00xx` warning or wants the full rule reference |347| [`references/source-generator.md`](references/source-generator.md) | ~2K | When `MIG01` fires or the user asks how the `<Type>Collection` shims work |348| [`references/runtime-shim.md`](references/runtime-shim.md) | ~2K | When a 1.5.378 extension call still compiles but is flagged `[Obsolete]`, or when async-promotion guidance is needed |349| [`references/migration-patterns.md`](references/migration-patterns.md) | ~5K | The categorical playbook for the 14 manual layers — primary fallback for residuals |350| [`references/known-gaps.md`](references/known-gaps.md) | ~1.5K | When legacy WinForms, generated-shim lifetime, or analyzer-loading issues surface |351| [`references/compatibility-matrix.md`](references/compatibility-matrix.md) | ~1K | When verifying the analyzer actually loaded under csc.exe vs IDE, or when picking a TFM |352| [`references/stack-migration/README.md`](references/stack-migration/README.md) | index | Bundled offline snapshot of all 15 thematic migration docs; load only the symptom-matched file |353354### Scripts (invoke via `run_skill_script`)355356| File | Purpose |357|---|---|358| [`scripts/apply-codefixes.ps1`](scripts/apply-codefixes.ps1) | PowerShell wrapper around `dotnet format analyzers --diagnostics UA0002 … --severity warn`. Auto-discovers `.sln`/`.slnx`, reports before/after warning counts. |359360### Assets (pasteable templates)361362| File | Purpose |363|---|---|364| [`assets/PackageReference.example.xml`](assets/PackageReference.example.xml) | Single `<PackageReference>` snippet for a consumer csproj. |365| [`assets/Directory.Build.targets.example.xml`](assets/Directory.Build.targets.example.xml) | Multi-project `<NoWarn>` recipe for `TreatWarningsAsErrors=true`. |366367### Optional current upstream docs368369- [`docs/MigrationGuide.md`](https://github.com/OPCFoundation/UA-.NETStandard/blob/master/docs/MigrationGuide.md) — current human-facing landing page and cross-cutting notes.370- [`docs/migrate/2.0.x/README.md`](https://github.com/OPCFoundation/UA-.NETStandard/blob/master/docs/migrate/2.0.x/README.md) — current upstream migration index.371- [`docs/migrate/2.0.x/`](https://github.com/OPCFoundation/UA-.NETStandard/tree/master/docs/migrate/2.0.x) — current versions of the thematic docs bundled under `references/stack-migration/`.372- [`tools/Opc.Ua.MigrationAnalyzer/NugetREADME.md`](https://github.com/OPCFoundation/UA-.NETStandard/blob/master/tools/Opc.Ua.MigrationAnalyzer/NugetREADME.md) — the package's own README, shipped inside the NuGet.