DP44/enriched-qwen3-coder-next/Common/DTS.Common/Interface/Groups/GroupList.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common/Interface/Groups/GroupList/IGroupListView.cs Common/DTS.Common/Interface/Groups/GroupList/TestSetupParentHelper.cs Common/DTS.Common/Interface/Groups/GroupList/IGroupListViewModel.cs Common/DTS.Common/Interface/Groups/GroupList/IGroup.cs	2026-04-16T03:07:21.318900+00:00	Qwen/Qwen3-Coder-Next-FP8	1	cfa13e8b0909ec6a

GroupList

Documentation: Group List Module

---

1. Purpose

This module defines the core interfaces and supporting types for managing groups—logical collections of test hardware (e.g., sensors, data recorders, channels)—within the DTS system. It provides a standardized contract for group data modeling (IGroup), group list management and filtering (IGroupListViewModel), and view-layer integration (IGroupListView). The module serves as the domain abstraction layer between UI components and underlying data persistence (e.g., database via IGroupDbRecord), enabling features like group creation, editing, deletion, hardware association, XML export/import, and test setup association.

---

2. Public Interface

Interfaces

• IGroupListView : IBaseView
  Namespace: DTS.Common.Interface.Groups.GroupTemplateList
  Marker interface for the view layer associated with group list display. Inherits IBaseView. No additional members.

• IGroupListViewModel : IBaseViewModel, IFilterableListView
  Namespace: DTS.Common.Interface.Groups.GroupList
  ViewModel managing the group list state and operations. Key members:

  • IGroupListView View { get; set; } – Binds to the view instance.
  • void Unset() – Releases resources or clears state (exact semantics not specified in source).
  • void Sort(object o, bool columnClick) – Sorts the group list; o likely identifies the sort key/column.
  • IGroup[] Groups { get; set; } – Gets or sets the current list of groups.
  • void OnSetActive(object page, bool groupTile, object currentUser) – Initializes or activates the view for a specific context (page, currentUser) and display mode (groupTile).
  • void MouseDoubleClick(int index) – Handles double-click on group at index.
  • void Filter(string term) – Filters the group list by term.
  • IGroup GetGroup(int? id, bool updateTags = true) – Retrieves a group by ID; optionally updates tags.
  • IGroup GetGroup(string displayName) – Retrieves a group by displayName.
  • IGroup[] GetGroups(int[] ids) – Retrieves multiple groups by IDs.
  • IGroup[] GetAllGroups() – Retrieves all groups.
  • void DeleteGroups(int[] ids) – Deletes groups by IDs.
  • IGroup CreateGroup() – Creates a new, unsaved group.
  • IGroup CreateGroup(List<string> includedHardwareStringList) – Creates a new group, pre-populating hardware via legacy string IDs.
  • IGroup CreateGroup(SqlDataReader reader, List<string> includedHardwareStringList, List<int> dasIdList) – Creates a group from database record and hardware lists.
  • IGroup CreateGroup(IGroupDbRecord groupRecord, List<string> includedHardwareStringList, List<int> dasIdList) – Creates a group from a database record and hardware lists.

• IGroup : IComparable<IGroup>
  Namespace: DTS.Common.Interface.Groups.GroupList
  Core domain interface for a group entity. Key members:

  • int Id { get; set; }, string Name { get; set; }, string DisplayName { get; set; }, string Description { get; set; } – Basic metadata.
  • int? StaticGroupId { get; set; }, bool IsDifferentThanStaticGroup { get; set; }, bool StaticGroupIsEqual() – Support for static group templates.
  • bool Embedded { get; set; } – Indicates if group is embedded (non-editable?).
  • DateTime LastModified { get; set; }, string LastModifiedBy { get; set; } – Audit fields.
  • int[] IncludedHardware { get; set; }, string[] IncludedHardwareStringList { get; set; } – Hardware associations (new and legacy ID formats).
  • bool Filter(string term) – Returns true if group matches term.
  • bool Save(Channels.IGroupChannel[] groupChannels, bool canUserCommitChannelCodes)
bool Save(Channels.IGroupChannel[] groupChannels, bool canUserCommitChannelCodes, ref List<IGroupChannel> newGroupChannelList)
    Persists group and its channels; returns success. Second overload tracks newly created channels.
  • void ClearGroupChannelSettingCache(long groupId) – Clears cached channel settings for this group.
  • Channels.IGroupChannel[] GetAllChannels(bool bEditable, IDictionary<int, ISensorData> sensorLookup, IDictionary<int, IDASHardware> hardwareLookup, IChannelSetting[] channelDefaults, bool allowSensorPushAndPull = false) – Retrieves all channels for this group, with lookups for sensors/hardware and defaults.
  • void LoadHardware() – Loads associated hardware data.
  • void ConvertToEmbedded(Channels.IGroupChannel[] groupChannels) – Converts group to embedded state.
  • void DeterminePositionAndTestObject(Channels.IGroupChannel[] channels) – Infers position/test object values from channels.
  • bool PositionIsMixed { get; set; }, bool PositionIsTextbox { get; set; }, bool PositionIsCombobox { get; set; }, string Position { get; set; } – UI state for position field.
  • bool TestObjectIsMixed { get; set; }, string TestObject { get; set; } – UI state for test object field.
  • int DisplayOrder { get; set; } – Sort order in UI.
  • ISensorData GetSensor(Channels.IGroupChannel channel, ISensorData sensorData, bool bUseIsoFilter)
