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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common/Events/Database/DbStatusEvent.cs	2026-04-16T03:24:36.502234+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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).