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

Tag extended properties over 2020 WCF — GetTepByNm (HCAL R1.5)

Status: ✅ DONE + live-verified (2026-06-20). HistorianClient.GetTagExtendedPropertiesAsync(tag) reads a tag's extended (user-defined) properties over the 2020 WCF op aa/Retr/GetTagExtendedPropertiesFromName (GetTepByNm). Live-verified end-to-end from the pure-managed .NET 10 client against the local 2020 Historian.

The op

GetTepByNm is on the Retrieval service (IRetrievalServiceContract4):

bool GetTagExtendedPropertiesFromName(
    string handle,                       // Open2 storage-session GUID, UPPERCASE dash-no-braces
    byte[]  tagNames,                    // [MessageParameter pRequestBuff-style]
    ref uint sequence,                   // paging cursor (0 on first call)
    out byte[] tagExtendedProperties,    // result buffer
    out byte[] errorBuffer)

It is a string-handle op — reachable from the managed client because the handle is the Open2 storage-session GUID formatted storageSessionId.ToString("D").ToUpperInvariant() (the same handle format that unlocked GETRP/GETHI/ExeC; see wcf-string-handle-wall.md). The Retrieval service version handshake (Retr.GetV) is primed first, as the native client does.

Why the name-based path (not the TagQuery path)

There are two managed entry points:

• Index-based TagQuery.GetTagExtendedPropertyInfo(start, count, …) — requires a prior StartTagQuery (QTB). On this 2020 box QTB fails server-side (error 1 from CMdServer::StartTagQuery::StartActiveTagnamesQuery over \\.\pipe\aahMetadataServer\console), so this path is dead here regardless of handle format.
• Name-based HistorianAccess.GetTagExtendedPropertiesByName(tagName, fetchFromServer, …) — issues GetTepByNm directly with the tag name in tagNames, no QTB needed. Its second arg forces a server fetch when true; when false the C++ client reads a local cache and returns error 41 (Requested item not found) without any WCF round-trip. The SDK reproduces the name-based path.

Wire format (captured)

scripts/Capture-TagExtendedProperties.ps1 (NativeTraceHarness tag-extended-properties scenario + instrument-wcf-{write,read}message) → decode with scripts/decode-tag-properties-capture.py. Golden-pinned in WcfTagExtendedPropertyProtocolTests.

Request — tagNames buffer

uint32 count
per name: uint32 charCount + UTF-16LE chars

(For one tag: 01 00 00 00 + LL 00 00 00 + UTF-16 name.)

Response — tagExtendedProperties buffer

uint32 tagCount
per tag:
    byte   groupMarker            (observed 0x01)
    0x09 + uint16 byteLen + ASCII tagName        (compact-ASCII string)
    uint32 propertyCount
    per property:
        byte   propMarker         (observed 0x02 — likely the value type)
        0x09 + uint16 byteLen + ASCII propertyName
        0x43 + uint16 payloadLen + uint16 charCount + UTF-16LE value   (VT_BSTR CRetVariant)
    byte   trailingMarker         (observed 0x01)

payloadLen counts the charCount field (2 bytes) + the UTF-16 value bytes. Only the string value variant (0x43) is evidence-backed; other variant types throw ProtocolEvidenceMissingException (same discipline as GETRP). The single-byte 0x01/0x02/0x01 markers are pinned as observed constants from a single capture; their full semantics are not independently disambiguated.

Example (sanitized — real capture used a dev tag/value):

tag "Reactor.Temp1" → property "Location" = "Plant/AreaA"

Paging

GetTepByNm is sequence-paged like GetNextQueryResultBuffer: call with sequence = 0, parse the buffer, then re-call with the returned sequence. A small result returns everything on the first call; the next call returns an empty/nil buffer (with a benign CClientUtil::FillBufferFromVector terminator) — that is the stop signal. The SDK loops until the buffer carries no rows.

R1.6 (localized properties) — no distinct op on 2020

There is no GetTagLocalizedPropertiesFromName / GetTlpByNm op or GetTagLocalizedPropertiesByName method in current/aahClientManaged.dll — the only "localized" surfaces are ClientApp.GetLocalizedText and SMessageTextMap.GetLocalizedMessage (error-message / UI-text localization), not tag properties. So R1.6 collapses into R1.5: extended properties (GetTepByNm) are the user-defined tag-property read surface on 2020. R1.6 is closed as "no separate op," not left throwing.

R1.12 (localized-property write) — no distinct op on 2020 (mirror of R1.6)

Symmetric to R1.6 on the write side: there is no AddTagLocalizedProperties / DeleteTagLocalizedProperties (or any *LocalizedPropert* / TagLocalized*) symbol in any current/*.dll. A full symbol sweep of the shipped client DLLs surfaces only GetLocalizedText, GetLocalizedMessage, and LocalizedResourcesDir — all UI/error-message-text localization, not tag data. (The sweep does find the real write op AddTagExtendedProperties and the whole AddTag* family, so the absence of a localized op is a true negative, not a grep miss.) R1.12 is therefore closed as "no separate op" — the same conclusion as R1.6's read side. Extended-property write (R1.11 AddTEx) is the user-defined tag-property write surface on 2020; localized properties are a 2023 R2 / gRPC-only concept. Not left throwing.

Shipped surface

• HistorianClient.GetTagExtendedPropertiesAsync(tag) → IReadOnlyList<HistorianTagExtendedProperty> (Name/Value pairs; empty when the tag has none).
• HistorianTagExtendedPropertyProtocol (serializer/parser), HistorianWcfTagExtendedPropertyClient (orchestration), golden WcfTagExtendedPropertyProtocolTests, gated live GetTagExtendedPropertiesAsync_AgainstLocalHistorian_ReturnsProperties (set HISTORIAN_TEP_TAG to a tag with extended properties).