mirror of
https://github.com/OPCFoundation/UA-.NETStandard.git
synced 2026-10-18 22:55:08 +08:00
Marc Schier
59374fc81d
# 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.