DP44/enriched-qwen3-coder-next/Common/DTS.CommonCore/Base/Interface.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.CommonCore/Base/Interface/IBaseClass.cs Common/DTS.CommonCore/Base/Interface/IViewModel.cs Common/DTS.CommonCore/Base/Interface/IBaseView.cs Common/DTS.CommonCore/Base/Interface/IBaseWindow.cs Common/DTS.CommonCore/Base/Interface/IBaseModel.cs Common/DTS.CommonCore/Base/Interface/IBasePropertyChanged.cs Common/DTS.CommonCore/Base/Interface/IHeaderInfoProvider.cs Common/DTS.CommonCore/Base/Interface/IBaseWindowModel.cs Common/DTS.CommonCore/Base/Interface/IBaseViewModel.cs	2026-04-16T02:50:59.182890+00:00	Qwen/Qwen3-Coder-Next-FP8	1	cd583516ecde421b

Interface

Documentation: DTS.Common.Base Interface Layer

---

1. Purpose

This module defines a foundational set of interfaces for implementing the Model-View-ViewModel (MVVM) pattern within the DTS codebase. It establishes contract-based abstractions for core UI and data entities—IBaseModel, IBaseViewModel, IBaseWindowModel, IBaseView, IBaseWindow, and supporting interfaces like IBasePropertyChanged and IHeaderInfoProvider<T>—to enforce consistency, lifecycle management, and property change notification across the application. These interfaces decouple UI components (Views/Windows) from their backing logic (ViewModels/Models), enabling testability, reuse, and standardized behavior for state tracking (IsDirty, IsBusy, IsSaved), initialization, and cleanup.

---

2. Public Interface

Interfaces (all in DTS.Common.Base namespace)

Interface	Signature	Description
IBaseClass	public interface IBaseClass : IBasePropertyChanged { }	Marker interface extending IBasePropertyChanged. Used as a base contract for classes requiring property change notification.
IBasePropertyChanged	public interface IBasePropertyChanged : INotifyPropertyChanged { void OnPropertyChanged(string propertyName); }	Extends INotifyPropertyChanged with a required OnPropertyChanged(string) method. Note: No default implementation is provided.
IBaseModel	public interface IBaseModel : IBasePropertyChanged { bool IsSaved { get; } }	Base interface for domain models. Guarantees IsSaved read-only state (e.g., whether the model has unsaved changes).
IBaseViewModel	public interface IBaseViewModel : IBasePropertyChanged { ... }	Base interface for ViewModels. Includes lifecycle methods (Initialize, Activated, Cleanup, CleanupAsync, InitializeAsync) and state properties (IsMenuIncluded, IsNavigationIncluded, IsBusy, IsDirty). Supports multiple Initialize overloads (with/without parameter, and with parameter + model).
IBaseWindowModel	public interface IBaseWindowModel : INotifyPropertyChanged { ... }	Base interface for Window-level ViewModels. Mirrors IBaseViewModel but does not inherit IBasePropertyChanged (directly implements INotifyPropertyChanged). Includes identical lifecycle/state members.
IViewModel	public interface IViewModel { object Model { get; set; } }	Minimal interface for ViewModels to expose their backing Model. Does not enforce lifecycle or state properties.
IBaseView	public interface IBaseView { object DataContext { get; set; } }	Base interface for Views (e.g., UserControls). Declares DataContext for binding to a ViewModel.
IBaseWindow	public interface IBaseWindow { object DataContext { get; set; } }	Base interface for Window classes. Declares DataContext for binding to a Window-level ViewModel.
IHeaderInfoProvider<T>	public interface IHeaderInfoProvider<T> { T HeaderInfo { get; } }	Generic interface for objects that expose a HeaderInfo (e.g., for XAML binding to UI headers). Type parameter T specifies the HeaderInfo type.

Lifecycle Method Overloads Summary
All Initialize/Cleanup methods are defined in both IBaseViewModel and IBaseWindowModel:

• void Initialize();
• void Initialize(object parameter);
• void Initialize(object parameter, object model); (only in IBaseViewModel)
• Task InitializeAsync();
• Task InitializeAsync(object parameter);
• void Activated();
• void Cleanup();
• Task CleanupAsync();

State Properties
Shared across IBaseViewModel and IBaseWindowModel:

• bool IsMenuIncluded { get; set; }
• bool IsNavigationIncluded { get; set; }
• bool IsBusy { get; set; }
• bool IsDirty { get; } (read-only)
• bool IsSaved { get; } (only in IBaseModel)

---

3. Invariants

• Property Change Notification: Any class implementing IBasePropertyChanged (including IBaseClass, IBaseModel, IBaseViewModel) must raise PropertyChanged via OnPropertyChanged(string propertyName). The interface does not enforce thread-safety or throttling—consumers must handle this.
• IsDirty vs IsSaved:
  • IsDirty (in IBaseViewModel/IBaseWindowModel) indicates whether the ViewModel has unsaved changes relative to its initialization state.
  • IsSaved (in IBaseModel) indicates whether the underlying Model has been persisted.
    These are orthogonal: a model can be IsSaved=true but IsDirty=true if the ViewModel has made new changes since the last save.
• Lifecycle Order:
  Initialize/InitializeAsync → Activated → (user interaction) → Cleanup/CleanupAsync.
  InitializeAsync and CleanupAsync are asynchronous; callers must await them to ensure completion before proceeding.
• IHeaderInfoProvider<T>: The HeaderInfo property is read-only (get only). Implementations must ensure HeaderInfo is non-null (or handle null gracefully) for XAML binding.

---

4. Dependencies

Dependencies of this module:

• System.ComponentModel: Required for INotifyPropertyChanged (used in IBasePropertyChanged, IBaseWindowModel, IBaseViewModel).
• System.Threading.Tasks: Required for Task return types in IBaseViewModel and IBaseWindowModel.

Dependencies on this module (inferred from naming conventions and usage patterns):

• UI Layer: Views (e.g., WPF Window, UserControl) likely implement IBaseView/IBaseWindow and bind DataContext to ViewModels implementing IBaseViewModel/IBaseWindowModel.
• ViewModel Layer: Concrete ViewModels inherit from base classes implementing IBaseViewModel or IBaseWindowModel.
• Model Layer: Domain models likely implement IBaseModel.
• Header Binding: UI components (e.g., headers, toolbars) consume types implementing IHeaderInfoProvider<T>.

No internal dependencies within this module (interfaces are self-contained).

---

5. Gotchas

• IBaseWindowModel does not inherit IBasePropertyChanged: It directly implements INotifyPropertyChanged. This is inconsistent with IBaseViewModel (which inherits IBasePropertyChanged). Developers may mistakenly assume both share the same base contract.
• OnPropertyChanged signature lacks default parameter: The interface defines void OnPropertyChanged(string propertyName); without a default value (commented-out alternatives exist in source but are not part of the contract). Implementers must pass a non-null property name (or risk silent failures).
• IsDirty is read-only: Its value must be computed internally (e.g., via SetProperty logic or manual tracking). No setter is exposed, so external state changes (e.g., after save) require updating via internal logic.
• Initialize(object parameter, object model) is IBaseViewModel-only: IBaseWindowModel lacks this overload. Using it in a Window-level ViewModel may cause ambiguity or require custom implementation.
• No default implementations: These are interfaces only. Concrete behavior (e.g., SetProperty, IsDirty tracking) must be provided by base classes or implementations (not documented here).
• Namespace quirk: All interfaces use DTS.Common.Base despite being in DTS.CommonCore paths. This may cause confusion if namespace resolution is expected to match folder structure.

None identified from source alone.