void SetSensor(Channels.IGroupChannel channel, ISensorData sensorData) – Sensor read/write helpers.
  • void WriteXML(ref XmlWriter writer)
IGroup ReadXML(XmlElement node, Dictionary<long, IGroupChannel> channelLookup, List<ISensorData> sensors) – XML serialization/deserialization.
  • List<Channels.IGroupChannel> GroupChannelList { get; set; } – In-memory channel list.
  • void SetIncludedHardware(int[] hardware) – Sets hardware list and marks data as loaded.
  • List<TestSetupParentHelper> AssociatedTestSetups { get; set; } – Associated test setups.
  • void SetTestSetupLists() – Populates AssociatedTestSetups.
  • bool TagCompatible(int[] tags) – Checks if group’s tags are compatible with tags.
  • int[] TagIDs { get; set; }, string Tags { get; set; } – Tag metadata.
  • string GetTagsAsCommaSeparatedString(TagsGetDelegate tagsGet) – Formats tags as CSV using a delegate.
  • List<string> AvailableTestObjects { get; set; }, string SelectedTestObjectItem { get; set; }
List<string> AvailablePositions { get; set; }, string SelectedPositionItem { get; set; } – UI selection lists.

Classes

• TestSetupParentHelper
  Namespace: DTS.Common.Interface.Groups.GroupList
  Simple DTO for test setup associations:
  • int Id – Public field.
  • string Name { get; set; } – Display name.
  • bool Modified { get; set; } – Tracks modification state.
  • override string ToString() – Returns Name.

---

3. Invariants

• IGroup.Id must be non-null and unique per group instance (implied by GetGroup(int? id) and DeleteGroups(int[] ids)).
• IGroup.DisplayName is used for display and filtering (Filter(string term)), implying it must be non-null and stable.
• IGroup.IncludedHardware and IGroup.IncludedHardwareStringList must be kept in sync; the latter is explicitly noted as legacy (primarily for import).
• IGroup.Save(...) must persist both group metadata and channel state; return value indicates success/failure.
• IGroup.Filter(string term) must return true if and only if the group matches the search term (case-sensitivity not specified).
• IGroupListViewModel.Groups must reflect the current filtered/sorted state after Filter() or Sort() calls.
• IGroupListViewModel.GetGroup(...) methods must return a valid IGroup instance (or null if not found), with optional tag updates (updateTags parameter).
• IGroup.TagCompatible(int[] tags) must validate tag compatibility against group’s TagIDs.

---

4. Dependencies

This module depends on:

• DTS.Common.Base (IBaseView, IBaseViewModel, IFilterableListView)
• DTS.Common.Interface.Pagination (via IFilterableListView)
• DTS.Common.Interface.Channels (IGroupChannel, IChannelSetting)
• DTS.Common.Interface.Sensors (ISensorData)
• DTS.Common.Interface.DataRecorders (IDASHardware)
• DTS.Common.Interface.TestSetups.TestSetupsList (TestSetupParentHelper usage implies dependency)
• System.Xml, System.Data.SqlClient (for XmlWriter, XmlElement, SqlDataReader)

This module is depended upon by:

• UI components implementing IGroupListView (e.g., WPF/WinForms views).
• ViewModels or services implementing IGroupListViewModel (e.g., GroupListViewModel in UI layer).
• Persistence layers implementing IGroupDbRecord (not shown here, but referenced by IGroup.GetIGroupDbRecord() and IGroup.CreateGroup(...) overloads).

---

5. Gotchas

• IncludedHardwareStringList is explicitly documented as a legacy field for import purposes; relying on it for current logic may be risky.
• IGroup.CreateGroup(...) overloads accept List<string> includedHardwareStringList and List<int> dasIdList—but dasIdList is only used in two overloads. Inconsistent usage may indicate incomplete refactoring.
• IGroup.Save(...) has two overloads differing only by ref List<IGroupChannel> newGroupChannelList. The ref parameter suggests mutation of caller-provided lists; callers must initialize the list before invocation.
• IGroupListViewModel.OnSetActive(...) uses object for page, currentUser, and groupTile (a bool). This indicates weak typing; consumers must know the expected types (e.g., page likely a page/view instance, currentUser a user principal).
• TestSetupParentHelper is in namespace DTS.Common.Interface.Groups.GroupList, but IGroupListView is in DTS.Common.Interface.Groups.GroupTemplateList. Namespace inconsistency may cause confusion.
• IGroup.PositionIsMixed, PositionIsTextbox, PositionIsCombobox are separate flags—UI logic must ensure consistency (e.g., only one should be true at a time), but this is not enforced by the interface.
• GetTagsAsCommaSeparatedString requires a delegate (TagsGetDelegate), but its signature is not defined in this source. Callers must infer or reference Classes.Tags.TagsInstance.
• Filter(string term) behavior (e.g., case sensitivity, substring vs. prefix match) is not specified beyond "returns true if group matches search term".