This PR implements the **OPC UA Device Integration (DI, OPC 10000-100)**
companion-spec library trio (`Opc.Ua.Di` / `Opc.Ua.Di.Server` /
`Opc.Ua.Di.Client`) plus a worked example
(`Applications/MinimalPumpServer`) demonstrating the OPC 40223 Pumps
companion specification end-to-end with full simulation. It also closes
11 fluent-API gaps in `Opc.Ua.Server.Fluent`, three source-generator
bugs, integrates the DI layer into the unified `services.AddOpcUa()`
Microsoft.Extensions DI hosting pattern, and adds 250+ new tests.
**Worked example — `Applications/MinimalPumpServer/`**
- AOT-compatible console host using `Host.CreateApplicationBuilder` +
`AddOpcUa()`.
- `PumpNodeManager` inherits from `DiNodeManager`; multi-namespace (DI +
Machinery + Pumps) via runtime NodeSet2 loading and
`ModelLoaderBuilder`.
- Demonstrates declarative second-pump creation via
`.ConfigureDevicesFor<PumpNodeManager>(...)` and software-package
seeding from the same configurator.
- Full simulation: pressure, temperatures, power, flow, efficiency,
level, cavitation/overheat fault injection, alarm setup, NAMUR-style
supervision.
**Documentation**
- `Docs/Opc.Ua.Di/` — README, DeviceBuilder, Hosting, LockService,
SoftwareUpdate, ClientHelpers (6 new developer guides).
- `Docs/Opc.Ua.Di/ComplianceMatrix.md` — every DI declaration mapped to
In-v1 / Generated / Deferred / Excluded.
- `Docs/CompanionSpecLibraries.md` — packaging guide for new
companion-spec libraries.
- `Docs/FluentApiGaps.md` — historical record of G1–G11.
- `Docs/SourceGeneratedNodeManagers.md` updated for richer node
managers.
- `Docs/plans/StateMachineBuilder.md` — deferred state-machine builder
design.
## Proposed changes
When the source generator creates code for "instance" definitions (e.g.,
the `Server` object which has `ServerType` as its type definition), it
currently uses the modelling rules specified on the **instance's
children**, which may differ from the **type definition's children**.
For example:
- `ServerType` defines `UrisVersion` as `ModellingRule="Optional"`
- `Server` instance overrides it to `ModellingRule="Mandatory"`
This PR introduces two layers of modelling rule enforcement:
### 1. OPC UA promotion semantics (always active)
Regardless of any configuration, the generator now enforces OPC UA
modelling rule promotion semantics. Instances may only **promote** the
type definition's rule:
| Type Definition Rule | Allowed Instance Overrides |
|---|---|
| `Optional` | `Mandatory` |
| `OptionalPlaceholder` | `Mandatory`, `MandatoryPlaceholder` |
| `MandatoryPlaceholder` | `Mandatory` |
Any other instance override (demotion) is silently rejected and the type
definition's rule is used instead. This applies to both structural code
generation decisions and the emitted runtime `ModellingRuleId`.
### 2. `UseTypeDefinitionModellingRules` option (opt-in)
When enabled, the generator uses the type definition's modelling rules
**unconditionally** — instance overrides are ignored entirely (even
valid promotions). This is useful for stack generation where the type
definition's semantics should be preserved exactly.
- **Enabled by default** for stack generation
(`Opc.Ua.SourceGeneration.Stack`)
- **Disabled by default** for the Roslyn source generator
(`Opc.Ua.SourceGeneration`), configurable via
`ModelSourceGeneratorUseTypeDefinitionModellingRules` MSBuild property
### Key design decisions
- A `TypeDefinitionModellingRule` property on `HierarchyNode` captures
the type definition's original rule before instance overrides, updated
through base→derived type-hierarchy merges but frozen once explicit
instance overrides appear
- A `GetEffectiveModellingRule()` helper with `IsValidPromotion()`
centralizes the rule resolution logic across all structural check sites
and runtime `ModellingRuleId` emission
- Factory method emission (`LoadTemplate_ReplaceChild`) uses the
instance's own modelling rule for mandatory/optional list classification
so children the instance marks Mandatory are always created
## Related Issues
- N/A
### Types of changes
- [ ] Bugfix (non-breaking change which fixes an issue)
- [x] Enhancement (non-breaking change which adds functionality)
- [ ] Test enhancement (non-breaking change to increase test coverage)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected, requires version increase of
Nuget packages)
- [ ] Documentation Update (if none of the other choices apply)
## Checklist
- [x] I have read the
[CONTRIBUTING](https://github.com/OPCFoundation/UA-.NETStandard/blob/master/CONTRIBUTING.md)
doc.
- [x] I have signed the
[CLA](https://opcfoundation.org/license/cla/ContributorLicenseAgreementv1.0.pdf).
- [x] I ran tests locally with my changes, all passed.
- [ ] I fixed all failing tests in the CI pipelines.
- [ ] I fixed all introduced issues with CodeQL and LGTM.
- [ ] I have added tests that prove my fix is effective or that my
feature works and increased code coverage.
- [x] I have added necessary documentation (if appropriate).
- [ ] Any dependent changes have been merged and published in downstream
modules.
## Further comments
### Files changed:
| File | Change |
|------|--------|
| `Schema/ModelDesign.cs` | Added `TypeDefinitionModellingRule` property
to `HierarchyNode` |
| `Schema/ModelDesignValidator.cs` | Populates
`TypeDefinitionModellingRule` during hierarchy merge; updates through
base→derived type merges, freezes on instance overrides |
| `GeneratorOptions.cs` | Added `UseTypeDefinitionModellingRules` option
with full XML doc |
| `NodeStateGenerator.cs` | `GetEffectiveModellingRule()` +
`IsValidPromotion()` helpers; updated structural check sites and runtime
`ModellingRuleId` emission; `NodeToGenerate` extended with
`TypeDefinitionModellingRule` |
| `StackGeneration.cs` | Enabled option for stack generation |
| `ModelCompilationOptions.cs` | Added option + MSBuild property read |
| `ModelCompilation.cs` | Wired option through to `GeneratorOptions` |
| `OPCFoundation.Opc.Ua.SourceGeneration.props` | Registered MSBuild
`CompilerVisibleProperty` |
| `readme.md` | Documented new MSBuild property with promotion semantics
|
Two refactors that together reshape how the stack tier is laid out:
1. Rename `Opc.Ua` project to `Opc.Ua.Core.Types`
* Stack/Opc.Ua/ -> Stack/Opc.Ua.Core.Types/ (git mv preserves history)
* Opc.Ua.csproj -> Opc.Ua.Core.Types.csproj
* AssemblyName : `Opc.Ua` -> `Opc.Ua.Core.Types`
* PackageId : `OPCFoundation.NetStandard.Opc.Ua` ->
`OPCFoundation.NetStandard.Opc.Ua.Core.Types`
* RootNamespace : kept as `Opc.Ua`
* StackGeneration.cs assembly-name switch updated; the renamed
assembly still produces `StackGenerationType.Models`.
* The `OPCFoundation.NetStandard.Opc.Ua` name now belongs solely to
the roll-up meta-package (nuget/Opc.Ua.nuspec); the meta-package's
former self-dependency is replaced with the new
`.Core.Types` package, and `.Symbols.nuspec` gains the
matching `.Core.Types.Debug` debug-symbol dependency.
2. Move `Opc.Ua.Security.Certificates` from Libraries/ to Stack/
It is a stack-tier dependency consumed by Opc.Ua.Core, not a
higher-level library extension, so it now sits alongside the other
stack projects.
Both refactors update the same set of cross-cutting infrastructure:
- UA.slnx, UA Core Library.slnx, Applications/ConsoleReferenceServer/Dockerfile
- .azurepipelines/signlist{Debug,Release}.txt
- ProjectReferences across Stack/, Libraries/, Tests/, Fuzzing/
- Tests/Opc.Ua.SourceGeneration.Stack.Tests/StackGenerationAssemblyTests.cs
- Docs/PlatformBuild.md and .github/copilot-instructions.md (new
Core.Types package listed)
Verification
* dotnet build UA.slnx -c Debug -- succeeded, 0 errors
* StackGenerationAssemblyTests : 5 passed
* Opc.Ua.SourceGeneration.Tests : 40 passed
* Opc.Ua.SourceGeneration.Core.Tests : 3514 passed, 8 skipped
* Opc.Ua.Core.Tests (Stack filter) : 1982 passed, 80 skipped
* Opc.Ua.Security.Certificates.Tests : 239 passed
Add interop test agent
The new stack-pass ObjectMethodProxyGenerator emits proxies that derive
from Opc.Ua.ObjectTypeClient and reference Session.MessageContext.NamespaceUris.
Neither type exists in the in-memory test compilation, which only references
Opc.Ua.Types.dll. Moving ObjectTypeClient to Opc.Ua.Types would cascade ISessionClient,
IClientBase, ITransportChannel and the generated service interfaces with it, so the
type stays in Opc.Ua.Core and we add a minimal stub to OpcUaCoreStubs instead.
Wire Microsoft.Extensions.Options 10.0.5 + DependencyInjection.Abstractions 10.0.5 into Directory.Packages.props and the Gds.Client.Common project to enable upcoming options-driven configuration work.
Modernize Opc.Ua.Gds.Client.Common (DI, options, interfaces, async dispose)
Generate stack and application code using source generators
Change built in types to readonly structs
Update localized text implementation to use JSON text serializer
Status code with symbolic names
Immutable node ids
No boxing for all built in types <= 8 bytes in Variant.
Split user identity token and token handling via token handler
Add migration guide for breaking changes
Marc Schier