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

source_files, generated_at, model, schema_version, sha256

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