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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-17T15:33:22.595982+00:00	zai-org/GLM-5-FP8	1	b4a7d91f5b154d1d

RegionManager Module Documentation

1. Purpose

This module provides a region management abstraction layer built on top of Microsoft Prism's IRegionManager. It facilitates the addition, removal, and refresh of views within named UI regions in a WPF application using the MVVM pattern. The module defines a ViewDefinition class to encapsulate view registration metadata, provides three nearly identical region manager interfaces (IDataProRegionManager, IDTSRegionManager, IDTSViewRegionManager) with corresponding implementations, and includes extension methods for common region operations. Its role is to decouple view lifecycle management from the underlying Prism infrastructure while integrating with Unity dependency injection and event aggregation.

---

2. Public Interface

ViewDefinition (Class)

Signature:

public ViewDefinition(string regionName, Type viewInterfaceType, Type viewModelInterfaceType)

Properties:

• string RegionName { get; private set; } — The region name where the view is displayed.
• Type ViewInterfaceType { get; private set; } — The interface type of the View to be registered.
• Type ViewModelInterfaceType { get; private set; } — The interface type of the ViewModel to be registered.

Behavior: Immutable data container for view registration. Has a private parameterless constructor (likely for serialization or ORM use).

---

IDataProRegionManager, IDTSRegionManager, IDTSViewRegionManager (Interfaces)

All three interfaces are identical in signature and extend IRegionManager. They define the following members:

AddView (synchronous):

void AddView(ViewDefinition viewDefinition, object parameter)
void AddView(ViewDefinition viewDefinition, object parameter, bool allowMultipleInstances)

Adds a view to a region, initializing the ViewModel with the provided parameter.

AddViewAsync (asynchronous):

Task AddViewAsync(ViewDefinition viewDefinition, object parameter)
Task AddViewAsync(ViewDefinition viewDefinition, object parameter, bool allowMultipleInstances)

Asynchronous version of AddView.

RemoveView:

void RemoveView(IBaseViewModel viewModel)

Removes a view from all regions by matching its ViewModel reference.

RemoveViewByRegionName:

void RemoveViewByRegionName(string regionName)

Clears all views from the specified region.

RefreshView (synchronous):

void RefreshView(Type interfaceForView, object parameter)

Finds a view by its interface type, calls Cleanup() on its ViewModel, then re-initializes with the parameter.

RefreshViewAsync (asynchronous):

Task RefreshViewAsync(Type interfaceForView, object parameter)

Asynchronous version of RefreshView.

---

RegionManagerExtensions (Static Class)

ClearRegion:

public static void ClearRegion(this IRegionManager regionManager, string regionName)

Removes all views from the specified region.

GetViews:

public static IList<object> GetViews(this IRegionManager regionManager, string regionName, Type interfaceForView)

Returns all views in the region that implement the specified interface type.

GetView:

public static object GetView(this IRegionManager regionManager, string regionName, Type interfaceForView)

Returns the first view matching the interface type, or null if not found.

ActivateViewIfExists:

public static 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:

public static void DeactivateViews(this IRegionManager regionManager, string regionName)

Deactivates all currently active views in the region.

RemoveViews:

public static void RemoveViews(this IRegionManager regionManager, string regionName)

Removes all active views from the region.

ActivateLastView:

public static void ActivateLastView(this IRegionManager regionManager, string regionName)

Activates the last view in the region (checks active views first, then all views).

AddViewToRegion:

public static void AddViewToRegion(this IRegionManager regionManager, string regionName, object view)

Adds a view to the region without activating it.

AddViewToRegionActivate:

public static void AddViewToRegionActivate(this IRegionManager regionManager, string regionName, object view)

Adds a view to the region and immediately activates it.

RemoveView (extension overloads):

public static void RemoveView(this IRegionManager regionManager, object view)
public static void RemoveView(this IRegionManager regionManager, string regionName, object view)

Removes a view from all regions, or from a specific region (deactivates before removal).

---

DTSRegionManager, DTSViewRegionManager, DataProRegionManager (Classes)

All three implement their respective interfaces with nearly identical code. Constructor signature:

public DTSRegionManager(IUnityContainer unityContainer, IRegionManager regionManager, IEventAggregator eventAggregator)

Regions Property:

public IRegionCollection Regions { get; private set; }

CreateRegionManager:

public IRegionManager CreateRegionManager()

Returns a new RegionManager instance.

---

3. Invariants

• ViewDefinition immutability: All properties are read-only after construction via the public constructor.
• Interface-based resolution: Views and ViewModels are resolved by their interface types (ViewInterfaceType, ViewModelInterfaceType), not concrete types.
• ViewModel lifecycle: When a view is removed, Cleanup() is called on the ViewModel before deactivation and removal.
• Single-instance default: AddView overloads without allowMultipleInstances default to false (single instance).
• Region existence: Extension methods assume the region name exists in regionManager.Regions; behavior is undefined if the region is not found (likely throws KeyNotFoundException).
• IBaseView/IBaseViewModel contract: All implementations cast views to IBaseView and ViewModels to IBaseViewModel, expecting DataContext, Initialize(), InitializeAsync(), Cleanup(), CleanupAsync(), and Activated() members.

---

4. Dependencies

This module depends on:

• Microsoft.Practices.Prism.Regions — IRegionManager, IRegionCollection, RegionManager
• Microsoft.Practices.Prism.Events — IEventAggregator
• Microsoft.Practices.Unity — IUnityContainer
• DTS.Common.Base — IBaseView, IBaseViewModel
• DTS.Common.Events — RaiseNotification, NotificationContentEventArgs
• DTS.Common.Interface — IShellViewModel
• DTS.Common.Classes — Utility (for GetAllErrorMessages)
• System.Windows — For WPF UI components

What depends on this module:

• Cannot be determined from source alone; consumers would resolve IDataProRegionManager, IDTSRegionManager, or IDTSViewRegionManager via Unity.

---

5. Gotchas

1. Three nearly identical interfaces and implementations: IDataProRegionManager, IDTSRegionManager, and IDTSViewRegionManager have identical method signatures. The reason for this duplication is unclear from source alone. The implementations (DataProRegionManager, DTSRegionManager, DTSViewRegionManager) are also nearly identical, with minor differences in GetShellViewModelByRegionName logic.

2. Unused allowMultipleInstances in synchronous AddView: In the synchronous AddView(ViewDefinition, object, bool) implementations, the allowMultipleInstances parameter is accepted but not used—the view is always added regardless of whether an instance already exists. Only the async versions check this flag and return early if a view already exists.

3. Commented-out code in ViewDefinition: There is a commented-out ViewType property and a commented-out alternate constructor, suggesting the design may have changed or is incomplete.

4. TODO comments in implementations:

   • GetShellViewModelByRegionName has //TODO: Add more stuff in DTSRegionManager and DTSViewRegionManager.
   • RefreshViewAsync has //TODO: fix so that it finds view in right view. in all three implementations, indicating a known issue with multi-region scenarios.

5. Regions property never assigned: The Regions property in all three manager implementations has a private setter but is never assigned in the constructors or elsewhere visible in the source. This property will be null unless set via reflection or another mechanism not shown.

6. Potential race condition in GetView extension: The GetView method iterates through views and assigns to a local variable; if multiple views match, only the last one is returned (not necessarily the first or only one).

7. Error handling inconsistency: Async methods catch exceptions and publish RaiseNotification events; synchronous methods do not have try-catch blocks (except RefreshView which does).