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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common/Base/Interface/IBaseClass.cs Common/DTS.Common/Base/Interface/IViewModel.cs Common/DTS.Common/Base/Interface/IBaseView.cs Common/DTS.Common/Base/Interface/IBaseWindow.cs Common/DTS.Common/Base/Interface/IBaseModel.cs Common/DTS.Common/Base/Interface/IBasePropertyChanged.cs Common/DTS.Common/Base/Interface/IHeaderInfoProvider.cs Common/DTS.Common/Base/Interface/IBaseWindowModel.cs Common/DTS.Common/Base/Interface/IBaseViewModel.cs	2026-04-16T03:27:09.388583+00:00	Qwen/Qwen3-Coder-Next-FP8	1	10328346e97dc4f0

DTS.Common.Base Interfaces Documentation

1. Purpose

This module defines a foundational set of interfaces for implementing the MVVM (Model-View-ViewModel) pattern within the DTS application architecture. It establishes contracts for core components—IBaseModel, IBaseViewModel, IBaseWindowModel, IBaseView, IBaseWindow, and IBaseClass—that enforce standardized lifecycle management (initialization, activation, cleanup), state tracking (e.g., IsDirty, IsBusy, IsSaved), and data binding support via INotifyPropertyChanged. These interfaces decouple UI and business logic layers, enabling consistent behavior across views, viewmodels, and models while supporting asynchronous initialization and cleanup workflows.

2. Public Interface

Interfaces

• IBaseClass

  • Definition: public interface IBaseClass : IBasePropertyChanged { }
  • Behavior: Serves as a base interface for classes requiring property change notification. Currently acts as a marker interface extending IBasePropertyChanged.

• IViewModel

  • Definition: public interface IViewModel { object Model { get; set; } }
  • Behavior: Provides a contract for viewmodels to expose and bind to a backing Model object.

• IBaseView

  • Definition: public interface IBaseView { object DataContext { get; set; } }
  • Behavior: Defines a view contract with a DataContext property for data binding (typically to a ViewModel).

• IBaseWindow

  • Definition: public interface IBaseWindow { object DataContext { get; set; } }
  • Behavior: Similar to IBaseView, but intended for window-level UI components; exposes DataContext for binding.

• IBaseModel

  • Definition: public interface IBaseModel : IBasePropertyChanged { bool IsSaved { get; } }
  • Behavior: Extends IBasePropertyChanged and adds a read-only IsSaved property indicating whether the model has been persisted.

• IBasePropertyChanged

  • Definition: public interface IBasePropertyChanged : INotifyPropertyChanged { void OnPropertyChanged(string propertyName); }
  • Behavior: Extends INotifyPropertyChanged and declares a required OnPropertyChanged method for raising change notifications.

• IHeaderInfoProvider<T>

  • Definition: public interface IHeaderInfoProvider<T> { T HeaderInfo { get; } }
  • Behavior: Provides a strongly-typed HeaderInfo property for binding header metadata (e.g., title, subtitle) from XAML.

• IBaseWindowModel

  • Definition:

    public interface IBaseWindowModel : INotifyPropertyChanged
    {
        bool IsMenuIncluded { get; set; }
        bool IsNavigationIncluded { get; set; }
        bool IsBusy { get; set; }
        void Activated();
        bool IsDirty { get; }
        void Cleanup();
        Task CleanupAsync();
        void Initialize();
        void Initialize(object parameter);
        Task InitializeAsync();
        Task InitializeAsync(object parameter);
    }
    

  • Behavior: Defines lifecycle and state management for window-level models. Includes properties for UI control visibility (IsMenuIncluded, IsNavigationIncluded), busy state (IsBusy), dirty state (IsDirty), and methods for initialization/activation/cleanup (synchronous and asynchronous variants).

• IBaseViewModel

  • Definition:

    public interface IBaseViewModel : IBasePropertyChanged
    {
        bool IsMenuIncluded { get; set; }
        bool IsNavigationIncluded { get; set; }
        bool IsBusy { get; set; }
        void Activated();
        bool IsDirty { get; }
        void Cleanup();
        Task CleanupAsync();
        void Initialize();
        void Initialize(object parameter);
        void Initialize(object parameter, object model);
        Task InitializeAsync();
        Task InitializeAsync(object parameter);
    }
    

  • Behavior: Defines lifecycle and state management for viewmodels. Extends IBasePropertyChanged and includes all lifecycle methods of IBaseWindowModel, plus an overloaded Initialize method accepting both parameter and model arguments.

3. Invariants

• IBasePropertyChanged.OnPropertyChanged must be called whenever a property value changes, passing the exact property name as a string.
• IsDirty is read-only in both IBaseViewModel and IBaseWindowModel; implementations must manage its state internally (e.g., via private setters or logic).
• IsSaved is read-only in IBaseModel; implementations must ensure it reflects the persistence state of the model.
• IsBusy, IsMenuIncluded, and IsNavigationIncluded are read-write in IBaseViewModel and IBaseWindowModel; they must be observable via INotifyPropertyChanged.
• Lifecycle methods (Initialize, Cleanup, Activated) must be idempotent or explicitly documented for non-idempotency; the interface does not enforce ordering, but implementations should avoid re-initializing after cleanup.
• IBaseWindowModel does not extend IBasePropertyChanged (it directly implements INotifyPropertyChanged), while IBaseViewModel extends IBasePropertyChanged. This is an intentional distinction in the design.

4. Dependencies

• Depends on:
  • System.ComponentModel (for INotifyPropertyChanged in IBasePropertyChanged, IBaseWindowModel, and IBaseViewModel).
  • System.Threading.Tasks (for Task in IBaseWindowModel and IBaseViewModel).
• Used by:
  • Viewmodel and model implementations throughout the codebase (e.g., concrete classes implementing IBaseViewModel, IBaseModel, IBaseWindowModel).
  • UI framework components (e.g., views/windows implementing IBaseView/IBaseWindow) to bind to viewmodels/models.
  • XAML binding systems via IHeaderInfoProvider<T> for header metadata.
• No direct dependencies on other DTS modules are evident from the source files alone.

5. Gotchas

• IBasePropertyChanged declares OnPropertyChanged(string propertyName) but does not enforce null-safety or validation; callers must ensure propertyName is non-null and accurate (e.g., using nameof()).
• IBaseWindowModel and IBaseViewModel share overlapping members but are not related via inheritance (e.g., IBaseWindowModel does not extend IBaseViewModel), which may lead to duplication or confusion.
• Initialize(object parameter, object model) in IBaseViewModel is absent in IBaseWindowModel—this asymmetry may cause inconsistencies if window models require model injection.
• IsDirty has no setter; implementations must define how dirty state is tracked (e.g., via property change handlers or explicit SetDirty() methods).
• No default implementations are provided—consumers must implement all interface members, including boilerplate INotifyPropertyChanged handling.
• IBaseClass is currently empty beyond inheritance; its purpose is unclear without further context (possibly legacy or placeholder).
• No guidance on thread affinity for lifecycle methods (e.g., InitializeAsync/CleanupAsync), which may lead to cross-thread UI violations if not handled carefully.
• IHeaderInfoProvider<T> is generic but T is unconstrained; implementations must ensure T is serializable or bindable if used in XAML.

None identified beyond the above.