histsdk/docs/reverse-engineering/wcf-add-tag-extended-properties.md

Extended-property write over 2020 WCF — AddTEx (HCAL R1.11)

Status: ✅ Add DONE + live-verified (2026-06-21). Delete (DelTep) deferred — see below. HistorianClient.AddTagExtendedPropertiesAsync / AddTagExtendedPropertyAsync writes user-defined extended properties onto an existing tag via the 2020 WCF AddTEx (AddTagExtendedProperties) op, and they read back via the R1.5 GetTagExtendedPropertiesAsync path. Verified end-to-end from the pure-managed .NET 10 client against the local 2020 Historian (create tag → add property → read back → delete tag).

The op

bool AddTagExtendedProperties(string handle, byte[] inBuff, out byte[] errorBuffer)   // AddTEx

On IHistoryServiceContract2 (History service). Requires a write-enabled connection (Open2 mode 0x401) and the uppercase storage-session GUID handle — the SDK reuses the write orchestrator's open + priming chain (the same one used by EnsT2/DelT). The tag is referenced by name inside inBuff; no extra per-connection tag registration was needed (the server resolves it).

The inBuff — the exact inverse of the R1.5 read response

The native AddTagExtendedProperties(TagExtendedPropertyGroupList, out err) packs its groups into the AddTEx inBuff with the same framing the R1.5 GetTepByNm response uses, so the write serializer is the inverse of HistorianTagExtendedPropertyProtocol.ParseResponse:

uint32 groupCount (= 1)
byte 0x01                         (group marker)
0x09 + uint16 byteLen + ASCII tagName      (compact-ASCII string)
uint32 propertyCount
repeated propertyCount times:
    byte 0x02                     (property marker)
    0x09 + uint16 byteLen + ASCII propertyName
    0x43 + uint16 payloadLen + uint16 charCount + UTF-16LE value   (VT_BSTR variant; payloadLen = 2 + charCount*2)
byte 0x01                         (group trailer)
byte 0x00                         (buffer terminator)

⚠️ The trailing 0x01 0x00 matters: the group trailer is 0x01 (as in the read parser) plus a final 0x00 buffer terminator. Omitting the 0x00 makes inBuff one byte short and the server throws SErrorException in aahClientAccessPoint::CHistStorage::AddTagExtendedProperties (AddTEx returns false). The read parser tolerates the extra byte because it only consumes one trailing byte per group.

Only the string (0x43 VT_BSTR) value variant is evidence-backed (matching the read path). The raw instrument capture mangles the final byte with MDAS chunk markers, so the golden fixture pins the clean byte[] the SDK handed the channel (dumped via AVEVA_HISTORIAN_TEP_DUMP) — the exact buffer the live server accepted.

Delete (DelTep) — deferred

DeleteTagExtendedProperties (DelTep) is not shipped yet. The native DeleteTagExtendedPropertiesByName(tag, propertyNames, deleteFromServer, out err) performs a client-side sync check and returns error 229 ("Tag extended property not synchronized with server") when deleting a just-added property — so the DelTep request never reached the wire and its inBuff could not be captured. Capturing it needs a property that is already server-synchronized (add it in one session, then delete in a later one). Left for a follow-up rather than shipping a guessed buffer.

Shipped surface

• HistorianClient.AddTagExtendedPropertiesAsync(tag, IReadOnlyList<HistorianTagExtendedProperty>) and AddTagExtendedPropertyAsync(tag, name, value).
• HistorianTagExtendedPropertyProtocol.SerializeAddRequest (the inBuff serializer; lives beside the R1.5 read parser); orchestrator path in HistorianWcfTagWriteOrchestrator.
• Golden WcfTagExtendedPropertyWriteProtocolTests (pins the server-accepted buffer + layout); gated live test AddTagExtendedPropertiesAsync_AgainstLocalHistorian_WritesAndReadsBack.

Capture / decode tooling

scripts/Capture-AddTagExtendedProperties.ps1 (native-harness add-tep scenario + instrument-wcf-{write,read}message; sandbox-guarded create→add→[optional delete]) and scripts/decode-add-tep-capture.py.