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

---
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.