# .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 ``` ## Packaging Create local library and CLI artifacts from the repository root: ```powershell $dotnetPackageOutput = Join-Path (Get-Location) 'artifacts/clients/dotnet' dotnet pack clients/dotnet/MxGateway.Client/MxGateway.Client.csproj -c Release -p:PackageOutputPath="$dotnetPackageOutput" dotnet publish clients/dotnet/MxGateway.Client.Cli/MxGateway.Client.Cli.csproj -c Release -o artifacts/clients/dotnet/mxgw-dotnet ``` The library package references the shared contracts project at build time. The published CLI runs from `artifacts/clients/dotnet/mxgw-dotnet`. ## Regenerating Protobuf Bindings The .NET client uses the generated C# types from `src/MxGateway.Contracts/Generated`. Regenerate those files through the contracts project: ```powershell dotnet build src/MxGateway.Contracts/MxGateway.Contracts.csproj ``` ## Client Usage `MxGatewayClient` opens a gRPC channel to the gateway and attaches the API key to every unary and streaming call as `authorization: Bearer `. 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 --client-name mxgw-dotnet-cli --json dotnet run --project clients/dotnet/MxGateway.Client.Cli -- add-item --session-id --server-handle 1 --item Area001.Pump001.Speed --json dotnet run --project clients/dotnet/MxGateway.Client.Cli -- advise --session-id --server-handle 1 --item-handle 1 --json dotnet run --project clients/dotnet/MxGateway.Client.Cli -- write --session-id --server-handle 1 --item-handle 1 --type int32 --value 123 --json dotnet run --project clients/dotnet/MxGateway.Client.Cli -- write2 --session-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 --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`. Use TLS options for a secured gateway: ```powershell dotnet run --project clients/dotnet/MxGateway.Client.Cli -- smoke --endpoint https://mxgateway.example.local:5001 --tls --ca-file C:\certs\mxgateway-ca.pem --server-name mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item Area001.Pump001.Speed --json ``` ## Integration Checks Run live checks only when a gateway and MXAccess-backed worker are available: ```powershell $env:MXGATEWAY_INTEGRATION = '1' $env:MXGATEWAY_ENDPOINT = 'http://localhost:5000' $env:MXGATEWAY_API_KEY = '' $env:MXGATEWAY_TEST_ITEM = 'Area001.Pump001.Speed' dotnet run --project clients/dotnet/MxGateway.Client.Cli -- smoke --endpoint $env:MXGATEWAY_ENDPOINT --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json ``` ## Related Documentation - [Client Packaging](../../docs/ClientPackaging.md) - [Client Proto Generation](../../docs/client-proto-generation.md) - [.NET Client Detailed Design](../../docs/clients-dotnet-csharp-design.md)