dohertj2/histsdk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

R1.11 AddTagExtendedPropertiesAsync: extended-property write via AddTEx

Browse Source 
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
This commit is contained in:
Joseph Doherty
2026-06-21 01:43:19 -04:00
parent 108220c36b
commit 08b950caee
11 changed files with 701 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/AVEVA.Historian.Client/HistorianClient.cs
+22
View File
@@ -179,6 +179,28 @@ public sealed class HistorianClient : IAsyncDisposable
return _protocol.GetTagExtendedPropertiesAsync(tag, cancellationToken);
}
/// <summary>
/// Adds (or updates) extended (user-defined) properties on an existing tag via the 2020 WCF
/// <c>AddTEx</c> (AddTagExtendedProperties) op. Requires a write-enabled connection. String-valued
/// properties only (the evidence-backed surface). The new properties are read back via
/// <see cref="GetTagExtendedPropertiesAsync"/>. See <c>HistorianTagExtendedPropertyProtocol</c>.
/// </summary>
public Task<bool> AddTagExtendedPropertiesAsync(string tag, IReadOnlyList<HistorianTagExtendedProperty> properties, CancellationToken cancellationToken = default)
{
ArgumentException.ThrowIfNullOrWhiteSpace(tag);
ArgumentNullException.ThrowIfNull(properties);
return new HistorianWcfTagWriteOrchestrator(_options).AddTagExtendedPropertiesAsync(tag, properties, cancellationToken);
}
/// <summary>Convenience overload of <see cref="AddTagExtendedPropertiesAsync"/> for a single
/// string-valued property.</summary>
public Task<bool> AddTagExtendedPropertyAsync(string tag, string name, string value, CancellationToken cancellationToken = default)
{
ArgumentException.ThrowIfNullOrWhiteSpace(tag);
ArgumentException.ThrowIfNullOrWhiteSpace(name);
return AddTagExtendedPropertiesAsync(tag, [new HistorianTagExtendedProperty(name, value ?? string.Empty)], cancellationToken);
}
/// <summary>
/// Creates or updates the named tag in the Historian Runtime database via
/// <c>EnsureTags2</c>. Currently only <see cref="HistorianDataType.Float"/> is
src/AVEVA.Historian.Client/Wcf/HistorianTagExtendedPropertyProtocol.cs
+77
View File
@@ -55,6 +55,83 @@ internal static class HistorianTagExtendedPropertyProtocol
return stream.ToArray();
}
private const byte GroupMarker = 0x01;
private const byte PropertyMarker = 0x02;
/// <summary>
/// Serializes the <c>AddTEx</c> (AddTagExtendedProperties) inBuff for a single tag's string
/// properties. The buffer is the exact inverse of the <see cref="ParseResponse"/> group framing
/// (decoded from a native <c>AddTagExtendedProperties</c> capture; see
/// <c>docs/reverse-engineering/wcf-add-tag-extended-properties.md</c>):
/// <code>
/// uint32 groupCount (= 1)
/// byte 0x01 (group marker)
/// 0x09 + uint16 byteLen + ASCII tagName
/// uint32 propertyCount
/// repeated: byte 0x02 (property marker) + 0x09 + uint16 byteLen + ASCII propName
/// + 0x43 VT_BSTR + uint16 payloadLen + uint16 charCount + UTF-16LE value
/// byte 0x01 (group trailer)
/// </code>
/// Only string-valued properties are evidence-backed (the VT_BSTR variant), matching the read path.
/// </summary>
public static byte[] SerializeAddRequest(string tagName, IReadOnlyList<HistorianTagExtendedProperty> properties)
{
ArgumentException.ThrowIfNullOrEmpty(tagName);
ArgumentNullException.ThrowIfNull(properties);
if (properties.Count == 0)
{
throw new ArgumentException("At least one extended property is required.", nameof(properties));
}
using MemoryStream stream = new();
Span<byte> u32 = stackalloc byte[4];
BinaryPrimitives.WriteUInt32LittleEndian(u32, 1u); // group count
stream.Write(u32);
stream.WriteByte(GroupMarker);
WriteCompactAscii(stream, tagName);
BinaryPrimitives.WriteUInt32LittleEndian(u32, checked((uint)properties.Count));
stream.Write(u32);
foreach (HistorianTagExtendedProperty property in properties)
{
ArgumentException.ThrowIfNullOrEmpty(property?.Name, nameof(properties));
stream.WriteByte(PropertyMarker);
WriteCompactAscii(stream, property.Name);
WriteVariantString(stream, property.Value ?? string.Empty);
}
stream.WriteByte(GroupMarker); // group trailer
stream.WriteByte(0x00); // buffer terminator (captured: the native inBuff ends 0x01 0x00)
return stream.ToArray();
}
private static void WriteCompactAscii(MemoryStream stream, string value)
{
byte[] ascii = Encoding.ASCII.GetBytes(value);
stream.WriteByte(CompactStringMarker);
Span<byte> u16 = stackalloc byte[2];
BinaryPrimitives.WriteUInt16LittleEndian(u16, checked((ushort)ascii.Length));
stream.Write(u16);
stream.Write(ascii, 0, ascii.Length);
}
private static void WriteVariantString(MemoryStream stream, string value)
{
byte[] utf16 = Encoding.Unicode.GetBytes(value);
ushort charCount = checked((ushort)value.Length);
stream.WriteByte(VariantTypeBStr);
Span<byte> u16 = stackalloc byte[2];
// payloadLen = the bytes that follow it: the uint16 charCount field (2) + UTF-16 bytes.
BinaryPrimitives.WriteUInt16LittleEndian(u16, checked((ushort)(2 + utf16.Length)));
stream.Write(u16);
BinaryPrimitives.WriteUInt16LittleEndian(u16, charCount);
stream.Write(u16);
stream.Write(utf16, 0, utf16.Length);
}
/// <summary>
/// Parses the <c>tagExtendedProperties</c> response buffer into a flat list of
/// (tagName, propertyName, value) rows. Returns an empty list when the buffer carries no rows
src/AVEVA.Historian.Client/Wcf/HistorianWcfTagWriteOrchestrator.cs
+49
View File
@@ -41,6 +41,18 @@ internal sealed class HistorianWcfTagWriteOrchestrator
return Task.Run(() => DeleteTag(tagName), cancellationToken);
}
public Task<bool> AddTagExtendedPropertiesAsync(
string tagName, IReadOnlyList<HistorianTagExtendedProperty> properties, CancellationToken cancellationToken)
{
ArgumentException.ThrowIfNullOrWhiteSpace(tagName);
ArgumentNullException.ThrowIfNull(properties);
if (properties.Count == 0)
{
throw new ArgumentException("At least one extended property is required.", nameof(properties));
}
return Task.Run(() => AddTagExtendedProperties(tagName, properties), cancellationToken);
}
private bool EnsureTag(HistorianTagDefinition definition)
{
Guid contextKey = Guid.NewGuid();
@@ -86,6 +98,43 @@ internal sealed class HistorianWcfTagWriteOrchestrator
return result;
}
private bool AddTagExtendedProperties(string tagName, IReadOnlyList<HistorianTagExtendedProperty> properties)
{
Guid contextKey = Guid.NewGuid();
var (histBinding, histEndpoint, _, _) = HistorianWcfBindingFactory.CreateBindingPair(_options);
Binding auxBinding = HistorianWcfBindingFactory.CreateAuxiliaryBinding(_options);
EndpointAddress statusEndpoint = HistorianWcfBindingFactory.CreateAuxiliaryEndpointAddress(_options, HistorianWcfServiceNames.Status);
EndpointAddress transactionEndpoint = HistorianWcfBindingFactory.CreateAuxiliaryEndpointAddress(_options, HistorianWcfServiceNames.Transaction);
EndpointAddress retrievalEndpoint = _options.Transport == HistorianTransport.LocalPipe
? HistorianWcfBindingFactory.CreatePipeEndpointAddress(_options.Host, HistorianWcfServiceNames.Retrieval)
: HistorianWcfBindingFactory.CreateEndpointAddress(_options.Host, _options.Port, HistorianWcfServiceNames.Retrieval);
bool result = false;
HistorianWcfAuthChainHelper.OpenAuthenticatedConnection(
_options, histBinding, histEndpoint, contextKey, CancellationToken.None,
connectionMode: HistorianWcfAuthChainHelper.NativeIntegratedWriteEnabledConnectionMode,
additionalSetup: (historyChannel, context) =>
{
RunWritePriming(historyChannel, context, auxBinding, statusEndpoint, transactionEndpoint, retrievalEndpoint);
string handle = context.StorageSessionId.ToString("D").ToUpperInvariant();
byte[] inBuff = HistorianTagExtendedPropertyProtocol.SerializeAddRequest(tagName, properties);
DumpTepIfRequested(inBuff);
bool ok = historyChannel.AddTagExtendedProperties(handle, inBuff, out byte[] errorBuffer);
WriteDiag("AddTEx", $"Returned={ok} Tag={tagName} PropCount={properties.Count} InLen={inBuff.Length} ErrLen={errorBuffer?.Length ?? -1} ErrHex={(errorBuffer is null ? "<null>" : Convert.ToHexString(errorBuffer))}");
result = ok;
});
return result;
}
/// <summary>Env-gated dump of the clean AddTEx inBuff (base64) for golden-fixture capture,
/// mirroring the rename/SQL dump hooks — avoids hand-stitching MDAS chunk markers.</summary>
private static void DumpTepIfRequested(byte[] inBuff)
{
string? path = Environment.GetEnvironmentVariable("AVEVA_HISTORIAN_TEP_DUMP");
if (string.IsNullOrWhiteSpace(path)) return;
try { File.AppendAllText(path, Convert.ToBase64String(inBuff) + Environment.NewLine); } catch { }
}
private static bool SendEnsureTags2(
IHistoryServiceContract2 historyChannel,
HistorianWcfAuthChainHelper.OpenConnectionContext context,