histsdk/AGENTS.md

AGENTS.md

Mission

Build a fully managed .NET 10 replacement for AVEVA Historian's aahClientManaged / aahClient.dll stack by reverse-engineering the native binary Historian protocol.

The target is an in-process managed SDK that can replace the current .NET Framework/native sidecar used by OtOpcUa.Driver.Historian.Wonderware.

Chosen Approach

Use the reverse-engineering path from instructions.md:

1. Decompile current\aahClientManaged.dll to understand the managed wrapper surface, connection flow, query types, data models, error handling, and native calls.
2. Inspect current\aahClient.dll and the matching AVEVA install DLLs to map the native ABI and identify transport/framing responsibilities.
3. Capture traffic from real Historian sessions and derive the on-the-wire protocol for the required read-only operations.
4. Implement the protocol in a pure managed .NET 10 client.

Do not pursue the REST API implementation unless explicitly asked. Do not build a P/Invoke shim as the primary solution; it is useful only as an analysis aid.

Repository Layout

This workspace is an SDK investigation folder, not a full application repo.

• instructions.md - source planning document and decision record.
• current\ - the seven DLLs the existing sidecar links against today.
• aveva-install-x64\ - full 64-bit AVEVA Historian client-side DLL set.
• aveva-install-x86\ - full 32-bit AVEVA Historian client-side DLL set.

Use current\ first because it represents the deployed sidecar dependency set. Use aveva-install-* to compare architecture-specific behavior and locate adjacent client APIs.

Required SDK Surface

Keep the managed SDK narrowly scoped to the operations used in production:

• ReadRawAsync(tag, startUtc, endUtc, maxValues)
• ReadAggregateAsync(tag, startUtc, endUtc, mode, interval)
• ReadAtTimeAsync(tag, timestampsUtc)
• ReadEventsAsync(startUtc, endUtc)
• ProbeAsync()

The existing alarm-event write path is dormant. Do not implement write-back unless a new requirement is supplied.

Reverse-Engineering Workflow

1. Managed Wrapper Analysis

Use dnSpy or ILSpy on current\aahClientManaged.dll.

Document:

• Public types and methods used for connections and queries.
• P/Invoke or native interop entry points.
• Constructor arguments, enum values, flags, and default values.
• Query argument structures for raw, aggregate, at-time, and event reads.
• Returned sample/event models, quality fields, timestamp handling, and error propagation.

Prefer producing small Markdown notes under a future docs\reverse-engineering\ folder rather than relying on memory.

2. Native ABI Mapping

Inspect current\aahClient.dll and compare with:

• aveva-install-x64\aahClient.dll
• aveva-install-x86\aahClient.dll
• aahClientCommon.dll
• aahDataSetClient.dll
• aahClientConfig.dll

Useful tools:

• dumpbin /exports
• Dependencies or Process Monitor
• API Monitor
• Detours or equivalent call hooks

Document function names, calling conventions, pointer ownership, HRESULT/error patterns, string encodings, and architecture differences.

3. Wire Capture

Capture real Historian sessions with Wireshark while running the existing Wonderware sidecar/client against a development Historian.

Capture each scenario independently:

• Connection open/close and health probe.
• Raw history query.
• Aggregate query for each required retrieval mode.
• At-time/interpolated query.
• Event query.
• Error cases: bad tag, empty range, invalid credentials, server offline.

For every capture, record:

• Historian version and architecture.
• Client DLL version and file hash.
• Server host/port.
• Query parameters.
• Expected logical result set.
• Packet capture filename.

Do not commit sensitive packet captures, credentials, server names, or customer tag names. Sanitize before adding any fixtures or notes.

4. Protocol Model

Derive and document:

• Session handshake.
• Authentication exchange, if present.
• Message framing and length prefixes.
• Message type identifiers.
• Request/response correlation.
• Endianness.
• Timestamp encoding.
• String encoding.
• Numeric value encoding.
• Quality/status encoding.
• Error frame format.
• Event payload format.

Add version notes whenever behavior differs between the installed 2020 DLLs and newer Historian versions.

5. Managed Implementation Shape

When implementation starts, use this project shape unless the real repo dictates otherwise:

src/AVEVA.Historian.Client/
  AVEVA.Historian.Client.csproj
  HistorianClient.cs
  HistorianClientOptions.cs
  Models/
    HistorianSample.cs
    HistorianAggregateSample.cs
    HistorianEvent.cs
    RetrievalMode.cs
  Protocol/
    HistorianConnection.cs
    HistorianFrame.cs
    HistorianMessageType.cs
    HistorianProtocolReader.cs
    HistorianProtocolWriter.cs
  Transport/
    TcpHistorianTransport.cs
    ClusterEndpointPicker.cs
  Internal/
    BackoffPolicy.cs

Keep protocol parsing isolated from transport I/O so captured frames can be tested without a live Historian.

Testing Expectations

Start with deterministic tests around protocol encoding/decoding:

• Golden byte fixtures for each message kind.
• Round-trip tests for request builders.
• Parser tests for captured and sanitized response frames.
• Timestamp, quality, and string encoding edge cases.
• Error frame parsing.

Add live integration tests only behind explicit configuration, such as:

• HISTORIAN_HOST
• HISTORIAN_PORT
• HISTORIAN_USER
• HISTORIAN_PASSWORD
• HISTORIAN_TEST_TAG

Integration tests must skip cleanly when these values are not configured.

Constraints

• Keep the final SDK pure managed .NET 10.
• Avoid adding native runtime dependencies to the production SDK.
• Avoid broad API design. Implement only the operations listed above.
• Treat AVEVA protocol details as version-sensitive; document assumptions.
• Do not redistribute AVEVA binaries.
• Do not commit credentials, proprietary captures, or customer data.
• Do not delete or overwrite DLLs in current\ or aveva-install-*.

Definition of Done

For the reverse-engineering phase:

• Managed wrapper public surface and native entry points are documented.
• Required query flows have sanitized captures or byte-level notes.
• Message framing, request fields, response fields, and error frames are described well enough to implement parser tests.

For the SDK phase:

• The managed client implements the required read-only surface.
• Unit tests cover protocol parse/build behavior.
• Integration tests can validate against a configured live Historian.
• The SDK can replace the existing sidecar call sites without requiring aahClientManaged.dll or aahClient.dll at runtime.