docs(sphistorianclient): add CLAUDE.md + README.md

2026-06-19 05:58:13 -04:00
parent 81bf7322f0
commit 989db9317d
2 changed files with 267 additions and 0 deletions
@@ -0,0 +1,96 @@
+# 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 all 16 retrieval 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 |
+| `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.