# Description
Closes the original PR #3619 TODO and extends the `MatrixOf<T>` opt-in
to every place the source generator previously fell back to `Variant`
for `ValueRank="OneOrMoreDimensions"`.
## Generator changes (`Tools/Opc.Ua.SourceGeneration.Core`)
### Site 1 — DataType structure fields (`DataTypeGenerator.cs`)
Fields declared with matrix rank now render as
`global::Opc.Ua.MatrixOf<T>` instead of `Variant`, mirroring the
existing `ArrayOf<T>` treatment for `Array` rank. Encode/decode is
routed per the field's `DataType`:
| Field `DataType` | Property | Encode | Decode |
| ------------------------------------------------- |
--------------------------------------- |
----------------------------------------------------------- |
-----------------------------------------------------------------------
|
| primitive (`Boolean`, `Int32`, `String`, …) | `MatrixOf<bool>` etc. |
`WriteVariant(name, Variant.From(field));` |
`ReadVariant(name).GetBooleanMatrix();` (etc.) |
| `Structure` / abstract structure | `MatrixOf<ExtensionObject>` |
`WriteVariant(name, Variant.From(field));` |
`ReadVariant(name).GetExtensionObjectMatrix();` |
| concrete `IEncodeable` (e.g. `Vector`) | `MatrixOf<Vector>` |
`WriteEncodeableMatrix(name, field);` |
`ReadEncodeableMatrix<Vector>(name);` |
| typed enum | `MatrixOf<MyEnum>` | `WriteVariant(name,
Variant.From(field));` |
`ReadVariant(name).GetEnumerationMatrix<MyEnum>();` |
| `BaseDataType` / `Number` / `Integer` / `UInteger`|
`MatrixOf<Variant>` | `WriteVariant(name, Variant.From(field));` |
`ReadVariant(name).GetVariantMatrix();` |
### Site 2 — VariableType State classes (`NodeStateGenerator.cs`)
Replaces the original `// TODO: matrixOf;` from #3619. Concrete matrix
variable types now inherit the typed `<MatrixOf<T>>` chain. Standard
model:
- `XYArrayItemState :
ArrayItemState<MatrixOf<XVType>>.Implementation<StructureBuilder<XVType>>`
Abstract bases (`ArrayItemType`, `CubeItemType`, `ImageItemType`,
`NDimensionArrayItemType` — all `DataType="BaseDataType"`) keep the
existing `<T>` early-return.
### Site 3 — Property / Variable instances
(`ModelDesignExtensions.GetNodeStateClassName`)
Adds a `OneOrMoreDimensions` branch after the existing `Array` branch
and refines `IsTemplateParameterRequired` / `IsIndeterminateType` so
matrix-rank concrete types are no longer treated as indeterminate.
Standard model:
- `EnumDictionaryEntries: PropertyState<MatrixOf<NodeId>>`
- `FailureSystemIdentifier: BaseDataVariableState<MatrixOf<byte>>`
### Site 4 — Method parameters (`ClientApiGenerator` /
`ServerApiGenerator`)
`CollectParameters` opts in to `useMatrixTypeInsteadOfVariant` via
`SupportsMatrixOf()`. Zero standard-service impact (no OPC UA service
declares matrix args).
## Encoder / decoder API
Adds the parameterless overload `MatrixOf<T>
ReadEncodeableMatrix<T>(string? fieldName) where T : IEncodeable, new()`
to `IDecoder` and all implementations (`BinaryDecoder`, `JsonDecoder`,
`XmlDecoder`, `XmlParser`, `PubSubJsonDecoder`), mirroring the existing
`ReadEncodeableArray<T>(string?)` shape so the generator does not need a
runtime encoding-id lookup.
## Consumer migration
-
`Applications/Quickstarts.Servers/ReferenceServer/ReferenceNodeManager.cs`
— `CreateXYArrayItemVariable` updated from
`Variant.FromStructure(ArrayOf.Wrapped(...))` to `new XVType[] { …
}.ToMatrixOf(5)` to match the new typed `XYArrayItemState.Value`
surface.
## Tests added
- **Generator snippet tests**:
`GenerateMatrixValueDataType_EmitsMatrixOfPropertiesAndCalls` (custom
data-type matrix fields) and
`NodeStateGeneratorEmitsMatrixOfTemplateParameterForStandardModel`
(standard-model VariableType + instance types).
- **Encoder round-trip**: new `EncodeableMatrixRoundTripTests` exercises
`WriteEncodeableMatrix` ↔ `ReadEncodeableMatrix<T>(string?)` through
Binary, XML, and parameterless overloads with null-matrix and populated
payloads.
- **Extension tests**: parameterised
`GetDotNetTypeName_OneOrMoreDimensionsValueRankWithBasicDataTypes_ReturnsCorrectMatrixOfType`
and `IsTemplateParameterRequired_OneOrMoreDimensionsWith…` tables;
`SupportsMatrixOf` coverage including `DiagnosticInfo → false` and
`ArgumentNullException` for null receiver.
- **Test resource models** (`TestDataDesign.xml`, `DemoModel.xml`,
`TestModel.xml`): new `MatrixValueDataType` /
`SampleStructureWithMatrixFields` exercise every branch end-to-end
through the existing `GenerateAndCompileDesignFileAsync` integration
test.
## Documentation
`Docs/MigrationGuide.md` — new sub-section "Generated data type fields
with ValueRank=OneOrMoreDimensions" with a per-`BasicDataType` mapping
table, the `IDecoder.ReadEncodeableMatrix<T>(string?)` overload note for
custom decoder implementations, and a sibling block covering
VariableType State classes, property-state instances, and service
parameters with before/after code samples.
## Verification
| Suite (net10.0) | Result |
| --------------- | ------ |
| `Opc.Ua.Types.Tests` | 7553 passed |
| `Opc.Ua.SourceGeneration.Core.Tests` | 3623 passed, 8 skipped
(analyzer-conditional) |
| `Opc.Ua.SourceGeneration.Stack.Tests` | 90 passed |
| `Opc.Ua.SourceGeneration.Tests` | 40 passed |
| `Opc.Ua.Server.Tests` (focused on `ReferenceServer`/`ArrayItem`) | 37
passed |
| Full `UA.slnx` build | 0 errors (42 pre-existing unrelated CA2007
warnings) |
The `// TODO: matrixOf;` comment is gone from `NodeStateGenerator.cs`.
## Related Issues
- Fixes#3625
## Checklist
- [x] I have signed the
[CLA](https://opcfoundation.org/license/cla/ContributorLicenseAgreementv1.0.pdf)
and read the
[CONTRIBUTING](https://github.com/OPCFoundation/UA-.NETStandard/blob/master/CONTRIBUTING.md)
doc.
- [x] I have added tests that prove my fix is effective or that my
feature works and increased code coverage.
- [x] I have added all necessary documentation.
- [x] I have verified that my changes do not introduce (new) build or
analyzer warnings.
- [x] I ran **all** tests locally using the **UA.slnx** solution against
at least .net **framework** and .net **10**, and all passed.
- [ ] I fixed **all** failing and flaky tests in the CI pipelines and
**all** CodeQL warnings.
- [ ] I have addressed **all** PR feedback received.
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.
* New certificate and secrete abstraction with certificate infrastructure and certificate/secret stores.
* leak testing for certificate resources to validate new ref counting in every test assembly
* Migration guide updated and documentation added for all
* Remove IDisposable from Nodestate and UserIdentity.
* UserCertificateTokenHandler now just points into certificate registry/stores, no dispose required
* Fix CA2000 warnings and cleanup of other diagnostics, increase warning levels in .editorconfig
* Fix boolean default should be false instead of true
* Update MigrationGuide for boolean default value changes
Clarified the impact of the boolean default value change and updated the migration guide to reflect the correct initialization requirements.
* make most ptojects aot compatible
* Remove newtonsoft
* Migrate all projects from Mono.Options to System.CommandLine 2.0.5
* Fix array clone
* Replace serializers for storage using new attribute driven type geberator
* Add new AOT integration tests covering all functional areas
* Documentation updates
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