# 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.
- Add new managed session, wrapping session and providing connection management and failover handling
- Add new Subscription engine that can act as alternative to current engine, but is based on channels with worker tasks
- Add a fluent builder for managed session clients
- Replace NodeCache with LruNodeCache, rename ILruNodeCache and LruNodeCache to INodeCache and NodeCache
- Update migration guide and document new functionality.
Use RequestLifetime throughout the server stack for unified request lifetime and cancellation management. Update all service method signatures, OperationContext, and request processing logic to use RequestLifetime, enabling precise tracking of cancellation reasons with UA StatusCodes. Remove obsolete synchronous request handling and legacy delegates. Update code generation, tests, and interfaces to support the new model. This change improves cancellation, timeout, and abort handling, and prepares the server for advanced request management features.
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