DP44/enriched-partialglm/Common/DTS.CommonCore/RegionManager.md

---
source_files:
  - Common/DTS.CommonCore/RegionManager/ViewDefinition.cs
  - Common/DTS.CommonCore/RegionManager/IDataProRegionManager.cs
  - Common/DTS.CommonCore/RegionManager/IDTSRegionManager.cs
  - Common/DTS.CommonCore/RegionManager/IDTSViewRegionManager.cs
  - Common/DTS.CommonCore/RegionManager/RegionManagerExtensions.cs
  - Common/DTS.CommonCore/RegionManager/DTSRegionManager.cs
  - Common/DTS.CommonCore/RegionManager/DTSViewRegionManager.cs
  - Common/DTS.CommonCore/RegionManager/DataProRegionManager.cs
generated_at: "2026-04-16T12:08:29.432638+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "716052479006d994"
---

# Documentation: DTS.Common.RegionManager

## 1. Purpose
This module provides an abstraction layer over the Prism `IRegionManager` to manage the lifecycle of views in a WPF application. It facilitates the registration, activation, removal, and refreshing of views within specific UI regions, while enforcing a strict Model-View-ViewModel (MVVM) pattern. The module bridges the Unity dependency injection container with Prism's region navigation, ensuring that views and view models are resolved, bound, and initialized consistently.

## 2. Public Interface

### Classes

#### `ViewDefinition`
A definition class used to describe a view to be added to a region.

*   **`ViewDefinition(string regionName, Type viewInterfaceType, Type viewModelInterfaceType)`**
    *   Constructor that initializes the definition.
    *   `regionName`: The name of the region where the view will be displayed.
    *   `viewInterfaceType`: The interface type of the View (used for resolution and activation checks).
    *   `viewModelInterfaceType`: The interface type of the ViewModel (used for resolution).
*   **`string RegionName { get; private set; }`**
    *   Gets the region name.
*   **`Type ViewInterfaceType { get; private set; }`**
    *   Gets the View's interface type.
*   **`Type ViewModelInterfaceType { get; private set; }`**
    *   Gets the ViewModel's interface type.

#### `RegionManagerExtensions`
A static class providing extension methods for `IRegionManager`.

*   **`void ClearRegion(this IRegionManager regionManager, string regionName)`**
    *   Removes all views from the specified region.
*   **`IList<object> GetViews(this IRegionManager regionManager, string regionName, Type interfaceForView)`**
    *   Retrieves a list of views from a region that match a specific interface type.
*   **`object GetView(this IRegionManager regionManager, string regionName, Type interfaceForView)`**
    *   Retrieves a single view from a region matching a specific interface type.
*   **`bool ActivateViewIfExists(this IRegionManager regionManager, string regionName, Type viewType)`**
    *   Activates a view if it exists in the region. Returns `true` if found and activated; otherwise `false`.
*   **`void DeactivateViews(this IRegionManager regionManager, string regionName)`**
    *   Deactivates all currently active views in the specified region.
*   **`void RemoveViews(this IRegionManager regionManager, string regionName)`**
    *   Removes all active views from the specified region.
*   **`void ActivateLastView(this IRegionManager regionManager, string regionName)`**
    *   Activates the last view in the region (prioritizing active views, falling back to all views).
*   **`void AddViewToRegion(this IRegionManager regionManager, string regionName, object view)`**
    *   Adds a view to the region without activating it.
*   **`void AddViewToRegionActivate(this IRegionManager regionManager, string regionName, object view)`**
    *   Adds a view to the region and immediately activates it.
*   **`void RemoveView(this IRegionManager regionManager, object view)`**
    *   Removes a view from *all* regions where it is registered.
*   **`void RemoveView(this IRegionManager regionManager, string regionName, object view)`**
    *   Deactivates and removes a view from a specific region.

### Interfaces & Implementations

The module defines three distinct interfaces (`IDTSRegionManager`, `IDTSViewRegionManager`, `IDataProRegionManager`) with identical public members. They are implemented by `DTSRegionManager`, `DTSViewRegionManager`, and `DataProRegionManager` respectively.

**Common Public Members (inherited from `IRegionManager`):**

*   **`void AddView(ViewDefinition viewDefinition, object parameter)`**
    *   Adds a view to the region. Calls `Initialize(parameter)` on the ViewModel.
*   **`void AddView(ViewDefinition viewDefinition, object parameter, bool allowMultipleInstances)`**
    *   Adds a view to the region.
*   **`Task AddViewAsync(ViewDefinition viewDefinition, object parameter)`**
    *   Asynchronously adds a view.
*   **`Task AddViewAsync(ViewDefinition viewDefinition, object parameter, bool allowMultipleInstances)`**
    *   Asynchronously adds a view. Checks for existing instances unless `allowMultipleInstances` is true.
*   **`void RemoveView(IBaseViewModel viewModel)`**
    *   Removes the view associated with the given ViewModel from all regions. Calls `Cleanup()` on the ViewModel.
*   **`void RemoveViewByRegionName(string regionName)`**
    *   Clears all views from the specified region.
*   **`void RefreshView(Type interfaceForView, object parameter)`**
    *   Finds a view by interface type, calls `Cleanup()` on its ViewModel, and re-initializes it with the parameter.
*   **`Task RefreshViewAsync(Type interfaceForView, object parameter)`**
    *   Asynchronously refreshes the view.

## 3. Invariants

1.  **Type Resolution:** All `ViewDefinition` instances must provide interface types (`ViewInterfaceType`, `ViewModelInterfaceType`) that are registered in the `IUnityContainer`. The managers cast resolved objects to `IBaseView` and `IBaseViewModel`.
2.  **DataContext Binding:** When a view is added, the `DataContext` of the View is explicitly set to the resolved ViewModel instance.
3.  **Region Existence:** The `regionName` provided in `ViewDefinition` must correspond to a region already registered in the Prism `RegionManager`.
4.  **Shell Context:** When a view is added to `RegionNames.MainRegion`, the implementation sets `shell.ContextMainRegion` (or `ContextNavigationRegion` in `DataProRegionManager`) to the resolved view instance.
5.  **View Lifecycle:** `RemoveView` and `RefreshView` rely on the View implementing `IBaseView` and the ViewModel implementing `IBaseViewModel` to execute lifecycle methods (`Cleanup`, `Initialize`, `Activated`).

## 4. Dependencies

**Internal Dependencies (DTS.Common):**
*   `DTS.Common.Base`: Uses `IBaseView`, `IBaseViewModel`.
*   `DTS.Common.Events`: Uses `RaiseNotification` event and `NotificationContentEventArgs` for error handling.
*   `DTS.Common.Interface`: Uses `IShellViewModel`.
*   `DTS.Common.Classes`: Uses `Utility` for error message formatting.

**External Dependencies:**
*   `Microsoft.Practices.Prism.Regions`: Core region management (`IRegionManager`, `IRegion`, `IRegionCollection`).
*   `Microsoft.Practices.Unity`: Dependency injection (`IUnityContainer`).
*   `Microsoft.Practices.Prism.Events`: Event aggregation (`IEventAggregator`).
*   `System.Windows`: Implied dependency for UI elements (Views).

## 5. Gotchas

1.  **Uninitialized `Regions` Property:** The classes `DTSRegionManager`, `DTSViewRegionManager`, and `DataProRegionManager` implement `IRegionManager`. The source explicitly defines a `