R1.1 ExecuteSqlCommandAsync (ExeC + GetR, NRBF DataTable, no BinaryFormatter)

Ship SQL command execution over the 2020 WCF aa/Retr/ExeC + aa/Retr/GetR ops: HistorianClient.ExecuteSqlCommandAsync(sql) -> HistorianSqlResult (columns + typed rows). String-handle ops reached with the Open2 storage-session GUID formatted uppercase (the handle format that unlocked GETRP/GETHI). Chain: Retr.GetV prime -> ExeC(handle, sql, option=0, ref queryHandle) -> GetR loop. Key gotcha captured: GetR returns FALSE even on success -- the byte stream is in pResultBuff regardless; false just signals the final page. So the orchestrator consumes the buffer first, then stops on a false result / empty page. GetR's pResultBuff is an NRBF-serialized System.Data.DataTable (SerializationFormat.Xml: members XmlSchema (XSD) + XmlDiffGram (rows)). BinaryFormatter is removed from .NET 10, so the stream is decoded read-only with the System.Formats.Nrbf package (NrbfDecoder) + XDocument -- no BinaryFormatter, no code execution. Values are typed per the XSD type, falling back to string. Adds: HistorianSqlResult / HistorianSqlColumn / HistorianSqlExecuteOption models, HistorianSqlResultProtocol (NRBF + diffgram parser), HistorianWcfSqlClient (ExeC/GetR orchestration with an AVEVA_HISTORIAN_SQL_DUMP diagnostic), dialect + public API. Golden WcfSqlResultProtocolTests pinned to the real clean GetR stream for the benign "SELECT 1 AS ProbeValue" (no sensitive data); gated live tests (single cell + multi-column/multi-row/NULL). Doc: wcf-exec-sql.md; roadmap R1.1 DONE; wall doc + memory updated (incl. the QTB-server-side nuance). 229 tests green. Note: a raw instrument-wcf capture corrupts a large pResultBuff with MDAS transport chunk markers (0x9F); the clean contract-level byte[] is dumped via the AVEVA_HISTORIAN_SQL_DUMP env var for the golden fixture. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B6mcaT2PjRFKcogzp9UkfC
2026-06-20 23:16:06 -04:00
parent 4da5287d01
commit 1a539882d0
12 changed files with 676 additions and 9 deletions
@@ -296,6 +296,65 @@ public sealed class HistorianClientIntegrationTests
        Assert.False(string.IsNullOrWhiteSpace(value));
    }

