DP44/enriched-qwen3-coder-next/Common/DTS.CommonCore/Classes/ChannelCodes.md

---
source_files:
  - Common/DTS.CommonCore/Classes/ChannelCodes/TextPastedArgs.cs
  - Common/DTS.CommonCore/Classes/ChannelCodes/ChannelCode.cs
generated_at: "2026-04-16T02:39:51.595748+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "9a72b7f2cc9cf8aa"
---

# ChannelCodes

## Documentation: ChannelCode Module

---

### 1. Purpose

This module provides core data and command infrastructure for handling *channel codes*—named identifiers (e.g., ISO or user-defined codes) used to categorize or label channels in the system. It defines the `ChannelCode` class as the canonical implementation of `IChannelCode`, including persistence support via `IDataReader`, equality semantics, and property change notification. It also defines `PasteCommandClass`, a `ICommand` implementation that intercepts text paste operations in UI text boxes, processes clipboard content (including multi-line or delimited data), and publishes structured `TextPastedArgs` events for downstream handling—while suppressing default paste behavior to enable custom logic.

---

### 2. Public Interface

#### `class ChannelCode : BasePropertyChanged, IChannelCode`

- **`int Id { get; set; }`**  
  Unique numeric identifier for the channel code. Initialized to `-1` by default.

- **`UIItemStatus ItemStatus { get; set; }`**  
  Status of the item (e.g., `None`, `New`, `Modified`, `Deleted`). Uses `SetProperty` for change notification.

- **`string Code { get; protected set; }`**  
  The code string (e.g., `"A1"`, `"ISO-8601"`). Protected setter allows subclassing.

- **`string Name { get; protected set; }`**  
  Human-readable name for the channel code (e.g., `"Temperature Sensor"`).

- **`ChannelEnumsAndConstants.ChannelCodeType CodeType { get; set; }`**  
  Enumerated type of the code: `User` or `ISO`. Default is `ISO` in parameterless constructor.

- **`const string PASTE_ID = "ChannelCode"`**  
  Static identifier used to correlate paste operations with this channel code type.

- **`ICommand PasteCommand { get; set; } = null`**  
  Command bound to text boxes to handle paste operations. Defaults to `null` to avoid exceptions during UI construction.

- **`ChannelCode(IDataReader reader, IReadOnlyDictionary<short, string> channelTypeLookup)`**  
  Constructor that initializes the instance from a database record. Reads `Id`, `Code`, `Name`, and `CodeTypeInt` columns. Uses `channelTypeLookup` to map `CodeTypeInt` to `ChannelCodeType` (`User` or `ISO`) via string keys (`"User"` / `"ISO"`).

- **`ChannelCode()`**  
  Parameterless constructor. Sets `CodeType` to `ISO`.

- **`ChannelCode(IChannelCode channelCode)`**  
  Copy constructor. Copies `Id`, `Code`, `Name`, and `CodeType` from another `IChannelCode`.

- **`override bool Equals(object obj)`**  
  Equality comparison based on `Code`, `Name`, and `CodeType`. Returns `false` if `obj` is not a `ChannelCode`.

- **`~ChannelCode()`**  
  Finalizer that nulls `_code` and `_name` to reduce memory footprint if the object is held longer than expected.

#### `class PasteCommandClass : ICommand`

- **`string Id { get; }`**  
  Identifier passed at construction; used to tag paste events.

- **`bool CanExecute(object parameter)`**  
  Always returns `true`.

- **`void Execute(object parameter)`**  
  Handles paste logic:
  - Requires `parameter` to be a `TextBox`.
  - Attempts to resolve `IChannelCode` from `TextBox.DataContext`, with fallbacks to `ChannelCodeBuilder` or `ChannelNameBuilder` view models.
  - Reads clipboard text.
  - If clipboard contains **exactly one line** and **no delimiters** (`,`, `;`, `\t`), publishes a `PageModifiedEvent` and exits early (single-field paste is handled by `TextChanged`).
  - Otherwise:
    - Resets `Code` and `Name` properties (no-op assignment to trigger change notifications).
    - Publishes a `TextPastedEvent` with a `TextPastedArgs` instance containing:
      - `Text`: full clipboard content
      - `Sender`: resolved `IChannelCode`
      - `Id`: `PasteCommandClass.Id`
      - `Tag`: `TextBox.Tag`
  - Catches and reports exceptions via `PageErrorEvent`.

