dohertj2/mxaccessgw
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: AlarmClient public surface — managed-event premise wrong, WM_APP required

Browse Source 
Reflection probe of the deployed aaAlarmManagedClient.dll
(v1.0.7368.41290) on 2026-05-01 confirmed the public AlarmClient class
exposes zero public events. The PR A.5 design that AlarmClientConsumer
is built on (managed-event surface, no message pump) does not hold
against this assembly.

The actual notification mechanism is WM_APP messaging:
RegisterConsumer(hWnd, ...) takes a window handle because AVEVA's alarm
provider WM_APP-pokes the registered window, then GetStatistics +
GetAlarmExtendedRec pull the change set on each poke.

Practical impact:

- AlarmClientConsumer.AlarmRecordReceived has no production caller.
  RaiseAlarmRecordReceived is invoked only from tests. Subscribe(...)
  returns OK from RegisterConsumer + Subscribe but no notifications
  reach the consumer at runtime because no window is attached.
- Until A.2 lands a hidden message-only window + WindowProc that routes
  WM_APP into MxAccessAlarmEventSink.EnqueueTransition, the gateway's
  MX_EVENT_FAMILY_ON_ALARM_TRANSITION family cannot carry events.
- AcknowledgeByGuid and SnapshotActiveAlarms are pull-style and remain
  correct as written.

Changes:

- docs/AlarmClientDiscovery.md (new) — reflection probe summary, full
  AlarmClient method list, open questions for A.2 implementation.
- AlarmClientConsumer.cs xmldoc — replaced the inaccurate "managed
  event surface" claim with the WM_APP finding; flagged
  AlarmRecordReceived as unreachable in production until the WM_APP
  pump lands.
- MxAccessAlarmEventSink.cs xmldoc — replaced the "verify on dev rig"
  hedge in the wiring plan with the resolved finding; expanded the
  open-questions list (WM_APP message ID, wParam/lParam semantics, STA
  affinity, subscription scope) so the next A.2 PR knows what the
  dev-rig probe needs to answer.

