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]
@@ -0,0 +1,72 @@
+using System.Buffers.Binary;
+using System.Text;
+using AVEVA.Historian.Client.Models;
+using AVEVA.Historian.Client.Wcf;
+
+namespace AVEVA.Historian.Client.Tests;
+
+/// <summary>
+/// Golden-byte tests for the <c>AddTEx</c> (AddTagExtendedProperties) inBuff serializer (HCAL R1.11).
+/// The reference buffer is the exact byte[] the SDK handed the WCF channel in the live
+/// <c>AddTagExtendedPropertiesAsync_AgainstLocalHistorian_WritesAndReadsBack</c> run — the server
+/// accepted it and the property was read back, so it is server-validated.
+/// </summary>
+public sealed class WcfTagExtendedPropertyWriteProtocolTests
+{
+    // Server-accepted AddTEx inBuff for tag "RetestSdkWriteTepSdk3", property "SdkLiveTestProp" =
+    // "SdkLiveTestValue", dumped via AVEVA_HISTORIAN_TEP_DUMP during the live write test.
+    private const string ServerAcceptedInBuffBase64 =
+        "AQAAAAEJFQBSZXRlc3RTZGtXcml0ZVRlcFNkazMBAAAAAgkPAFNka0xpdmVUZXN0UHJvcEMiABAAUwBkAGsATABpAHYAZQBUAGUAcwB0AFYAYQBsAHUAZQABAA==";
+
+    [Fact]
+    public void SerializeAddRequest_MatchesServerAcceptedBuffer()
+    {
+        byte[] expected = Convert.FromBase64String(ServerAcceptedInBuffBase64);
+        byte[] actual = HistorianTagExtendedPropertyProtocol.SerializeAddRequest(
+            "RetestSdkWriteTepSdk3",
+            [new HistorianTagExtendedProperty("SdkLiveTestProp", "SdkLiveTestValue")]);
+        Assert.Equal(expected, actual);
+    }
+
+    [Fact]
+    public void SerializeAddRequest_SingleProperty_HasExpectedLayout()
+    {
+        byte[] buf = HistorianTagExtendedPropertyProtocol.SerializeAddRequest(
+            "ReactorTemp", [new HistorianTagExtendedProperty("Location", "PlantA")]);
+
+        int c = 0;
+        Assert.Equal(1u, BinaryPrimitives.ReadUInt32LittleEndian(buf.AsSpan(c, 4))); c += 4; // group count
+        Assert.Equal(0x01, buf[c++]);                                                        // group marker
+        Assert.Equal(0x09, buf[c++]);                                                        // compact string marker
+        Assert.Equal(11, BinaryPrimitives.ReadUInt16LittleEndian(buf.AsSpan(c, 2))); c += 2; // tag byte len
+        Assert.Equal("ReactorTemp", Encoding.ASCII.GetString(buf.AsSpan(c, 11))); c += 11;
+        Assert.Equal(1u, BinaryPrimitives.ReadUInt32LittleEndian(buf.AsSpan(c, 4))); c += 4; // property count
+        Assert.Equal(0x02, buf[c++]);                                                        // property marker
+        Assert.Equal(0x09, buf[c++]);
+        Assert.Equal(8, BinaryPrimitives.ReadUInt16LittleEndian(buf.AsSpan(c, 2))); c += 2;
+        Assert.Equal("Location", Encoding.ASCII.GetString(buf.AsSpan(c, 8))); c += 8;
+        Assert.Equal(0x43, buf[c++]);                                                        // VT_BSTR
+        Assert.Equal(14, BinaryPrimitives.ReadUInt16LittleEndian(buf.AsSpan(c, 2))); c += 2; // payloadLen = 2 + 6*2
+        Assert.Equal(6, BinaryPrimitives.ReadUInt16LittleEndian(buf.AsSpan(c, 2))); c += 2;  // char count
+        Assert.Equal("PlantA", Encoding.Unicode.GetString(buf.AsSpan(c, 12))); c += 12;
+        Assert.Equal(0x01, buf[c++]);  // group trailer
+        Assert.Equal(0x00, buf[c++]);  // buffer terminator
+        Assert.Equal(buf.Length, c);
+    }
+
+    [Fact]
+    public void SerializeAddRequest_MultipleProperties_EncodesCount()
+    {
+        byte[] buf = HistorianTagExtendedPropertyProtocol.SerializeAddRequest(
+            "T", [new HistorianTagExtendedProperty("A", "1"), new HistorianTagExtendedProperty("B", "2")]);
+        // group count @0, then 0x01 marker, 0x09 + u16(1) + "T" => property count at offset 4+1+1+2+1 = 9
+        Assert.Equal(2u, BinaryPrimitives.ReadUInt32LittleEndian(buf.AsSpan(9, 4)));
+    }
+
+    [Fact]
+    public void SerializeAddRequest_NoProperties_Throws()
+    {
+        Assert.Throws<ArgumentException>(() =>
+            HistorianTagExtendedPropertyProtocol.SerializeAddRequest("T", Array.Empty<HistorianTagExtendedProperty>()));
+    }
+}