Joseph Doherty
112 lines
4.9 KiB
Markdown
112 lines
4.9 KiB
Markdown
# .NET Client Projects
|
|
|
|
The .NET client workspace contains the MXAccess Gateway client library, test
|
|
CLI, and unit tests.
|
|
|
|
## Projects
|
|
|
|
| Project | Purpose |
|
|
|---------|---------|
|
|
| `MxGateway.Client` | .NET 10 library entry point, raw gRPC calls, and session helpers. |
|
|
| `MxGateway.Client.Cli` | Test CLI for smoke and diagnostic commands. |
|
|
| `MxGateway.Client.Tests` | Unit tests for client options, generated contract wiring, auth metadata, session helpers, cancellation, and event streaming. |
|
|
|
|
The projects reference `src/MxGateway.Contracts/MxGateway.Contracts.csproj` so
|
|
the client compiles against the same generated protobuf and gRPC types as the
|
|
gateway. `clients/dotnet/generated` remains reserved for generator output if a
|
|
future client build switches to client-local `Grpc.Tools` generation.
|
|
|
|
## Build And Test
|
|
|
|
```powershell
|
|
dotnet build clients/dotnet/MxGateway.Client.sln
|
|
dotnet test clients/dotnet/MxGateway.Client.sln --no-build
|
|
```
|
|
|
|
## Client Usage
|
|
|
|
`MxGatewayClient` opens a gRPC channel to the gateway and attaches the API key
|
|
to every unary and streaming call as `authorization: Bearer <api-key>`.
|
|
Cancellation tokens passed to the public methods flow to the generated gRPC
|
|
call. Client-side cancellation stops waiting for the gateway response; it does
|
|
not abort an MXAccess COM call that is already executing inside a worker.
|
|
|
|
```csharp
|
|
await using MxGatewayClient client = MxGatewayClient.Create(
|
|
new MxGatewayClientOptions
|
|
{
|
|
Endpoint = new Uri("http://localhost:5000"),
|
|
ApiKey = apiKey,
|
|
});
|
|
|
|
MxGatewaySession session = await client.OpenSessionAsync();
|
|
try
|
|
{
|
|
int serverHandle = await session.RegisterAsync("sample-client");
|
|
int itemHandle = await session.AddItemAsync(
|
|
serverHandle,
|
|
"Area001.Pump001.Speed");
|
|
|
|
await session.AdviseAsync(serverHandle, itemHandle);
|
|
}
|
|
finally
|
|
{
|
|
await session.CloseAsync();
|
|
}
|
|
```
|
|
|
|
Use `OpenSessionRawAsync`, `CloseSessionRawAsync`, `InvokeAsync`, and
|
|
`StreamEventsAsync` when tests or parity tools need direct generated protobuf
|
|
messages. `MxGatewaySession.OpenSessionReply` keeps the raw session-open reply
|
|
available, and command helpers have `*RawAsync` variants when callers need the
|
|
complete `MxCommandReply`.
|
|
|
|
`MxGatewaySession.CloseAsync` is explicit and idempotent. Repeated calls return
|
|
the first `CloseSessionReply` instead of sending another close request.
|
|
|
|
## Values, Status, And Errors
|
|
|
|
The client provides extension helpers for generated protobuf values. Use
|
|
`ToMxValue()` on .NET scalar values and typed arrays to create `MxValue`
|
|
instances for `Write` and `Write2`. Use `ToClrValue()` and
|
|
`GetProjectionKind()` when test or diagnostic code needs to inspect generated
|
|
`MxValue` replies while preserving `rawDiagnostic`, raw data type fields, and
|
|
raw byte payloads.
|
|
|
|
`MxStatusProxy.IsSuccess()` and `ToDiagnosticSummary()` expose MXAccess status
|
|
arrays without collapsing them into a single gateway success flag. Command
|
|
reply helpers follow the same split:
|
|
|
|
```csharp
|
|
reply.EnsureProtocolSuccess();
|
|
reply.EnsureMxAccessSuccess();
|
|
```
|
|
|
|
`EnsureProtocolSuccess()` raises gateway, session, worker, or command
|
|
exceptions for gateway-level failures. It leaves
|
|
`PROTOCOL_STATUS_CODE_MXACCESS_FAILURE` to `EnsureMxAccessSuccess()` so callers
|
|
can keep the full `MxCommandReply`, HRESULT, and status array when MXAccess
|
|
itself rejects a command. `MxAccessException.Reply` contains the raw generated
|
|
reply.
|
|
|
|
## CLI Usage
|
|
|
|
The test CLI supports deterministic JSON output for automation:
|
|
|
|
```powershell
|
|
dotnet run --project clients/dotnet/MxGateway.Client.Cli -- version --json
|
|
dotnet run --project clients/dotnet/MxGateway.Client.Cli -- open-session --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
|
|
dotnet run --project clients/dotnet/MxGateway.Client.Cli -- register --session-id <id> --client-name mxgw-dotnet-cli --json
|
|
dotnet run --project clients/dotnet/MxGateway.Client.Cli -- add-item --session-id <id> --server-handle 1 --item Area001.Pump001.Speed --json
|
|
dotnet run --project clients/dotnet/MxGateway.Client.Cli -- advise --session-id <id> --server-handle 1 --item-handle 1 --json
|
|
dotnet run --project clients/dotnet/MxGateway.Client.Cli -- write --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --json
|
|
dotnet run --project clients/dotnet/MxGateway.Client.Cli -- write2 --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --timestamp 2026-01-01T00:00:00Z --json
|
|
dotnet run --project clients/dotnet/MxGateway.Client.Cli -- stream-events --session-id <id> --max-events 1 --json
|
|
dotnet run --project clients/dotnet/MxGateway.Client.Cli -- smoke --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --item Area001.Pump001.Speed --json
|
|
```
|
|
|
|
`smoke` opens a session, registers a client, adds one item, advises it,
|
|
optionally writes a value when `--type` and `--value` are supplied, reads a
|
|
bounded event stream, and closes the session in a `finally` block. CLI error
|
|
output redacts API keys supplied through `--api-key`.
|