init

enriched-qwen3-coder-next/Common/DTS.CommonCore/Events/Database.md

@@ -0,0 +1,60 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Events/Database/DbStatusEvent.cs
+generated_at: "2026-04-16T02:47:59.031594+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "e7feae6606912806"
+---
+
+# Database
+
+## 1. Purpose  
+This module defines event infrastructure for communicating database operation status changes within the application, specifically to notify subscribers when database-related operations (such as connection, backup, copy, or restore) succeed or fail. It leverages the Prism event aggregation pattern (`CompositePresentationEvent`) to decouple event producers (e.g., database service logic) from consumers (e.g., UI components or logging modules), enabling asynchronous, loosely coupled status reporting.
+
+## 2. Public Interface  
+- **`DbStatusEvent`**  
+  *Type:* `class` inheriting from `CompositePresentationEvent<DbStatusArg>`  
+  *Behavior:* A Prism event class used to publish and subscribe to database status updates. Subscribers receive a `DbStatusArg` payload describing the outcome of a database operation.
+
+- **`DbStatusArg`**  
+  *Type:* `class`  
+  *Properties:*  
+  - `EventTypes Status { get; }` — The type of database event that occurred (e.g., `Complete`, `FailedToConnectToRemote`).  
+  - `Exception Exception { get; }` — The exception associated with the event (may be `null` for non-error events like `Complete`).  
+  *Constructor:*  
+  - `DbStatusArg(EventTypes error, Exception exception)` — Initializes a new instance with the specified status and exception. Both parameters are stored immutably.
+
+- **`DbStatusArg.EventTypes`**  
+  *Type:* `enum`  
+  *Values:*  
+  - `FailedToConnectToRemote`  
+  - `FailedToBackupLocal`  
+  - `FailedToCopy`  
+  - `FailedToRestoreLocal`  
+  - `FailedToBackupLocalFileNotFound`  
+  - `Complete`  
+  - `LegacyStatus`  
+
+## 3. Invariants  
+- `Status` and `Exception` are **immutable** after construction (no setters beyond initialization).  
+- `Exception` may be `null`, but only for non-error statuses (e.g., `Complete`). For error statuses, an exception *should* be provided, though the class does not enforce this at runtime.  
+- The `EventTypes` enum values are exhaustive for known database operation outcomes; no validation ensures that only these values are used.  
+- The event is published via Prism’s event aggregation system, implying thread-safety and subscription lifecycle management (e.g., unsubscription required to avoid memory leaks), though the source file itself does not enforce subscription rules.
+
+## 4. Dependencies  
+- **Depends on:**  
+  - `System` (for `Exception`)  
+  - `Microsoft.Practices.Prism.Events` (for `CompositePresentationEvent<T>`)  
+  - `DTS.Common.Events.Database` namespace (internal module scope)  
+
+- **Depended on by (inferred):**  
+  - Any module or component that needs to react to database status changes (e.g., UI layers subscribing to `DbStatusEvent` to update status indicators, or logging services publishing to an external system).  
+  - *Note:* The source file does not specify concrete consumers; dependencies are implied by the event’s purpose and Prism usage.
+
+## 5. Gotchas  
+- `LegacyStatus` is included in `EventTypes` but its meaning is undocumented; its purpose is unclear from the source alone.  
+- The `Exception` property is nullable, but the constructor does not validate that non-`Complete` statuses include a non-null exception. Consumers must defensively handle `null` exceptions for error statuses.  
+- The class uses Prism’s `CompositePresentationEvent<T>`, which implies **thread marshaling may be required** for UI updates (e.g., via `Subscribe` with `ThreadOption.UIThread`). This is not enforced by the event class itself.  
+- No versioning or deprecation mechanism is evident for `EventTypes`; adding/removing values may break consumers.  
+- None identified from source alone.