# ZB.MOM.WW.SPHistorianClient

Pure-managed .NET 10 client library for **AVEVA System Platform Historian** (Wonderware).
Part of the ZB.MOM.WW SCADA family.

No native AVEVA runtime dependency — `aahClientManaged.dll` / `aahClient.dll` are **not**
required. The wire protocol is re-implemented in managed C#. Live WCF transports require
Windows; offline tests and gRPC run cross-platform.

---

## Quick start

```csharp
using ZB.MOM.WW.SPHistorianClient;
using ZB.MOM.WW.SPHistorianClient.Models;

await using HistorianClient client = new(new HistorianClientOptions
{
    Host = "localhost",
    IntegratedSecurity = true,
    Transport = HistorianTransport.LocalPipe,
});

DateTime endUtc = DateTime.UtcNow;
DateTime startUtc = endUtc - TimeSpan.FromMinutes(10);

await foreach (HistorianSample sample in client.ReadRawAsync(
    "SysTimeSec", startUtc, endUtc, maxValues: 100))
{
    Console.WriteLine($"{sample.TimestampUtc:o}  {sample.NumericValue}  Q={sample.Quality}");
}
```

### DI registration

```csharp
// In Program.cs / Startup
services.AddZbSpHistorianClient(
    config.GetSection("Historian").Get<HistorianClientOptions>()!);

// Resolves HistorianClient (transient) from the container
```

---

## Supported operations

| Operation | Status |
|---|---|
| `ProbeAsync` | live-verified |
| `ReadRawAsync` | live-verified |
| `ReadAggregateAsync` | live-verified across the `RetrievalMode` enum (15 modes) |
| `ReadAtTimeAsync` | live-verified |
| `ReadBlocksAsync` | block history read |
| `ReadEventsAsync` | live-verified (typed event + property bag) |
| `BrowseTagNamesAsync` | live-verified |
| `GetTagMetadataAsync` | live-verified across many native data-type codes |
| `GetConnectionStatusAsync` | synthesized from authenticated probe |
| `GetStoreForwardStatusAsync` | synthesized defaults |
| `GetSystemParameterAsync` | live-verified |
| `EnsureTagAsync` | live-verified for analog `Float`; `Double`/`Int2`/`Int4`/`UInt4` supported |
| `DeleteTagAsync` | live-verified (see note below) |

> **Note:** Writing sample values is architecturally blocked — the Historian server cache only
> ingests from configured IOServer / Application Server pipelines. `DeleteTagAsync` server-side
> cascade may not always complete; use SMC as a fallback to clean up sandbox tags.

---

## Transport matrix

| Transport | Protocol | Platform | Verification |
|---|---|---|---|
| `LocalPipe` | WCF/MDAS over Net.NamedPipe | Windows-only | live-verified |
| `RemoteTcpIntegrated` | WCF/MDAS over Net.TCP + Windows auth | Windows-only | live-verified |
| `RemoteTcpCertificate` | WCF/MDAS over Net.TCP + TLS | Windows-only | `ProbeAsync` live-verified; deeper coverage pending |
| `RemoteGrpc` | gRPC (2023 R2) | cross-platform | unit-tested; live verification pending |

---

## Build and test

```bash
# From ZB.MOM.WW.SPHistorianClient/

dotnet build ZB.MOM.WW.SPHistorianClient.slnx
dotnet test  ZB.MOM.WW.SPHistorianClient.slnx

# Pack
dotnet pack  ZB.MOM.WW.SPHistorianClient.slnx -c Release -o ./artifacts
```

Offline unit tests (191 total) run on any OS. Live integration tests are gated by environment
variables (`HISTORIAN_HOST` for WCF, `HISTORIAN_GRPC_HOST` for gRPC) and skip cleanly when unset.
See `CLAUDE.md` for the full environment variable reference.