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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.CommonCore/Classes/ChannelCodes/TextPastedArgs.cs Common/DTS.CommonCore/Classes/ChannelCodes/ChannelCode.cs	2026-04-16T02:39:51.595748+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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).