DP44/enriched-qwen3-coder-next/Common/DTS.Common/Events/GroupTemplates/TemplateChannelList.md

---
source_files:
  - Common/DTS.Common/Events/GroupTemplates/TemplateChannelList/TemplateChannelListOrderChangedEvent.cs
  - Common/DTS.Common/Events/GroupTemplates/TemplateChannelList/TemplateChannelListSelectionChangedEvent.cs
  - Common/DTS.Common/Events/GroupTemplates/TemplateChannelList/TemplateChannelListRequiredChangedEvent.cs
generated_at: "2026-04-16T03:26:02.944009+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "0971a3dcff5effca"
---

# TemplateChannelList

## Documentation: TemplateChannelList Events Module

### 1. Purpose  
This module defines Prism-based pub/sub events used to signal changes in the state of a *template channel list*—a UI or business construct representing ordered, configurable channels associated with a group template. Specifically, it enables decoupled communication between components that manage or consume channel lists (e.g., UI views, view models, or services), notifying them when the *order*, *selection*, or *required-ness* of channels changes. Though the XML documentation comments are misleading (referring to “template selection” instead of channel list state), the actual event types and payloads indicate they are concerned with channel-level state transitions.

---

### 2. Public Interface  

#### `TemplateChannelListOrderChangedEvent`  
- **Type**: `class`  
- **Inherits**: `PubSubEvent<IGroupTemplateChannel>`  
- **Behavior**: Published when the *ordering* of channels in a template channel list changes. The payload is the *single channel* whose position has changed (e.g., moved up/down in the list). Subscribers can use this to reorder internal structures or update UI bindings accordingly.  

#### `TemplateChannelListSelectionChangedEvent`  
- **Type**: `class`  
- **Inherits**: `PubSubEvent<IGroupTemplateChannel>`  
- **Behavior**: Published when the *selection state* of a channel in the list changes (e.g., user selects/deselects a channel). The payload is the *channel* whose selection status changed.  

#### `TemplateChannelListRequiredChangedEvent`  
- **Type**: `class`  
- **Inherits**: `PubSubEvent<TemplateChannelListRequiredChangeEventArgs>`  
- **Behavior**: Published when the *required status* of one or more channels changes (e.g., a channel becomes mandatory or optional). The payload is a `TemplateChannelListRequiredChangeEventArgs` object containing:  
  - `Consumer`: The object (e.g., view model or service) triggering the change.  
  - `Channels`: An array of `IGroupTemplateChannel` instances whose required status has changed.  

#### `TemplateChannelListRequiredChangeEventArgs`  
- **Type**: `class`  
- **Properties**:  
  - `public object Consumer { get; }` — The entity initiating the required-status change.  
  - `public IGroupTemplateChannel[] Channels { get; }` — The channels affected by the required-status change.  
- **Constructor**:  
  ```csharp
  public TemplateChannelListRequiredChangeEventArgs(object o, IGroupTemplateChannel[] channels)
  ```  
  Initializes the args with the specified consumer and channel array.

---

### 3. Invariants  
- All events are **asynchronous** (via Prism’s `PubSubEvent`), so ordering of delivery to subscribers is *not guaranteed*.  
- The `IGroupTemplateChannel` type is assumed to represent a single channel with identity, name, and state (e.g., selection, required flag), but its exact contract is defined externally (see *Dependencies*).  
- For `TemplateChannelListOrderChangedEvent` and `TemplateChannelListSelectionChangedEvent`, only *one* channel is emitted per event—no batch semantics are implied.  
- For `TemplateChannelListRequiredChangedEvent`, the `Channels` array may contain *zero or more* channels, but the event is only published when at least one channel’s required status changes.  
- The `Consumer` field in `TemplateChannelListRequiredChangeEventArgs` is *not validated*—it may be `null`, though this is discouraged.

---

### 4. Dependencies  

#### Dependencies *of this module*:  
- `Prism.Events` — Provides the base `PubSubEvent<T>` class.  
- `DTS.Common.Interface.GroupTemplate.IGroupTemplateChannel` — Defines the interface for channel objects. Its contract is assumed to include properties like `IsSelected`, `IsRequired`, and identity (e.g., `Id`), but this is not visible in the source.  

#### Dependencies *on this module*:  
- Any component managing or reacting to channel list state (e.g., UI views, view models, or services in the `DTS.Common` or higher layers) will subscribe to these events.  
- The `TemplateChannelListRequiredChangedEvent` suggests integration with a consumer registration pattern (via the `Consumer` property), implying downstream systems track which entities are responsible for channel requirements.

---

### 5. Gotchas  
- **Misleading documentation**: All three events’ XML comments incorrectly state *“called when a template is selected”*—this is inconsistent with their actual payloads and naming. This may cause confusion during debugging or onboarding.  
- **Ambiguous semantics of `Consumer`**: The `Consumer` field in `TemplateChannelListRequiredChangeEventArgs` is typed as `object`, offering no compile-time safety or clarity about expected types. This increases the risk of runtime errors if consumers misidentify the source of the change.  
- **No distinction between *initiator* and *affected channels***: In `TemplateChannelListRequiredChangedEvent`, the `Consumer` and `Channels` are bundled together, but it is unclear whether *all* channels in the array changed *because of* the consumer or *for* the consumer. This could lead to incorrect assumptions about causality.  
- **No event for bulk operations**: If multiple channels’ order or selection changes simultaneously (e.g., drag-and-drop reordering of several items), this module provides no event to signal the full set—only per-channel events. Subscribers must deduce batch changes by correlating events, which is error-prone.  
- **No cancellation or rollback mechanism**: These are *notification-only* events (fire-and-forget). There is no way for subscribers to veto a change (e.g., prevent an invalid reordering).  

None identified beyond the above.