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