114 lines
7.2 KiB
Markdown
114 lines
7.2 KiB
Markdown
---
|
|
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 ` |