- **`PasteCommandClass(string id)`**  
  Constructor storing `id` in `Id` property.

#### `delegate string CoerceISOCodeDelegate(...)`

- **`string CoerceISOCodeDelegate(string val, bool uniqueISOCodesRequired, bool useISOCodeFilterMapping)`**  
  Signature for a delegate used to transform or validate incoming ISO codes. Not implemented in this file—only declared.

---

### 3. Invariants

- **`ChannelCode.Code` and `ChannelCode.Name` must be non-null**  
  Initialized to `string.Empty` and never set to `null` (via `SetProperty` and constructor defaults).

- **`ChannelCode.Id` defaults to `-1`**  
  A value of `-1` indicates the code has not been persisted or assigned.

- **`ChannelCode.CodeType` defaults to `ISO`**  
  Unless explicitly set otherwise (e.g., via constructor with `IDataReader` or copy constructor).

- **Equality is based on `Code`, `Name`, and `CodeType`**  
  `Id` is *not* part of equality semantics.

- **Paste command only processes `TextBox` parameters**  
  Non-`TextBox` inputs are silently ignored.

- **Clipboard text is split by `Environment.NewLine`**  
  Only single-line, non-delimited text bypasses `TextPastedEvent`; all other cases trigger it.

---

### 4. Dependencies

#### *This module depends on:*
- **`DTS.Common.Base`**  
  Provides `BasePropertyChanged` (base class for `ChannelCode`).
- **`DTS.Common.Interface.Channels.ChannelCodes`**  
  Defines `IChannelCode` interface.
- **`DTS.Common.Enums`**  
  Provides `UIItemStatus`, `ChannelEnumsAndConstants` (enum `ChannelCodeType`, string constants `"User"`, `"ISO"`).
- **`DTS.Common.Events`**  
  Defines `PageModifiedEvent`, `TextPastedEvent`, `PageErrorEvent`, and argument types (`PageModifiedArg`, `TextPastedArgs`, `PageErrorArg`).
- **`System.Data`**  
  For `IDataReader`.
- **`System.Windows` / `System.Windows.Controls` / `System.Windows.Input`**  
  For `UIElement`, `TextBox`, `ICommand`.
- **`Microsoft.Practices.Prism.Events`**  
  For `IEventAggregator`.
- **`Microsoft.Practices.ServiceLocation`**  
  For `ServiceLocator`.

#### *This module is depended on by:*
- Any UI layer components that bind `ChannelCode` instances to views (e.g., `ChannelCodeBuilder`, `ChannelNameBuilder`).
- Event handlers subscribed to `TextPastedEvent`.
- Code that constructs `ChannelCode` instances from database readers or clones them.

---

### 5. Gotchas

- **`PasteCommand` defaults to `null`**  
  To avoid exceptions during UI construction (per inline comment: *"putting a null here avoids wasteful exception"*). Consumers must explicitly assign a `PasteCommandClass` instance.

- **`ChannelCode.Equals` ignores `Id`**  
  Two codes with different IDs but identical `Code`, `Name`, and `CodeType` are considered equal. This may cause issues if IDs are expected to be unique in comparisons.

- **`~ChannelCode()` finalizer nulls fields but does not prevent GC of the object**  
  This is a cleanup heuristic, not a disposal pattern. No `IDisposable` implementation is present.

- **Single-line paste with delimiters still triggers `TextPastedEvent`**  
  Only *single-line, no-delimiter* text skips the event; multi-line or single-line with `,`, `;`, or `\t` always publish `TextPastedArgs`.

- **`PasteCommand.Execute` silently ignores invalid contexts**  
  If `parameter` is not a `TextBox`, or `DataContext` is not an `IChannelCode`/builder, the method returns without error or logging (except via `PageErrorEvent` on exception).

- **`CoerceISOCodeDelegate` is declared but not implemented here**  
  Its purpose is documented, but no concrete implementation is provided in this module.

- **`ChannelCode` constructor with `IDataReader` relies on column names and lookup dictionary**  
  If `channelTypeLookup` lacks the key from `CodeTypeInt`, or columns are missing, behavior is undefined (no explicit validation is present).