DP44/enriched-qwen3-coder-next/Common/DTS.CommonCore/RibbonControl/ViewModel.md

---
source_files:
  - Common/DTS.CommonCore/RibbonControl/ViewModel/RibbonViewModel.cs
generated_at: "2026-04-16T02:47:35.849821+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "62f46108ae312a85"
---

# ViewModel

## Documentation: `RibbonViewModel<TModel>`

---

### **1. Purpose**

`RibbonViewModel<TModel>` is a base view model class for ribbon-based UI views in the DTS application. It provides foundational infrastructure for command handling (e.g., closing), status reporting via Prism’s event aggregation, model binding, and lifecycle management (initialization, activation, cleanup). It is designed to be subclassed by concrete ribbon view models (e.g., for specific ribbon tabs or panels), enforcing consistent behavior across ribbon-related UI components. The generic type parameter `TModel` allows binding to domain-specific data models while abstracting common ribbon concerns like busy state, dirty state, and UI element visibility toggles.

---

### **2. Public Interface**

#### **Properties**
- `public TModel Model { get; set; }`  
  Holds the domain model instance bound to this view model. Settable; cleared during `Cleanup()`.

- `public IRibbonView View { get; }`  
  Reference to the associated view (UI layer), injected via constructor.

- `public InteractionRequest<Confirmation> ConfirmationRequest { get; }`  
  Prism interaction request used to trigger confirmation dialogs (e.g., “Are you sure?”). Publicly exposed for XAML binding.

- `public DelegateCommand<object> CloseCommand { get; }`  
  Delegate command bound to UI close actions (e.g., close button). Executes `CloseMethod()`.

- `public bool IsMenuIncluded { get; set; }`  
  Controls visibility of the menu area in the ribbon UI. Defaults to `true`. Raises `PropertyChanged` on change.

- `public bool IsNavigationIncluded { get; set; }`  
  Controls visibility of the navigation area in the ribbon UI. Defaults to `false`. Raises `PropertyChanged` on change.

- `public int Percentage { get; set; }`  
  Represents progress percentage (e.g., for busy state). No validation or side effects observed.

- `public string IsBusyMessage { get; set; }`  
  Message displayed during busy state (e.g., “Saving…”). No automatic binding or update logic observed.

- `public bool IsBusy { get; set; }`  
  Indicates whether the view model is busy. No automatic status event publishing observed on change.

- `public bool IsDirty { get; set; }`  
  Indicates whether the model has unsaved changes. No automatic dirty-state handling logic observed.

#### **Methods**
- `public virtual void Activated()`  
  Called after the view model is activated (e.g., via Prism region navigation). Default implementation is a no-op; intended for override.

- `public virtual void Initialize()`  
  Publishes a `ShowStatus` event with `StatusState.Busy` and message `"Loading"` (from `Strings.Strings.Loading`). Intended for synchronous initialization.

- `public virtual void Initialize(object parameter)`  
  Same as `Initialize()`, but accepts a navigation/initialization parameter. Does not use the parameter in current implementation.

- `public void Initialize(object parameter, object model)`  
  **No implementation provided** — body is empty. Behavior undefined.

- `public virtual async Task InitializeAsync()`  
  Async version of `Initialize()`. Uses `Dispatcher.CurrentDispatcher.InvokeAsync()` to marshal the `ShowStatus` event publish to the UI thread.

- `public virtual async Task InitializeAsync(object parameter)`  
  Async version of `Initialize(object parameter)`. Same marshaling behavior; parameter unused.

- `public virtual void Cleanup()`  
  Sets `Model` to `default(TModel)` (i.e., `null` for reference types). Intended for releasing resources before disposal.

- `public Task CleanupAsync()`  
  **Throws `NotImplementedException`** — not implemented.

- `protected virtual void CloseMethod(object parameter)`  
  Invoked by `CloseCommand`. Calls `CleanupAtClose()`, which in turn calls `Cleanup()`.

- `protected virtual void CreateCommands()`  
  Initializes `ConfirmationRequest` and `CloseCommand`. Overridable for subclass command registration.

#### **Protected Properties**
- `protected IEventAggregator Aggregator { get; }`  
  Prism event aggregator for publishing/subscribing to events (e.g., `ShowStatus`).

- `protected IUnityContainer Container { get; }`  
  Unity DI container, available for resolution in subclasses.

- `protected IRegionManager RegionManager { get; }`  
  Prism region manager for navigation and region management.

---

### **3. Invariants**

- `Model` is settable but **must be cleared** (set to `null`) before the view model is fully disposed — this is enforced via `Cleanup()` called during close.
- `IsMenuIncluded` and `IsNavigationIncluded` default to `true` and `false`, respectively, but no runtime validation prevents invalid states.
- `IsBusy`, `IsDirty`, `Percentage`, and `IsBusyMessage` are **not** automatically synchronized with status events — they are independent properties with no side effects.
- `Initialize()` and `InitializeAsync()` **always** publish a `Busy` status with the hardcoded `"Loading"` message — no customization or override hook is provided in the base class.
- `Initialize(object parameter, object model)` is **unimplemented** — calling it has no effect.

---

### **4. Dependencies**

#### **Imports/Usings**
- `System`, `System.ComponentModel`, `System.Threading.Tasks`, `System.Windows.Threading`
- `DTS.Common.Base` (base class `BasePropertyChanged`)
- `DTS.Common.Events` (contains `ShowStatus` event and `StatusInfo`)
- `Microsoft.Practices.Prism.*` (Prism libraries: `DelegateCommand`, `InteractionRequest`, `Events`, `Regions`, `Unity`)
- `Microsoft.Practices.Unity` (`IUnityContainer`)

#### **External Contracts**
- `IRibbonView` — expected interface for the associated view (not defined here).
- `ShowStatus` event — published via `IEventAggregator` during initialization.
- `StatusInfo` — type used to convey status state (`Busy`, message string).
- `Strings.Strings.Loading` — localized string resource.

#### **Depended-on By**
- Subclasses of `RibbonViewModel<TModel>` (e.g., specific ribbon tab view models).
- UI layers (XAML) binding to `CloseCommand`, `ConfirmationRequest`, `IsMenuIncluded`, etc.

---

### **5. Gotchas**

- **`CleanupAsync()` is unimplemented** — throws `NotImplementedException`. Subclasses must override or avoid calling it.
- **`Initialize(object parameter, object model)` is a stub** — no logic or side effects. Passing a model here does nothing.
- **No automatic `IsBusy` ↔ status event sync** — setting `IsBusy = true` does *not* publish a `ShowStatus` event. Developers must manually publish `ShowStatus` if using `IsBusy`.
- **`Percentage`, `IsBusyMessage`, `IsDirty` are passive properties** — they have no built-in integration with status reporting or dirty-state tracking (e.g., no auto-save or validation).
- **`Initialize()` methods publish only `"Loading"`** — no way to customize the status message in the base class.
- **`Dispatcher.CurrentDispatcher` used in async methods** — assumes the view model is created on the UI thread. May fail if instantiated off-thread.
- **No explicit disposal pattern** — relies on `Cleanup()` being called (e.g., via `CloseCommand`), but no `IDisposable` implementation.
- **No validation on `Model` assignment** — setting `Model = null` mid-lifecycle is allowed and may leave view in inconsistent state if not handled by subclasses.

None identified beyond the above.