mirror of
https://github.com/OPCFoundation/UA-.NETStandard.git
synced 2026-10-18 22:55:08 +08:00
romanett
e61ad4b306
# Description Part 16 §B.3 places `HasSubStateMachine` on the parent **state** node, but the fluent builder attached it to the state-machine **root** because `FluentFiniteStateMachineState` never materialized state nodes at all. Investigating #3821 showed the gap was wider than the reference placement: 1. **No state nodes existed.** The NodeId written into `CurrentState/Id` — `new NodeId(stateId, ElementNamespaceIndex)` — was **dangling**: no node with that id was in the address space. 2. **`AvailableStates` was never populated**, so `GetAvailableStatesAsync` returned empty against a fluent-built server. 3. **The whole client discovery chain was therefore dead.** `ObserveEffectiveStateAsync` enumerates `AvailableStates` and browses `HasSubStateMachine` from each state node — it found nothing. The client side was already spec-correct; only the server deviated. 4. **`HasSubStateMachine` is non-hierarchical** (a subtype of `NonHierarchicalReferences`, `i=32`). Using it as the sub-SM's `BaseInstanceState.ReferenceTypeId` left the sub-SM unreachable from a hierarchical browse of the machine. ## What changed **Element nodes are materialized.** Definition-mode machines now create one `StateType` node per declared state and one `TransitionType` node per declared transition — each a `HasComponent` child carrying `StateNumber` / `TransitionNumber`, with the §B.4 `FromState` / `ToState` / `HasEffect` references and `HasCause` added by `WithCause`. `AvailableStates`, `AvailableTransitions` and `LastTransition` are populated, so `CurrentState/Id` and `LastTransition/Id` resolve to real, browsable nodes. NodeIds are per-instance, so several machines built from one definition coexist. **`HasSubStateMachine` moved to the state node**, with the inverse `SubStateMachineOf`, and the sub-SM is attached as a `HasComponent` child (fixing 4). **Core gains element-id mapping hooks.** `GetCurrentStateId` / `UpdateStateVariable` / `UpdateTransitionVariable` hard-coded the numeric form and were non-virtual, so a subclass could not redirect them. They now route through `public virtual` `GetStateNodeId` / `GetStateId` / `GetTransitionNodeId` / `GetTransitionId`, whose defaults reproduce the previous `(elementId, ElementNamespaceIndex)` convention **exactly** — every stack-shipped and generator-emitted machine is unaffected, and there is a regression test asserting that. **Generated machines report their model namespace.** The generator now emits an `ElementNamespaceUri` override on `FiniteStateMachineType` subtypes, taken from the nearest type that actually *declares* state children — a subtype that only adds behaviour inherits its elements, and their namespace, from its base. **Ordering and validation fixes.** `WithSubStateMachine` and `WithInitialState` are now order-independent (previously, attaching a sub-SM before setting the initial state left the child suspended until the parent left and re-entered the state — silently). `WithSubStateMachine` validates `parentStateId`, and the builder rejects duplicate element browse names, since element NodeIds are now derived from them. ## A defect this surfaced Code that assembles nodes with the generated `CreateInstanceOf<Type>` factories never calls `NodeState.CreateAsPredefinedNode`, so `OnBeforeCreate` / `OnAfterCreate` are skipped for the entire subtree — and `OnAfterCreate` is the only place a state machine resolves its element namespace. It is also where `ConditionState` binds its `Enable` / `Disable` / `AddComment` handlers and `AlarmConditionState` binds the shelving methods, so the impact is broader than state machines. This PR fixes only the two call sites it depends on — DI's `SoftwareUpdateFacetWiring` and Robotics' `RoboticsOperationBuilder`. **The repository-wide audit is deliberately left out of scope and tracked in #4320** (24 files call these factories; none completed the lifecycle). The Robotics regression had no test coverage at all, so an assertion on `CurrentState/Id` was added and verified to fail without the fix. ## Breaking changes - Sub-state machines are **no longer browsable from the state-machine root**. Callers passing a machine's `ObjectId` to `GetSubStateMachineAsync` must pass a state NodeId instead — from `GetAvailableStatesAsync` or a snapshot's `CurrentStateId`. - `CurrentState/Id` for fluent machines changes from the numeric form to the materialized node's id. Code reading a numeric id out of it should call `FiniteStateMachineState.GetStateId` rather than parsing the identifier. - Generated machines qualify `CurrentState/Id` / `LastTransition/Id` with their companion-spec namespace instead of the OPC UA one. Documented in `docs/WhatsNewIn2.0.md` and `docs/StateMachines.md`. ## Notes for reviewers - Adding `virtual` to the `FiniteStateMachineState` members is a binary (not source) breaking change — assumed acceptable on the 2.0 line, but worth confirming against the compatibility policy. - Address-space cost is one node plus one property per declared state and transition, per machine instance; called out in the docs for servers instantiating many machines. - `AvailableTransitions` is modelled as a `HasComponent` `BaseDataVariable` (matching the standard NodeSet and what the client's browse path expects), not a Property. ## Related Issues - Fixes #3821 - Surfaced #4320 (node create lifecycle audit — not addressed here) ## Checklist - [ ] 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. - [ ] 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. ### Test runs (net10.0) | Suite | Result | |---|---| | `Opc.Ua.Server.Tests` (full) | 4734 passed, 5 skipped | | `Opc.Ua.SourceGeneration.Core.Tests` | 3780 passed | | `Opc.Ua.SourceGeneration.Tests` | 132 passed | | `Opc.Ua.SourceGeneration.Stack.Tests` | 94 passed | | `Opc.Ua.Types.Tests` | 8763 passed | | `Opc.Ua.Robotics.Tests` | 540 passed | | `Opc.Ua.Robotics.Intent.Tests` | 22 passed | | `Opc.Ua.Di.Tests` | 424 passed | | `Opc.Ua.ISA95.Tests` | 136 passed | | `Opc.Ua.Aas.Tests` | 670 passed | | `Opc.Ua.Positioning.Tests` | 69 passed | | `Opc.Ua.Client.Tests` (StateMachines) | 36 passed | Only net10.0 was run locally; the .NET Framework leg is left to CI, hence the unchecked box above. --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: marcschier <11168470+marcschier@users.noreply.github.com>
159 lines
9.5 KiB
C#
159 lines
9.5 KiB
C#
/* ========================================================================
|
|
* Copyright (c) 2005-2025 The OPC Foundation, Inc. All rights reserved.
|
|
*
|
|
* OPC Foundation MIT License 1.00
|
|
*
|
|
* Permission is hereby granted, free of charge, to any person
|
|
* obtaining a copy of this software and associated documentation
|
|
* files (the "Software"), to deal in the Software without
|
|
* restriction, including without limitation the rights to use,
|
|
* copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
* copies of the Software, and to permit persons to whom the
|
|
* Software is furnished to do so, subject to the following
|
|
* conditions:
|
|
*
|
|
* The above copyright notice and this permission notice shall be
|
|
* included in all copies or substantial portions of the Software.
|
|
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
|
|
* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
|
|
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
|
|
* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
|
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
|
* OTHER DEALINGS IN THE SOFTWARE.
|
|
*
|
|
* The complete license agreement can be found here:
|
|
* http://opcfoundation.org/License/MIT/1.00/
|
|
* ======================================================================*/
|
|
|
|
using System.Collections.Generic;
|
|
using Opc.Ua.Generators;
|
|
|
|
namespace Generators
|
|
{
|
|
/// <summary>
|
|
/// Translates the simulated operating state onto the numbers
|
|
/// <c>GeneratorStateMachineType</c> declares.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Kept apart from the node manager because it is a statement about the model,
|
|
/// not about how this server happens to publish it, and because the tests need
|
|
/// to hold it against <see cref="GeneratorSimulation.IsLegalTransition"/>. Two
|
|
/// tables that disagree produce a server whose state machine reports a machine
|
|
/// as running while its physics say it is stopped, and nothing at run time
|
|
/// notices.
|
|
/// </remarks>
|
|
internal static class GeneratorStateMap
|
|
{
|
|
/// <summary>
|
|
/// Gets the model's state <em>node id</em> for every simulated
|
|
/// state — the identifier of the StateType node the model
|
|
/// declares, which is what <c>CurrentState/Id</c> must carry
|
|
/// (the state <em>number</em> is a different value published by
|
|
/// the StateNumber property).
|
|
/// </summary>
|
|
public static IReadOnlyDictionary<GeneratorRunState, uint> StateIds { get; } =
|
|
new Dictionary<GeneratorRunState, uint>
|
|
{
|
|
[GeneratorRunState.Off] = GeneratorStateMachineTypeIds.StateIds.Off,
|
|
[GeneratorRunState.Ready] = GeneratorStateMachineTypeIds.StateIds.Ready,
|
|
[GeneratorRunState.Starting] = GeneratorStateMachineTypeIds.StateIds.Starting,
|
|
[GeneratorRunState.Warmup] = GeneratorStateMachineTypeIds.StateIds.Warmup,
|
|
[GeneratorRunState.Running] = GeneratorStateMachineTypeIds.StateIds.Running,
|
|
[GeneratorRunState.Loaded] = GeneratorStateMachineTypeIds.StateIds.Loaded,
|
|
[GeneratorRunState.Synchronizing] =
|
|
GeneratorStateMachineTypeIds.StateIds.Synchronizing,
|
|
[GeneratorRunState.Paralleled] = GeneratorStateMachineTypeIds.StateIds.Paralleled,
|
|
[GeneratorRunState.Cooldown] = GeneratorStateMachineTypeIds.StateIds.Cooldown,
|
|
[GeneratorRunState.Stopping] = GeneratorStateMachineTypeIds.StateIds.Stopping,
|
|
[GeneratorRunState.Fault] = GeneratorStateMachineTypeIds.StateIds.Fault,
|
|
[GeneratorRunState.EmergencyStopped] =
|
|
GeneratorStateMachineTypeIds.StateIds.EmergencyStopped,
|
|
};
|
|
|
|
/// <summary>
|
|
/// Gets the model's state number for every simulated state.
|
|
/// </summary>
|
|
public static IReadOnlyDictionary<GeneratorRunState, uint> StateNumbers { get; } =
|
|
new Dictionary<GeneratorRunState, uint>
|
|
{
|
|
[GeneratorRunState.Off] = GeneratorStateMachineTypeIds.StateNumbers.Off,
|
|
[GeneratorRunState.Ready] = GeneratorStateMachineTypeIds.StateNumbers.Ready,
|
|
[GeneratorRunState.Starting] = GeneratorStateMachineTypeIds.StateNumbers.Starting,
|
|
[GeneratorRunState.Warmup] = GeneratorStateMachineTypeIds.StateNumbers.Warmup,
|
|
[GeneratorRunState.Running] = GeneratorStateMachineTypeIds.StateNumbers.Running,
|
|
[GeneratorRunState.Loaded] = GeneratorStateMachineTypeIds.StateNumbers.Loaded,
|
|
[GeneratorRunState.Synchronizing] =
|
|
GeneratorStateMachineTypeIds.StateNumbers.Synchronizing,
|
|
[GeneratorRunState.Paralleled] = GeneratorStateMachineTypeIds.StateNumbers.Paralleled,
|
|
[GeneratorRunState.Cooldown] = GeneratorStateMachineTypeIds.StateNumbers.Cooldown,
|
|
[GeneratorRunState.Stopping] = GeneratorStateMachineTypeIds.StateNumbers.Stopping,
|
|
[GeneratorRunState.Fault] = GeneratorStateMachineTypeIds.StateNumbers.Fault,
|
|
[GeneratorRunState.EmergencyStopped] =
|
|
GeneratorStateMachineTypeIds.StateNumbers.EmergencyStopped,
|
|
};
|
|
|
|
/// <summary>
|
|
/// Gets the model's transition number for every legal move.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Every entry is a transition the specification declares. A pair that is
|
|
/// not here is not a legal move, which is why this table and
|
|
/// <see cref="GeneratorSimulation.IsLegalTransition"/> are held against each
|
|
/// other by <c>GeneratorStateMachineTests</c>.
|
|
/// </remarks>
|
|
public static IReadOnlyDictionary<(GeneratorRunState From, GeneratorRunState To), uint>
|
|
TransitionNumbers
|
|
{ get; } = new Dictionary<(GeneratorRunState, GeneratorRunState), uint>
|
|
{
|
|
[(GeneratorRunState.Off, GeneratorRunState.Ready)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.OffToReady,
|
|
[(GeneratorRunState.Ready, GeneratorRunState.Starting)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.ReadyToStarting,
|
|
[(GeneratorRunState.Ready, GeneratorRunState.Off)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.ReadyToOff,
|
|
[(GeneratorRunState.Starting, GeneratorRunState.Warmup)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.StartingToWarmup,
|
|
[(GeneratorRunState.Starting, GeneratorRunState.Fault)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.StartingToFault,
|
|
[(GeneratorRunState.Warmup, GeneratorRunState.Running)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.WarmupToRunning,
|
|
[(GeneratorRunState.Running, GeneratorRunState.Loaded)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.RunningToLoaded,
|
|
[(GeneratorRunState.Running, GeneratorRunState.Synchronizing)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.RunningToSynchronizing,
|
|
[(GeneratorRunState.Running, GeneratorRunState.Cooldown)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.RunningToCooldown,
|
|
[(GeneratorRunState.Running, GeneratorRunState.Fault)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.RunningToFault,
|
|
[(GeneratorRunState.Running, GeneratorRunState.EmergencyStopped)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.RunningToEmergencyStopped,
|
|
[(GeneratorRunState.Synchronizing, GeneratorRunState.Paralleled)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.SynchronizingToParalleled,
|
|
[(GeneratorRunState.Synchronizing, GeneratorRunState.Running)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.SynchronizingToRunning,
|
|
[(GeneratorRunState.Paralleled, GeneratorRunState.Loaded)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.ParalleledToLoaded,
|
|
[(GeneratorRunState.Paralleled, GeneratorRunState.Fault)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.ParalleledToFault,
|
|
[(GeneratorRunState.Paralleled, GeneratorRunState.EmergencyStopped)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.ParalleledToEmergencyStopped,
|
|
[(GeneratorRunState.Loaded, GeneratorRunState.Cooldown)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.LoadedToCooldown,
|
|
[(GeneratorRunState.Loaded, GeneratorRunState.Fault)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.LoadedToFault,
|
|
[(GeneratorRunState.Loaded, GeneratorRunState.EmergencyStopped)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.LoadedToEmergencyStopped,
|
|
[(GeneratorRunState.Cooldown, GeneratorRunState.Stopping)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.CooldownToStopping,
|
|
[(GeneratorRunState.Stopping, GeneratorRunState.Off)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.StoppingToOff,
|
|
[(GeneratorRunState.Fault, GeneratorRunState.Off)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.FaultToOff,
|
|
[(GeneratorRunState.EmergencyStopped, GeneratorRunState.Off)] =
|
|
GeneratorStateMachineTypeIds.TransitionNumbers.EmergencyStoppedToOff,
|
|
};
|
|
}
|
|
}
|