feat(adminui): typed TagConfig editors for OpcUaClient + Historian

2026-06-16 16:25:19 -04:00
parent 39755d717d
commit 72d414ada7
11 changed files with 483 additions and 1 deletions
@@ -0,0 +1,62 @@
+using System.Text.Json.Nodes;
+
+namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns.TagEditors;
+
+/// <summary>Typed working model for a Wonderware (AVEVA) Historian equipment tag's TagConfig JSON. The
+/// tag binds to a historian tag by its full reference (<c>FullName</c> — the historian tagname/source
+/// the driver reads against), plus the optional driver-agnostic server-side HistoryRead intent
+/// (<c>isHistorized</c> / <c>historianTagname</c>). Preserves unrecognised JSON keys across a load→save.</summary>
+/// <remarks>
+///     The <c>FullName</c> key is intentionally PascalCase: the deploy-time composer + node walker
+///     (<c>Phase7Composer.ExtractTagFullName</c>, <c>EquipmentNodeWalker</c>) read it via a
+///     case-sensitive <c>TryGetProperty("FullName", …)</c>, so the editor MUST persist that exact
+///     casing. The history keys (<c>isHistorized</c> / <c>historianTagname</c>) are camelCase to match
+///     <c>Phase7Composer.ExtractTagHistorize</c>.
+/// </remarks>
+public sealed class HistorianWonderwareTagConfigModel
+{
+    /// <summary>Historian tagname/source the tag binds to (the driver-side full reference). Required.</summary>
+    public string FullName { get; set; } = "";
+
+    /// <summary>Whether the server exposes OPC UA HistoryRead over this tag's variable node.</summary>
+    public bool IsHistorized { get; set; }
+
+    /// <summary>Optional historian tagname override; blank means the historian tagname defaults to <see cref="FullName"/>.</summary>
+    public string HistorianTagname { get; set; } = "";
+
+    private JsonObject _bag = new();
+
+    /// <summary>Loads a model from a TagConfig JSON string, defaulting any absent field and retaining
+    /// every original key (so fields this editor doesn't expose survive a load→save).</summary>
+    /// <param name="json">The tag's TagConfig JSON (null/blank/malformed ⇒ defaults).</param>
+    public static HistorianWonderwareTagConfigModel FromJson(string? json)
+    {
+        var o = TagConfigJson.ParseOrNew(json);
+        return new HistorianWonderwareTagConfigModel
+        {
+            FullName = TagConfigJson.GetString(o, "FullName") ?? "",
+            IsHistorized = TagConfigJson.GetBool(o, "isHistorized"),
+            HistorianTagname = TagConfigJson.GetString(o, "historianTagname") ?? "",
+            _bag = o,
+        };
+    }
+
+    /// <summary>Serialises this model back to a TagConfig JSON string over the preserved key bag.
+    /// <c>FullName</c> is written PascalCase (the composer/walker contract key); the history keys are
+    /// written camelCase and dropped when default (absent <c>isHistorized</c> ⇒ false at the composer;
+    /// blank <c>historianTagname</c> ⇒ defaults to <c>FullName</c>).</summary>
+    public string ToJson()
+    {
+        TagConfigJson.Set(_bag, "FullName", FullName.Trim());
+        // Drop isHistorized when false so the persisted blob stays minimal and matches the
+        // composer's "absent ⇒ false" convention; same for a blank historianTagname override.
+        TagConfigJson.Set(_bag, "isHistorized", IsHistorized ? true : null);
+        TagConfigJson.Set(_bag, "historianTagname",
+            string.IsNullOrWhiteSpace(HistorianTagname) ? null : HistorianTagname.Trim());
+        return TagConfigJson.Serialize(_bag);
+    }
+
+    /// <summary>Validation hook; returns an error message or null when the model is valid.</summary>
+    public string? Validate()
+        => string.IsNullOrWhiteSpace(FullName) ? "A historian tagname (FullName) is required." : null;
+}
@@ -0,0 +1,63 @@
+using System.Text.Json.Nodes;
+
+namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns.TagEditors;
+
+/// <summary>Typed working model for an OPC UA Client (gateway) equipment tag's TagConfig JSON. The tag
+/// is bound to the upstream OPC UA server node by its full reference (<c>FullName</c> — the persisted
+/// stable <c>nsu=…;s=…</c> or plain <c>ns=2;s=…</c> NodeId the driver reads/writes/subscribes against),
+/// plus the optional driver-agnostic server-side HistoryRead intent (<c>isHistorized</c> /
+/// <c>historianTagname</c>). Preserves unrecognised JSON keys across a load→save.</summary>
+/// <remarks>
+///     The <c>FullName</c> key is intentionally PascalCase: the deploy-time composer + node walker
+///     (<c>Phase7Composer.ExtractTagFullName</c>, <c>EquipmentNodeWalker</c>) read it via a
+///     case-sensitive <c>TryGetProperty("FullName", …)</c>, so the editor MUST persist that exact
+///     casing. The history keys (<c>isHistorized</c> / <c>historianTagname</c>) are camelCase to match
+///     <c>Phase7Composer.ExtractTagHistorize</c>.
+/// </remarks>
+public sealed class OpcUaClientTagConfigModel
+{
+    /// <summary>Upstream OPC UA node reference the tag binds to (the driver-side full reference). Required.</summary>
+    public string FullName { get; set; } = "";
+
+    /// <summary>Whether the server exposes OPC UA HistoryRead over this tag's variable node.</summary>
+    public bool IsHistorized { get; set; }
+
+    /// <summary>Optional historian tagname override; blank means the historian tagname defaults to <see cref="FullName"/>.</summary>
+    public string HistorianTagname { get; set; } = "";
+
+    private JsonObject _bag = new();
+
+    /// <summary>Loads a model from a TagConfig JSON string, defaulting any absent field and retaining
+    /// every original key (so fields this editor doesn't expose survive a load→save).</summary>
+    /// <param name="json">The tag's TagConfig JSON (null/blank/malformed ⇒ defaults).</param>
+    public static OpcUaClientTagConfigModel FromJson(string? json)
+    {
+        var o = TagConfigJson.ParseOrNew(json);
+        return new OpcUaClientTagConfigModel
+        {
+            FullName = TagConfigJson.GetString(o, "FullName") ?? "",
+            IsHistorized = TagConfigJson.GetBool(o, "isHistorized"),
+            HistorianTagname = TagConfigJson.GetString(o, "historianTagname") ?? "",
+            _bag = o,
+        };
+    }
+
+    /// <summary>Serialises this model back to a TagConfig JSON string over the preserved key bag.
+    /// <c>FullName</c> is written PascalCase (the composer/walker contract key); the history keys are
+    /// written camelCase and dropped when default (absent <c>isHistorized</c> ⇒ false at the composer;
+    /// blank <c>historianTagname</c> ⇒ defaults to <c>FullName</c>).</summary>
+    public string ToJson()
+    {
+        TagConfigJson.Set(_bag, "FullName", FullName.Trim());
+        // Drop isHistorized when false so the persisted blob stays minimal and matches the
+        // composer's "absent ⇒ false" convention; same for a blank historianTagname override.
+        TagConfigJson.Set(_bag, "isHistorized", IsHistorized ? true : null);
+        TagConfigJson.Set(_bag, "historianTagname",
+            string.IsNullOrWhiteSpace(HistorianTagname) ? null : HistorianTagname.Trim());
+        return TagConfigJson.Serialize(_bag);
+    }
+
+    /// <summary>Validation hook; returns an error message or null when the model is valid.</summary>
+    public string? Validate()
+        => string.IsNullOrWhiteSpace(FullName) ? "An upstream node reference (FullName) is required." : null;
+}
@@ -16,6 +16,8 @@ public static class TagConfigEditorMap
            ["AbLegacy"]  = typeof(Components.Shared.Uns.TagEditors.AbLegacyTagConfigEditor),
            ["TwinCat"]   = typeof(Components.Shared.Uns.TagEditors.TwinCATTagConfigEditor),
            ["Focas"]     = typeof(Components.Shared.Uns.TagEditors.FocasTagConfigEditor),
