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

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.

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:

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:

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.