56 lines
3.6 KiB
Markdown
56 lines
3.6 KiB
Markdown
|
---
|
|||
|
|
source_files:
|
|||
|
|
- Common/DTS.Common/Events/Database/DbStatusEvent.cs
|
|||
|
|
generated_at: "2026-04-16T03:24:36.502234+00:00"
|
|||
|
|
model: "Qwen/Qwen3-Coder-Next-FP8"
|
|||
|
|
schema_version: 1
|
|||
|
|
sha256: "907205cba2ff43f9"
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# Database
|
|||
|
|
|
|||
|
|
## 1. Purpose
|
|||
|
|
This module defines a Prism-based event (`DbStatusEvent`) used to communicate database operation status changes throughout the application—specifically for signaling failures or completion of database-related operations such as remote connection, local backup, file copy, and restore. It enables decoupled notification of database state transitions, allowing UI components or background services to react appropriately (e.g., display error messages, update status indicators) when database operations succeed or fail.
|
|||
|
|
|
|||
|
|
## 2. Public Interface
|
|||
|
|
- **`DbStatusEvent`**
|
|||
|
|
- *Type*: `class` inheriting from `PubSubEvent<DbStatusArg>`
|
|||
|
|
- *Behavior*: A Prism event used to publish and subscribe to database status updates. Payload is a `DbStatusArg` instance.
|
|||
|
|
|
|||
|
|
- **`DbStatusArg`**
|
|||
|
|
- *Type*: `class`
|
|||
|
|
- *Properties*:
|
|||
|
|
- `EventTypes Status { get; }` – The type of database status event (see `EventTypes` enum below).
|
|||
|
|
- `Exception Exception { get; }` – The exception associated with the event (if any); may be `null` for non-error statuses (e.g., `Complete`).
|
|||
|
|
- *Constructor*:
|
|||
|
|
- `DbStatusArg(EventTypes error, Exception exception)` – Initializes a new instance with the given status and exception.
|
|||
|
|
- **Nested `EventTypes` enum**:
|
|||
|
|
- `FailedToConnectToRemote`
|
|||
|
|
- `FailedToBackupLocal`
|
|||
|
|
- `FailedToCopy`
|
|||
|
|
- `FailedToRestoreLocal`
|
|||
|
|
- `FailedToBackupLocalFileNotFound`
|
|||
|
|
- `Complete`
|
|||
|
|
- `LegacyStatus`
|
|||
|
|
|
|||
|
|
## 3. Invariants
|
|||
|
|
- `Status` is immutable after construction (only set via constructor).
|
|||
|
|
- `Exception` is immutable after construction (only set via constructor).
|
|||
|
|
- `Exception` may be `null` (e.g., for `Complete` or `LegacyStatus` events), but the constructor does not enforce non-nullability—consumers must handle null cases.
|
|||
|
|
- `EventTypes` values represent *discrete, exhaustive* status categories; no validation is performed on the enum value passed to the constructor (e.g., invalid or future enum values are accepted silently).
|
|||
|
|
|
|||
|
|
## 4. Dependencies
|
|||
|
|
- **Depends on**:
|
|||
|
|
- `Prism.Events` (specifically `PubSubEvent<T>`)
|
|||
|
|
- `System` (for `Exception`)
|
|||
|
|
- **Depends on nothing else in the provided source**.
|
|||
|
|
- **Used by**:
|
|||
|
|
- Any part of the application that needs to publish or subscribe to database status updates (e.g., database service, UI status bar, logging module).
|
|||
|
|
- Inferred from naming (`DTS.Common.Events.Database` namespace), this is part of a shared/common library (`DTS.Common`), so it is likely consumed by multiple downstream modules (e.g., UI, data access layer).
|
|||
|
|
|
|||
|
|
## 5. Gotchas
|
|||
|
|
- The `Exception` property may be `null` for certain statuses (e.g., `Complete`, `LegacyStatus`), but the constructor signature does not enforce non-nullability—subscribers must defensively check for null before accessing `Exception.Message` or stack trace.
|
|||
|
|
- `LegacyStatus` is included but not documented; its semantics are unclear from source alone (e.g., whether it indicates a deprecated status, a fallback, or historical artifact).
|
|||
|
|
- No validation is performed on the `EventTypes` value passed to the constructor—invalid or mistyped enum values (e.g., due to refactoring) will be silently accepted.
|
|||
|
|
- The `<remarks>` section in `DbStatusEvent` is empty, suggesting incomplete documentation.
|
|||
|
|
- No guidance is provided on expected usage patterns (e.g., whether `FailedToBackupLocalFileNotFound` should *always* be accompanied by a `FileNotFoundException` in `Exception`).
|