R1.11 AddTagExtendedPropertiesAsync: extended-property write via AddTEx

Adds user-defined extended properties to an existing tag via the 2020 WCF AddTEx (AddTagExtendedProperties) op. Write-enabled connection + uppercase storage-session GUID handle; reuses the write orchestrator open/priming chain. The AddTEx inBuff is the exact inverse of the R1.5 GetTepByNm read-response framing, so the serializer mirrors the read parser: uint32 groupCount + 0x01(group) + [0x09+u16+ASCII tag] + uint32 propCount + per prop{ 0x02 + [0x09+u16+ASCII name] + 0x43 VT_BSTR + u16 payloadLen + u16 charCount + UTF-16 value } + 0x01(group trailer) + 0x00(terminator). The trailing 0x00 is required — without it inBuff is one byte short and the server throws SErrorException in CHistStorage::AddTagExtendedProperties. The golden fixture pins the clean inBuff the live server accepted (dumped via AVEVA_HISTORIAN_TEP_DUMP); read-back verified via R1.5. String (0x43) values only. Delete (DelTep) is deferred: the native DeleteTagExtendedPropertiesByName does a client-side sync check and returns err 229 for a just-added property, so the DelTep request never reaches the wire and its inBuff can't be captured yet. Shipped: HistorianClient.AddTagExtendedPropertiesAsync/AddTagExtendedPropertyAsync; HistorianTagExtendedPropertyProtocol.SerializeAddRequest; orchestrator path; golden WcfTagExtendedPropertyWriteProtocolTests (4); gated live write/read-back test; native-harness `add-tep` scenario + Capture-AddTagExtendedProperties.ps1 + decode-add-tep-capture.py. Doc: wcf-add-tag-extended-properties.md. 233 tests green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B6mcaT2PjRFKcogzp9UkfC
2026-06-21 01:43:19 -04:00
parent 108220c36b
commit 08b950caee
11 changed files with 701 additions and 3 deletions
@@ -505,6 +505,66 @@ public sealed class HistorianClientIntegrationTests
        Assert.True(deleted, "DeleteTagAsync returned false against the live Historian.");
    }

+    [Fact]
+    public async Task AddTagExtendedPropertiesAsync_AgainstLocalHistorian_WritesAndReadsBack()
+    {
+        // Safety: localhost only, sandbox tag must start with "RetestSdkWrite". Creates the tag,
+        // adds an extended property, reads it back via R1.5, and deletes the tag. Gated on
+        // HISTORIAN_WRITE_SANDBOX_TAG.
+        string? host = Environment.GetEnvironmentVariable("HISTORIAN_HOST");
+        string? sandboxTag = Environment.GetEnvironmentVariable("HISTORIAN_WRITE_SANDBOX_TAG");
+        if (string.IsNullOrWhiteSpace(host) || !string.Equals(host, "localhost", StringComparison.OrdinalIgnoreCase) || !OperatingSystem.IsWindows())
+        {
+            return;
+        }
+        if (string.IsNullOrWhiteSpace(sandboxTag) || !sandboxTag.StartsWith("RetestSdkWrite", StringComparison.Ordinal))
+        {
+            return; // safety gate
+        }
+
+        HistorianClient client = new(new HistorianClientOptions
+        {
+            Host = host,
+            IntegratedSecurity = true,
+            Transport = HistorianTransport.LocalPipe
+        });
+
+        await client.EnsureTagAsync(new AVEVA.Historian.Client.Models.HistorianTagDefinition
+        {
+            TagName = sandboxTag,
+            Description = "SDK ext-property write live test",
+            EngineeringUnit = "test",
+            DataType = AVEVA.Historian.Client.Models.HistorianDataType.Float,
+            MinEU = 0.0,
+            MaxEU = 100.0,
+        }, CancellationToken.None);
+
+        try
+        {
+            const string propName = "SdkLiveTestProp";
+            const string propValue = "SdkLiveTestValue";
+
+            bool added = await client.AddTagExtendedPropertyAsync(sandboxTag, propName, propValue, CancellationToken.None);
+            Assert.True(added, "AddTagExtendedPropertyAsync returned false against the live Historian.");
+
+            // Read back via R1.5 (server may take a moment to surface the new property).
+            bool found = false;
+            for (int i = 0; i < 10 && !found; i++)
+            {
+                await Task.Delay(500);
+                var props = await client.GetTagExtendedPropertiesAsync(sandboxTag, CancellationToken.None);
+                found = props.Any(p =>
+                    string.Equals(p.Name, propName, StringComparison.OrdinalIgnoreCase) &&
+                    string.Equals(p.Value, propValue, StringComparison.Ordinal));
+            }
+            Assert.True(found, $"Extended property '{propName}={propValue}' was not read back after the write.");
+        }
+        finally
+        {
+            try { await client.DeleteTagAsync(sandboxTag, CancellationToken.None); } catch { }
+        }
+    }
+
    // Round-trip every live-verified analog data type + the non-default-range case. The
    // sandbox tag name is suffixed per case so the runs don't collide. Always cleans up.
    [Theory]