+            ["OpcUaClient"]          = typeof(Components.Shared.Uns.TagEditors.OpcUaClientTagConfigEditor),
+            ["Historian.Wonderware"] = typeof(Components.Shared.Uns.TagEditors.HistorianWonderwareTagConfigEditor),
        };

    /// <summary>Returns the editor component type for a driver type, or null if none is registered.</summary>
@@ -29,6 +29,10 @@ public static class TagConfigJson
    public static int GetInt(JsonObject o, string name, int fallback = 0)
        => o.TryGetPropertyValue(name, out var n) && n is JsonValue v && v.TryGetValue<int>(out var i) ? i : fallback;

+    /// <summary>Reads a bool value, or <paramref name="fallback"/> if absent/null/non-boolean (incl. object/array/number/string nodes).</summary>
+    public static bool GetBool(JsonObject o, string name, bool fallback = false)
+        => o.TryGetPropertyValue(name, out var n) && n is JsonValue v && v.TryGetValue<bool>(out var b) ? b : fallback;
+
    /// <summary>Reads an enum by its serialised name, or <paramref name="fallback"/> if absent/unparseable.</summary>
    public static TEnum GetEnum<TEnum>(JsonObject o, string name, TEnum fallback) where TEnum : struct, Enum
        => GetString(o, name) is { } s && Enum.TryParse<TEnum>(s, ignoreCase: true, out var v) ? v : fallback;
@@ -18,6 +18,8 @@ public static class TagConfigValidator
            ["AbLegacy"]  = j => AbLegacyTagConfigModel.FromJson(j).Validate(),
            ["TwinCat"]   = j => TwinCATTagConfigModel.FromJson(j).Validate(),
            ["Focas"]     = j => FocasTagConfigModel.FromJson(j).Validate(),
+            ["OpcUaClient"]          = j => OpcUaClientTagConfigModel.FromJson(j).Validate(),
+            ["Historian.Wonderware"] = j => HistorianWonderwareTagConfigModel.FromJson(j).Validate(),
        };

    /// <summary>