--- source_files: - 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 generated_at: "2026-04-16T02:50:59.182890+00:00" model: "Qwen/Qwen3-Coder-Next-FP8" schema_version: 1 sha256: "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`—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` | `public interface IHeaderInfoProvider { 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`**: 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`. #### 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.*