DP44/docs/ai/Common/DTS.Common/RegionManager.md

---
source_files:
  - Common/DTS.Common/RegionManager/ViewDefinition.cs
  - Common/DTS.Common/RegionManager/IDataProRegionManager.cs
  - Common/DTS.Common/RegionManager/IDTSRegionManager.cs
  - Common/DTS.Common/RegionManager/IDTSViewRegionManager.cs
  - Common/DTS.Common/RegionManager/RegionManagerExtensions.cs
  - Common/DTS.Common/RegionManager/DataProRegionManager.cs
  - Common/DTS.Common/RegionManager/DTSRegionManager.cs
  - Common/DTS.Common/RegionManager/DTSViewRegionManager.cs
generated_at: "2026-04-17T15:34:05.296579+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "06b1df2fa33e653c"
---

# RegionManager Module Documentation

## 1. Purpose

This module provides a region management abstraction layer built on top of Prism's `IRegionManager`, facilitating view lifecycle management (add, remove, refresh) with support for both synchronous and asynchronous operations. It uses `ViewDefinition` objects to encapsulate view registration metadata (region name, view interface type, and ViewModel interface type), and coordinates view creation through Unity dependency injection while maintaining proper view-model binding and shell context updates. The module serves as the primary mechanism for dynamic view composition within the application's UI regions.

---

## 2. Public Interface

### ViewDefinition Class

A data transfer object that encapsulates the metadata required to register and instantiate a view within a region.

| Member | Signature | Description |
|--------|-----------|-------------|
| `RegionName` | `string { get; }` | Gets the region name in which a view is displayed. Set via constructor only. |
| `ViewInterfaceType` | `Type { get; }` | Gets the type of the View's interface. Set via constructor only. |
| `ViewModelInterfaceType` | `Type { get; }` | Gets the type of the ViewModel's interface. Set via constructor only. |
| Constructor | `ViewDefinition(string regionName, Type viewInterfaceType, Type viewModelInterfaceType)` | Creates a new instance with the specified region name and type definitions. |

### IDataProRegionManager / IDTSRegionManager / IDTSViewRegionManager Interfaces

All three interfaces extend `IRegionManager` and expose identical members:

| Member | Signature | Description |
|--------|-----------|-------------|
| `AddView` | `void AddView(ViewDefinition viewDefinition, object parameter)` | Adds view to the specified region with initialization parameter. Defaults to single instance mode. |
| `AddView` | `void AddView(ViewDefinition viewDefinition, object parameter, bool allowMultipleInstances)` | Adds view with explicit control over multiple instance allowance. |
| `AddViewAsync` | `Task AddViewAsync(ViewDefinition viewDefinition, object parameter)` | Asynchronously adds view to the region. |
| `AddViewAsync` | `Task AddViewAsync(ViewDefinition viewDefinition, object parameter, bool allowMultipleInstances)` | Asynchronously adds view with explicit multiple instance control. |
| `RemoveView` | `void RemoveView(IBaseViewModel viewModel)` | Removes a view from all regions by its ViewModel reference. Calls `Cleanup()` on the ViewModel. |
| `RemoveViewByRegionName` | `void RemoveViewByRegionName(string regionName)` | Removes all views from the specified region. |
| `RefreshView` | `void RefreshView(Type interfaceForView, object parameter)` | Reloads data for an existing view by calling `Cleanup()` then `Initialize(parameter)`. |
| `RefreshViewAsync` | `Task RefreshViewAsync(Type interfaceForView, object parameter)` | Asynchronously refreshes an existing view. |

### RegionManagerExtensions Static Class

Extension methods for `IRegionManager`:

| Method | Signature | Description |
|--------|-----------|-------------|
| `ClearRegion` | `void ClearRegion(this IRegionManager regionManager, string regionName)` | Removes all views from the specified region. |
| `GetViews` | `IList<object> GetViews(this IRegionManager regionManager, string regionName, Type interfaceForView)` | Returns all views in a region that implement the specified interface. |
| `GetView` | `object GetView(this IRegionManager regionManager, string regionName, Type interfaceForView)` | Returns a single view matching the interface type (last match if multiple exist). |
| `ActivateViewIfExists` | `bool ActivateViewIfExists(this IRegionManager regionManager, string regionName, Type viewType)` | Activates an existing view if found; returns `true` if activated, `false` otherwise. Also calls `Activated()` on the ViewModel. |
| `DeactivateViews` | `void DeactivateViews(this IRegionManager regionManager, string regionName)` | Deactivates all currently active views in the region. |
| `RemoveViews` | `void RemoveViews(this IRegionManager regionManager, string regionName)` | Removes all currently active views from the region. |
| `ActivateLastView` | `void ActivateLastView(this IRegionManager regionManager, string regionName)` | Activates the last view in the region (checks active views first, then all views). |
| `AddViewToRegion` | `void AddViewToRegion(this IRegionManager regionManager, string regionName, object view)` | Adds a view to the region without activating it. |
| `AddViewToRegionActivate` | `void AddViewToRegionActivate(this IRegionManager regionManager, string regionName, object view)` | Adds a view to the region and immediately activates it. |
| `RemoveView` | `void RemoveView(this IRegionManager regionManager, object view)` | Removes a view from all regions where it exists. |
| `RemoveView` | `void RemoveView(this IRegionManager regionManager, string regionName, object view)` | Deactivates and removes a view from a specific region. |

