scadalink-design/lmxproxy/docs/requirements/Component-MxAccessClient.md

# Component: MxAccessClient

## Purpose

The core component that wraps the ArchestrA MXAccess COM API, providing connection management, tag read/write operations, and subscription-based value change notifications. This is the bridge between the gRPC service layer and AVEVA System Platform.

## Location

`src/ZB.MOM.WW.LmxProxy.Host/MxAccess/MxAccessClient.cs` — partial class split across 6 files:
- `MxAccessClient.cs` — Main class, properties, disposal, factory.
- `MxAccessClient.Connection.cs` — Connection lifecycle (connect, disconnect, reconnect, cleanup).
- `MxAccessClient.ReadWrite.cs` — Read and write operations with retry and concurrency control.
- `MxAccessClient.Subscription.cs` — Subscription management and stored subscription state.
- `MxAccessClient.EventHandlers.cs` — COM event handlers (OnDataChange, OnWriteComplete, OperationComplete).
- `MxAccessClient.NestedTypes.cs` — Internal types and enums.

## Responsibilities

- Manage the MXAccess COM object lifecycle (create, register, unregister, release).
- Maintain connection state (Disconnected, Connecting, Connected, Disconnecting, Error, Reconnecting) and fire state change events.
- Execute read and write operations against MXAccess with concurrency control via semaphores.
- Manage tag subscriptions via MXAccess advise callbacks and store subscription state for reconnection.
- Handle COM threading constraints (STA thread context via `Task.Run`).

## 1. Connection Lifecycle

### 1.1 Connect

`ConnectAsync()` wraps `ConnectInternal()` in `Task.Run` for STA thread context:

1. Validates not disposed.
2. Returns early if already connected.
3. Sets state to `Connecting`.
4. `InitializeMxAccessConnection()` — creates new `LMXProxyServer` COM object, wires event handlers (OnDataChange, OnWriteComplete, OperationComplete).
5. `RegisterWithMxAccess()` — calls `_lmxProxy.Register("ZB.MOM.WW.LmxProxy.Host")`, stores the returned connection handle.
6. Sets state to `Connected`.
7. On error, calls `Cleanup()` and re-throws.

After successful connection, calls `RecreateStoredSubscriptionsAsync()` to restore any previously active subscriptions.

### 1.2 Disconnect

`DisconnectAsync()` wraps `DisconnectInternal()` in `Task.Run`:

1. Checks `IsConnected`.
2. Sets state to `Disconnecting`.
3. `RemoveAllSubscriptions()` — unsubscribes all tags from MXAccess but retains subscription state in `_storedSubscriptions` for reconnection.
4. `UnregisterFromMxAccess()` — calls `_lmxProxy.Unregister(_connectionHandle)`.
5. `Cleanup()` — removes event handlers, calls `Marshal.ReleaseComObject(_lmxProxy)` to force-release all COM references, nulls the proxy and resets the connection handle.
6. Sets state to `Disconnected`.

### 1.3 Connection State

- `IsConnected` property: `_lmxProxy != null && _connectionState == Connected && _connectionHandle > 0`.
- `ConnectionState` enum: Disconnected, Connecting, Connected, Disconnecting, Error, Reconnecting.
- `ConnectionStateChanged` event fires on all state transitions with previous state, current state, and optional message.

### 1.4 Auto-Reconnect

When `AutoReconnect` is enabled (default), the `MonitorConnectionAsync` loop runs continuously:
- Checks `IsConnected` every `MonitorIntervalSeconds` (default 5 seconds).
- On disconnect, attempts reconnect via semaphore-protected `ConnectAsync()`.
- On failure, logs warning and retries at the next interval.
- Reconnection restores stored subscriptions automatically.

## 2. Thread Safety & COM Constraints

- State mutations protected by `lock (_lock)`.
- COM operations wrapped in `Task.Run` for STA thread context (MXAccess is 32-bit COM).
- Concurrency control: `_readSemaphore` and `_writeSemaphore` limit concurrent MXAccess operations to `MaxConcurrentOperations` (default 10, configurable).
- Default max concurrency constant: `DefaultMaxConcurrency = 10`.

## 3. Read Operations

- `ReadAsync(address, ct)` — Applies Polly retry policy, calls `ReadSingleValueAsync()`, returns `Vtq`.
- `ReadBatchAsync(addresses, ct)` — Creates parallel tasks per address via `ReadAddressWithSemaphoreAsync()`. Each task acquires `_readSemaphore` before reading. Returns `IReadOnlyDictionary<address, Vtq>`.

## 4. Write Operations

- `WriteAsync(address, value, ct)` — Applies Polly retry policy, calls `WriteInternalAsync(address, value, ct)`.
- `WriteBatchAsync(values, ct)` — Parallel tasks via `WriteAddressWithSemaphoreAsync()`. Each task acquires `_writeSemaphore` before writing.
- `WriteBatchAndWaitAsync(values, flagAddress, flagValue, responseAddress, responseValue, ct)` — Writes batch, writes flag, polls response tag until match.

## 5. Subscription Management

- Subscriptions stored in `_storedSubscriptions` for reconnection persistence.
- `SubscribeInternalAsync(addresses, callback, storeSubscription)` — registers tags with MXAccess and stores subscription state.
- `RecreateStoredSubscriptionsAsync()` — called after reconnect to re-subscribe all previously active tags without re-storing.
- `RemoveAllSubscriptions()` — unsubscribes from MXAccess but retains `_storedSubscriptions`.

## 6. Event Handlers

- **OnDataChange** — Fired by MXAccess when a subscribed tag value changes. Routes the update to the SubscriptionManager.
- **OnWriteComplete** — Fired when an async write operation completes.
- **OperationComplete** — General operation completion callback.

## Dependencies

- **ArchestrA.MXAccess** COM interop assembly (`lib/ArchestrA.MXAccess.dll`).
- **Polly** — retry policies for read/write operations.
- **Configuration** — `ConnectionConfiguration` for timeouts, concurrency limits, and auto-reconnect settings.

## Interactions

- **GrpcServer** (ScadaGrpcService) delegates all SCADA operations to MxAccessClient via the `IScadaClient` interface.
- **SubscriptionManager** receives value change callbacks originating from MxAccessClient's COM event handlers.
- **HealthAndMetrics** queries `IsConnected` and `ConnectionState` for health checks.
- **ServiceHost** manages the MxAccessClient lifecycle (create at startup, dispose at shutdown).