+    [Fact]
+    public async Task ExecuteSqlCommandAsync_AgainstLocalHistorian_ReturnsRecordSet()
+    {
+        string? host = Environment.GetEnvironmentVariable("HISTORIAN_HOST");
+        if (string.IsNullOrWhiteSpace(host) || !string.Equals(host, "localhost", StringComparison.OrdinalIgnoreCase) || !OperatingSystem.IsWindows())
+        {
+            return;
+        }
+
+        HistorianClient client = new(new HistorianClientOptions
+        {
+            Host = host,
+            IntegratedSecurity = true,
+            Transport = HistorianTransport.LocalPipe
+        });
+
+        // ExeC/GetR ride the storage-session GUID as an uppercase string handle. A constant SELECT
+        // returns a single int column; the DataTable is decoded from the NRBF stream (no BinaryFormatter).
+        AVEVA.Historian.Client.Models.HistorianSqlResult result =
+            await client.ExecuteSqlCommandAsync("SELECT 1 AS ProbeValue", cancellationToken: CancellationToken.None);
+
+        AVEVA.Historian.Client.Models.HistorianSqlColumn column = Assert.Single(result.Columns);
+        Assert.Equal("ProbeValue", column.Name);
+        IReadOnlyList<object?> row = Assert.Single(result.Rows);
+        Assert.Equal(1, Assert.Single(row));
+    }
+
+    [Fact]
+    public async Task ExecuteSqlCommandAsync_AgainstLocalHistorian_MultiColumnMultiRow()
+    {
+        string? host = Environment.GetEnvironmentVariable("HISTORIAN_HOST");
+        if (string.IsNullOrWhiteSpace(host) || !string.Equals(host, "localhost", StringComparison.OrdinalIgnoreCase) || !OperatingSystem.IsWindows())
+        {
+            return;
+        }
+
+        HistorianClient client = new(new HistorianClientOptions
+        {
+            Host = host,
+            IntegratedSecurity = true,
+            Transport = HistorianTransport.LocalPipe
+        });
+
+        // Fully synthetic query (no server data): two columns (int + string), two rows, one NULL —
+        // exercises the schema/diffgram parser beyond the single-cell case.
+        AVEVA.Historian.Client.Models.HistorianSqlResult result = await client.ExecuteSqlCommandAsync(
+            "SELECT 10 AS Num, 'alpha' AS Word UNION ALL SELECT 20, NULL",
+            cancellationToken: CancellationToken.None);
+
+        Assert.Equal(2, result.Columns.Count);
+        Assert.Equal("Num", result.Columns[0].Name);
+        Assert.Equal("Word", result.Columns[1].Name);
+        Assert.Equal(2, result.Rows.Count);
+        Assert.Equal(10, result.Rows[0][0]);
+        Assert.Equal("alpha", result.Rows[0][1]);
+        Assert.Equal(20, result.Rows[1][0]);
+        Assert.Null(result.Rows[1][1]);
+    }
+
    [Fact]
    public async Task GetConnectionStatusAsync_AgainstLocalHistorian_ReportsConnectedToServer()
    {
@@ -0,0 +1,79 @@
+using AVEVA.Historian.Client.Models;
+using AVEVA.Historian.Client.Protocol;
+using AVEVA.Historian.Client.Wcf;
+
+namespace AVEVA.Historian.Client.Tests;
+
+/// <summary>
+/// Golden tests for the ExeC/GetR SQL result codec. The fixture is the real, clean GetR
+/// <c>pResultBuff</c> captured from the live server for the benign query
+/// <c>SELECT 1 AS ProbeValue</c> (no sensitive data) — an NRBF stream wrapping a
+/// <c>System.Data.DataTable</c> serialized with <c>SerializationFormat.Xml</c>. It is the
+/// contract-level byte[] the WCF channel reassembles (free of MDAS transport chunk markers).
+/// </summary>
+public sealed class WcfSqlResultProtocolTests
+{
+    // GetR pResultBuff for "SELECT 1 AS ProbeValue" (1232 bytes), base64. Captured via the
+    // AVEVA_HISTORIAN_SQL_DUMP diagnostic in HistorianWcfSqlClient.
+    private const string GetRStreamBase64 =
+        "AAEAAAD/////AQAAAAAAAAAMAgAAAE5TeXN0ZW0uRGF0YSwgVmVyc2lvbj00LjAuMC4wLCBDdWx0dXJlPW5ldXRyYWwsIFB1Ymxp" +
+        "Y0tleVRva2VuPWI3N2E1YzU2MTkzNGUwODkFAQAAABVTeXN0ZW0uRGF0YS5EYXRhVGFibGUDAAAAGURhdGFUYWJsZS5SZW1vdGlu" +
+        "Z1ZlcnNpb24JWG1sU2NoZW1hC1htbERpZmZHcmFtAwEBDlN5c3RlbS5WZXJzaW9uAgAAAAkDAAAABgQAAACJBTw/eG1sIHZlcnNp" +
+        "b249IjEuMCIgZW5jb2Rpbmc9InV0Zi0xNiI/Pg0KPHhzOnNjaGVtYSB4bWxucz0iIiB4bWxuczp4cz0iaHR0cDovL3d3dy53My5v" +
+        "cmcvMjAwMS9YTUxTY2hlbWEiIHhtbG5zOm1zZGF0YT0idXJuOnNjaGVtYXMtbWljcm9zb2Z0LWNvbTp4bWwtbXNkYXRhIj4NCiAg" +
+        "PHhzOmVsZW1lbnQgbmFtZT0iVGFibGUxIj4NCiAgICA8eHM6Y29tcGxleFR5cGU+DQogICAgICA8eHM6c2VxdWVuY2U+DQogICAg" +
+        "ICAgIDx4czplbGVtZW50IG5hbWU9IlByb2JlVmFsdWUiIG1zZGF0YTpSZWFkT25seT0idHJ1ZSIgdHlwZT0ieHM6aW50IiBtc2Rh" +
+        "dGE6dGFyZ2V0TmFtZXNwYWNlPSIiIC8+DQogICAgICA8L3hzOnNlcXVlbmNlPg0KICAgIDwveHM6Y29tcGxleFR5cGU+DQogIDwv" +
+        "eHM6ZWxlbWVudD4NCiAgPHhzOmVsZW1lbnQgbmFtZT0idG1wRGF0YVNldCIgbXNkYXRhOklzRGF0YVNldD0idHJ1ZSIgbXNkYXRh" +
+        "Ok1haW5EYXRhVGFibGU9IlRhYmxlMSIgbXNkYXRhOlVzZUN1cnJlbnRMb2NhbGU9InRydWUiPg0KICAgIDx4czpjb21wbGV4VHlw" +
+        "ZT4NCiAgICAgIDx4czpjaG9pY2UgbWluT2NjdXJzPSIwIiBtYXhPY2N1cnM9InVuYm91bmRlZCIgLz4NCiAgICA8L3hzOmNvbXBs" +
+        "ZXhUeXBlPg0KICA8L3hzOmVsZW1lbnQ+DQo8L3hzOnNjaGVtYT4GBQAAAJoCPGRpZmZncjpkaWZmZ3JhbSB4bWxuczptc2RhdGE9" +
+        "InVybjpzY2hlbWFzLW1pY3Jvc29mdC1jb206eG1sLW1zZGF0YSIgeG1sbnM6ZGlmZmdyPSJ1cm46c2NoZW1hcy1taWNyb3NvZnQt" +
+        "Y29tOnhtbC1kaWZmZ3JhbS12MSI+DQogIDx0bXBEYXRhU2V0Pg0KICAgIDxUYWJsZTEgZGlmZmdyOmlkPSJUYWJsZTExIiBtc2Rh" +
+        "dGE6cm93T3JkZXI9IjAiPg0KICAgICAgPFByb2JlVmFsdWU+MTwvUHJvYmVWYWx1ZT4NCiAgICA8L1RhYmxlMT4NCiAgPC90bXBE" +
+        "YXRhU2V0Pg0KPC9kaWZmZ3I6ZGlmZmdyYW0+BAMAAAAOU3lzdGVtLlZlcnNpb24EAAAABl9NYWpvcgZfTWlub3IGX0J1aWxkCV9S" +
+        "ZXZpc2lvbgAAAAAICAgIAgAAAAAAAAD//////////ws=";
+
+    [Fact]
+    public void Parse_DataTableStream_ExtractsColumnAndTypedRow()
+    {
+        byte[] stream = Convert.FromBase64String(GetRStreamBase64);
+
+        HistorianSqlResult result = HistorianSqlResultProtocol.Parse(stream, returnValue: 0);
+
+        HistorianSqlColumn column = Assert.Single(result.Columns);
+        Assert.Equal("ProbeValue", column.Name);
+        Assert.Equal("xs:int", column.SchemaType);
+
+        IReadOnlyList<object?> row = Assert.Single(result.Rows);
+        object? value = Assert.Single(row);
+        Assert.Equal(1, value);                  // typed to int per the xs:int schema
+        Assert.IsType<int>(value);
+        Assert.Equal(0, result.ReturnValue);
+    }
+
+    [Fact]
+    public void Parse_PreservesReturnValue()
+    {
+        byte[] stream = Convert.FromBase64String(GetRStreamBase64);
+        HistorianSqlResult result = HistorianSqlResultProtocol.Parse(stream, returnValue: 7);
+        Assert.Equal(7, result.ReturnValue);
+    }
+
+    [Fact]
+    public void Parse_EmptyBuffer_ReturnsEmptyResult()
+    {
+        HistorianSqlResult result = HistorianSqlResultProtocol.Parse(ReadOnlyMemory<byte>.Empty, returnValue: 3);
+        Assert.Empty(result.Columns);
+        Assert.Empty(result.Rows);
+        Assert.Equal(3, result.ReturnValue);
+    }
+
+    [Fact]
+    public void Parse_NonNrbfBuffer_Throws()
+    {
+        byte[] garbage = [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08];
+        Assert.Throws<ProtocolEvidenceMissingException>(
+            () => HistorianSqlResultProtocol.Parse(garbage, returnValue: 0));
+    }
+}