Code-only no-op for the worker; worker builds clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Joseph Doherty
2026-05-01 06:50:57 -04:00
parent a739fadb5f
commit 6e356da092
3 changed files with 194 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/MxGateway.Worker/MxAccess/AlarmClientConsumer.cs
+37 -18
View File
@@ -13,22 +13,39 @@ namespace MxGateway.Worker.MxAccess;
/// </summary>
/// <remarks>
/// <para>
/// The AVEVA alarm-manager surface (<c>IAlarmMgrDataProvider</c>)
/// exposes the events we need as plain .NET events — no Windows
/// message pump required. The worker keeps its STA thread for
/// MxAccess COM but the alarm-client callbacks arrive on the
/// AVEVA managed-client's internal callback thread.
/// <strong>⚠ Architecture finding (2026-05-01 reflection probe —
/// see <c>docs/AlarmClientDiscovery.md</c>):</strong> contrary to the
/// original PR A.5 design, <c>aaAlarmManagedClient.AlarmClient</c>
/// exposes <em>zero</em> public events on the deployed assembly
/// (<c>aaAlarmManagedClient.dll</c> v1.0.7368.41290). There is no
/// managed event surface. <c>RegisterConsumer(hWnd, …)</c> takes a
/// window handle because the actual notification mechanism is
/// WM_APP-pump messaging — AVEVA's alarm provider WM_APP-pokes the
/// registered window, and the consumer pulls the change set via
/// <c>GetStatistics</c> + <c>GetAlarmExtendedRec</c> on each poke.
/// </para>
/// <para>
/// The constructor parameters that <see cref="AlarmClient.RegisterConsumer"/>
/// takes (<c>hWnd</c>, product / application / version names,
/// retain-hidden flag) are pinned to safe defaults; the live
/// <c>hWnd</c> is intentionally <c>IntPtr.Zero</c> because we use
/// the managed-event surface, not the WM_APP pump. <strong>Verify
/// on dev rig</strong> that <c>RegisterConsumer</c> with
/// <c>hWnd=0</c> still wires the managed event handlers; if it
/// requires a real hWnd, the worker creates a hidden message-only
/// window and passes that handle here.
/// As a result, <see cref="AlarmRecordReceived"/> has no production
/// caller — <see cref="RaiseAlarmRecordReceived"/> is invoked only
/// from tests. <see cref="Subscribe"/> currently calls
/// <c>RegisterConsumer(hWnd: 0, …)</c> + <c>Subscribe(…)</c> and
/// returns OK, but no notifications will arrive at runtime because
/// no window is attached. Until A.2's WM_APP pump lands, the
/// gateway's <c>MX_EVENT_FAMILY_ON_ALARM_TRANSITION</c> family
/// cannot carry any events.
/// </para>
/// <para>
/// <see cref="Subscribe"/> as written is still a load-bearing call
/// the WM_APP path needs (it tells the alarm provider which
/// subscription expression to scope notifications to). The wiring
/// that has to change is the notification-receive side: replace the
/// <c>hWnd: 0</c> default with a real hidden message-only window
/// hWnd owned by the worker's STA, and add a <c>WindowProc</c> that
/// routes the AVEVA WM_APP message into a change-pull path that
/// ultimately invokes <see cref="RaiseAlarmRecordReceived"/>.
/// <see cref="AcknowledgeByGuid"/> and <see cref="SnapshotActiveAlarms"/>
/// are pull-style and don't depend on the event surface — they're
/// correct as is.
/// </para>
/// </remarks>
public sealed class AlarmClientConsumer : IMxAccessAlarmConsumer
@@ -63,10 +80,12 @@ public sealed class AlarmClientConsumer : IMxAccessAlarmConsumer
lock (subscribeLock)
{
// hWnd=0: AVEVA's managed event surface routes through the
// GetAlarmChangesCompleted .NET event, not a window-message pump.
// Verify on dev rig that 0 is accepted; if not, supply a hidden
// message-only window's handle here.
// hWnd=0: placeholder — the AVEVA alarm provider notifies via
// WM_APP messages, not via a managed-client event surface (see
// docs/AlarmClientDiscovery.md, 2026-05-01 reflection probe).
// RegisterConsumer accepts hWnd=0 but no notifications will reach
// this consumer until the WM_APP pump lands as part of A.2 and
// a real message-only window's handle is supplied here.
int registerResult = client.RegisterConsumer(
hWnd: 0,
szProductName: DefaultProductName,
src/MxGateway.Worker/MxAccess/MxAccessAlarmEventSink.cs
+36 -15
View File
@@ -11,19 +11,35 @@ namespace MxGateway.Worker.MxAccess;
/// </summary>
/// <remarks>
/// <para>
/// <strong>Architecture (pinned 2026-04-30):</strong> the worker hosts
/// <strong>Architecture (revised 2026-05-01 — see
/// <c>docs/AlarmClientDiscovery.md</c>):</strong> the worker hosts
/// <c>aaAlarmManagedClient.AlarmClient</c> alongside the existing
/// <c>ArchestrA.MxAccess</c> COM consumer. Both are x86 .NET Framework
/// 4.8 — the worker's existing runtime — and both use the same Windows
/// STA + WM_APP message pump. The MxAccess COM Toolkit at
/// <c>ArchestrA.MxAccess</c> COM consumer. Both are x86 .NET
/// Framework 4.8. The MxAccess COM Toolkit at
/// <c>C:\Program Files (x86)\ArchestrA\Framework\Bin\ArchestrA.MXAccess.dll</c>
/// exposes no alarm events; the alarm provider lives in a separate
/// AVEVA service that <c>aaAlarmManagedClient</c> subscribes to.
/// </para>
/// <para>
/// <strong>Notification mechanism: WM_APP pump.</strong> A reflection
/// probe of <c>aaAlarmManagedClient.dll</c> (v1.0.7368.41290) on
/// 2026-05-01 confirmed the public <c>AlarmClient</c> class has zero
/// public events. The original PR A.5 design (managed-event surface,
/// no message pump) is incorrect against this assembly. AVEVA's
/// alarm provider WM_APP-pokes a window registered through
/// <c>RegisterConsumer(hWnd, …)</c>; the consumer pulls the change
/// set via <c>GetStatistics</c> + <c>GetAlarmExtendedRec</c> on each
/// poke. PR A.5's <see cref="AlarmClientConsumer"/> still owns the
/// <see cref="AlarmClient"/> handle and the
/// <see cref="AlarmClient.Subscribe"/> /
/// <see cref="AlarmClient.AlarmAckByGUID"/> pull-style calls; only
/// the receive path is wrong.
/// </para>
/// <para>
/// <strong>Discovered API surface</strong> (see
/// <c>AlarmClientDiscoveryTests.DumpAlarmClientPublicSurface</c> in
/// <c>MxGateway.Worker.Tests</c> — Skip-gated reflection probe):
/// <c>MxGateway.Worker.Tests</c> — Skip-gated reflection probe; full
/// output captured in <c>docs/AlarmClientDiscovery.md</c>):
/// </para>
/// <list type="bullet">
/// <item><description><c>RegisterConsumer(hWnd, productName, applicationName, version, retainHidden)</c> — registers a Windows-message-pump consumer; the AVEVA alarm service WM_APP-pokes the hWnd when alarms change.</description></item>
@@ -33,20 +49,25 @@ namespace MxGateway.Worker.MxAccess;
/// <item><description><c>AlarmAckByGUID(alarmGuid, ackComment, oprName, oprNode, oprDomain, oprFullName)</c> — full-fidelity native Acknowledge: comment + four operator-identity fields are atomic with the ack transition.</description></item>
/// </list>
/// <para>
/// <strong>Wiring plan (subsequent PRs):</strong>
/// <strong>Open questions before A.2 implementation</strong>
/// (see <c>docs/AlarmClientDiscovery.md</c> "Implications for A.2"):
/// </para>
/// <list type="number">
/// <item><description>Worker session-startup wires <c>AlarmClient.RegisterConsumer</c> against the worker's existing STA hWnd; <c>Subscribe</c> with the Galaxy provider name + a permissive priority/filter range.</description></item>
/// <item><description>The STA's WM_APP handler routes alarm-changed messages into <see cref="EnqueueTransition"/>; the message ID is established at runtime via the consumer's reported handler (verify on dev rig).</description></item>
/// <item><description>Gateway-side <c>AcknowledgeAlarm</c> RPC translates to a worker command that calls <c>AlarmClient.AlarmAckByGUID</c> with the OPC UA operator's resolved identity — replaces the worker-pending diagnostic from PR A.3.</description></item>
/// <item><description>WM_APP message ID — not in the public surface, needs AVEVA C++ Toolkit reference or a runtime probe.</description></item>
/// <item><description><c>wParam</c> / <c>lParam</c> semantics — likely none (the pattern is "got poked → pull state via <c>GetStatistics</c>"), but confirm during the probe.</description></item>
/// <item><description>STA / threading affinity for the message-only window — likely the worker's existing STA, but if AVEVA assumes UI-thread inside <c>GetStatistics</c> the alarm path may need its own STA.</description></item>
/// <item><description>Subscription scope — reuse the configured Galaxy name from the data session.</description></item>
/// </list>
/// <para>
/// Until those PRs land, <see cref="Attach"/> is a no-op. The worker
/// continues to function for data subscriptions, and the gateway's
/// <see cref="MxEventFamily.OnAlarmTransition"/> family is reserved on
/// the wire but never emitted. lmxopcua-side <c>AlarmConditionService</c>
/// keeps the sub-attribute synthesis active and continues to surface
/// alarms to OPC UA Part 9 clients in the meantime.
/// Until A.2 lands a hidden message-only window + WindowProc that
/// routes WM_APP into <see cref="EnqueueTransition"/>,
/// <see cref="Attach"/> is a no-op. The worker continues to function
/// for data subscriptions, and the gateway's
/// <see cref="MxEventFamily.OnAlarmTransition"/> family is reserved
/// on the wire but never emitted. lmxopcua-side
/// <c>AlarmConditionService</c> keeps the sub-attribute synthesis
/// active and continues to surface alarms to OPC UA Part 9 clients
/// in the meantime.
/// </para>
/// </remarks>
public sealed class MxAccessAlarmEventSink : IMxAccessEventSink