---

## 3. Invariants

- **View Contract**: All views must implement `IBaseView` interface.
- **ViewModel Contract**: All ViewModels must implement `IBaseViewModel` interface.
- **Single Instance Default**: When `allowMultipleInstances` is not specified, it defaults to `false`, meaning duplicate views (by interface type) will not be created.
- **View-ViewModel Binding**: The `DataContext` of every resolved view is set to its resolved ViewModel immediately after resolution.
- **Shell Context Update**: Views added to `RegionNames.MainRegion` or `RegionNames.NavigationRegion` update the shell's context properties (`ContextMainRegion`, `ContextNavigationRegion`).
- **Cleanup on Removal**: `RemoveView` always calls `viewModel.Cleanup()` before deactivating and removing the view.
- **Refresh Pattern**: `RefreshView`/`RefreshViewAsync` always call `Cleanup()` before `Initialize()`/`InitializeAsync()`.
- **Error Handling**: Async methods catch exceptions and publish them via `RaiseNotification` event through `IEventAggregator`.

---

## 4. Dependencies

### External Dependencies (Imports)

| Namespace | Usage |
|-----------|-------|
| `Prism.Regions` / `Microsoft.Practices.Prism.Regions` | `IRegionManager`, `IRegionCollection`, `NavigationResult`, `NavigationParameters` |
| `Prism.Events` / `Microsoft.Practices.Prism.Events` | `IEventAggregator` for event publishing |
| `Unity` / `Microsoft.Practices.Unity` | `IUnityContainer` for dependency resolution |
| `System.Threading.Tasks` | Async/await support |

### Internal Dependencies

| Namespace | Types Used |
|-----------|------------|
| `DTS.Common.Base` | `IBaseView`, `IBaseViewModel` |
| `DTS.Common.Events` | `RaiseNotification` event, `NotificationContentEventArgs` |
| `DTS.Common.Interface` | `IShellViewModel` |
| `DTS.Common.Classes` | `Utility.GetAllErrorMessages()` |

### Consumers

**Unclear from source alone** - The module exposes public interfaces and implementations that would be consumed by other modules requiring view navigation/management, but specific consumers are not visible in the provided files.

---

## 5. Gotchas

1. **Three Nearly Identical Interfaces**: `IDataProRegionManager`, `IDTSRegionManager`, and `IDTSViewRegionManager` expose identical method signatures. The reason for this duplication is unclear from source alone—this may represent a refactoring in progress or different registration scopes.

2. **Prism Version Mismatch**: `DataProRegionManager` imports from `Microsoft.Practices.Prism.Regions` (older Prism), while `DTSRegionManager` and `DTSViewRegionManager` import from `Prism.Regions` (newer Prism). This suggests a migration between Prism versions.

3. **NotImplementedException on Navigation Methods**: `DTSRegionManager` and `DTSViewRegionManager` throw `NotImplementedException` for all `RequestNavigate`, `AddToRegion`, and `RegisterViewWithRegion` methods inherited from `IRegionManager`. These implementations cannot be used for Prism navigation.

4. **Synchronous AddView Ignores Existing Views**: The synchronous `AddView(ViewDefinition, object, bool)` overload does **not** check for existing views before adding, while the async version does. This means synchronous calls may create duplicate views even when `allowMultipleInstances` is `false`.

5. **GetView Returns Last Match**: The `GetView` extension method iterates all views and returns the last matching instance. If multiple views implement the same interface, only the last one is returned.

6. **Regions Property Never Assigned**: The `Regions` property in all three manager implementations has a private setter but is never assigned in constructors. The property returns whatever value is set (likely `null` unless externally configured).

7. **TODO Comments Indicate Known Issues**: 
   - `RefreshViewAsync` contains: `//TODO: fix so that it finds view in right view.`
   - `GetShellViewModelByRegionName` contains: `//TODO: Add more stuff` with commented-out region handling.

8. **Commented-Out Constructor**: `ViewDefinition` has a commented-out constructor that accepted concrete `viewType` and `viewModelType` parameters, suggesting the design was simplified to use interface types only.