DP44/enriched-qwen3-coder-next/DataPRO/IService.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/IService/SerializableDictionary.cs DataPRO/IService/SLICE Service.Information.cs DataPRO/IService/Resources.Designer.cs	2026-04-16T03:46:23.646675+00:00	Qwen/Qwen3-Coder-Next-FP8	1	6addfe530b08a7e8

IService

Documentation: SerializableDictionary<TKey, TValue> and Slice<T> Information Module

---

1. Purpose

This module provides two core components for the DAS (Data Acquisition System) service layer:

• SerializableDictionary<TKey, TValue> is a generic dictionary implementation that supports XML serialization via IXmlSerializable, enabling persistence of key-value metadata (e.g., user attributes for SlicePro/1.5 devices).
• The Slice<T> partial class (in SLICE Service.Information.cs) implements the IInformationActions interface to asynchronously query and populate device metadata (DASInfo) for each module in a Slice stack, including serial numbers, supported configurations, and capabilities.
  Together, they support configuration discovery, state reporting, and data persistence in the Slice service layer.

---

2. Public Interface

SerializableDictionary<TKey, TValue>

• GetSchema()
XmlSchema IXmlSerializable.GetSchema()
  Returns null. Required by IXmlSerializable but unused; no schema validation is enforced.

• ReadXml(XmlReader reader)
  Deserializes XML into the dictionary. Expects root element <SerializedDictionary> containing repeated <Item> elements, each with <Key> and <Value> child elements. Uses XmlSerializer for TKey and TValue.

  • Skips empty elements (IsEmptyElement).
  • Reads <Item> → <Key> → deserialized key → <Value> → deserialized value → Add(key, value).
  • Ends with </SerializedDictionary>.

• WriteXml(XmlWriter writer)
  Serializes the dictionary to XML. Writes <SerializedDictionary> root, then iterates over Keys, writing each as <Item><Key>...</Key><Value>...</Value></Item>. Uses XmlSerializer for keys and values.

  • Calls writer.WriteStartDocument() and writer.WriteEndDocument().
  • Calls writer.Flush() after each item.

Note

: The class inherits from Dictionary<TKey, TValue>, so all standard dictionary operations (Add, Item, Keys, etc.) are available.

Slice<T> (Information Region)

• void IInformationActions.Query(ServiceCallback callback, object userData)
  Initiates asynchronous execution of AsyncQueryInformation via LaunchAsyncWorker. Wraps callback and user data in a SliceServiceAsyncInfo object.

• private void AsyncQueryInformation(object asyncInfo)
  Executes the information query:

  • Sends QueryStackContents command synchronously (SyncExecute()).
  • Constructs InfoResult with per-module metadata:
    • ModuleNumber, SerialNumber, MaxRecordingSamples, NumberOfChannels,
    • SupportedGains (cloned from GainList),
    • SupportedModes (hardcoded to CircularBuffer, RecorderMode),
    • SupportedSampleRates (cloned from SamplerateList),
    • TypeOfModule = SliceBridge.
  • Assigns result to DASInfo.
  • Handles CanceledException → info.Cancel(), other exceptions → info.Error(...).

  Note

  : MaxNumberOfSamples, NumberOfChannelsPerModule, GainList, and SamplerateList are assumed to be defined elsewhere in Slice<T> (not visible in source).

• private void DASFactoryQueryInformation()
  Not part of the public interface (private method). Appears to be a duplicate of AsyncQueryInformation but uses StackContentsQuery instead of QueryStackContents.

  • Bug/Inconsistency: Contains a reference to info.Success()/info.Cancel()/info.Error(...), but info is not defined in scope (should be var info = asyncInfo as SliceServiceAsyncInfo;). This is likely a copy-paste error or incomplete refactoring.

---

3. Invariants

• SerializableDictionary

  • XML structure must match: <SerializedDictionary><Item><Key>...</Key><Value>...</Value></Item>...</SerializedDictionary>.
  • TKey and TValue must be serializable via XmlSerializer (i.e., public parameterless constructor, public read/write properties/fields, or attributed appropriately).
  • Keys must be unique (enforced by Dictionary<TKey, TValue> base class).
  • ReadXml does not clear existing entries before deserialization (risk of duplicate key exceptions if deserializing into a non-empty instance).

• Slice<T>.Query

  • DASInfo is overwritten on each successful query.
  • SupportedModes is hardcoded to two values (CircularBuffer, RecorderMode) — not dynamically determined from hardware.
  • SupportedGains and SupportedSampleRates are cloned from class-level fields (GainList, SamplerateList), implying these fields are populated elsewhere (e.g., during initialization).
  • MaxNumberOfSamples, NumberOfChannelsPerModule, GainList, SamplerateList must be initialized before Query is called.

---

4. Dependencies

SerializableDictionary<TKey, TValue>

• Depends on:
  • System.Xml.Serialization (XmlRoot, IXmlSerializable, XmlSerializer)
  • System.Collections.Generic (via Dictionary<TKey, TValue>)
• Used by:
  • Presumably other modules needing serializable dictionaries (e.g., user attributes in SlicePro/1.5), though no direct usage is visible in the provided files.

Slice<T> (Information Module)

• Depends on:
  • DTS.DASLib.Command.SLICE.QueryStackContents (for AsyncQueryInformation)
  • DTS.DASLib.Command.SLICE.StackContentsQuery (for DASFactoryQueryInformation)
  • DTS.DASLib.Service.SliceServiceAsyncInfo (for async callback handling)
  • DTS.DASLib.Service.InfoResult (for result structure)
  • Class-level fields: MaxNumberOfSamples, NumberOfChannelsPerModule, GainList, SamplerateList
  • Base class Communication<T> and interfaces (IInformationActions, etc.)
• Used by:
  • External callers invoking IInformationActions.Query(...) (e.g., UI or orchestration layer).

---

5. Gotchas

• SerializableDictionary

  • WriteXml calls writer.WriteStartDocument() and writer.WriteEndDocument(), which may conflict if the writer is already positioned inside an XML document (e.g., when serializing as part of a larger document).
  • No handling for duplicate keys during ReadXml; will throw ArgumentException if the XML contains duplicate keys.
  • ReadXml does not validate element names beyond "Item", "Key", "Value" — malformed XML may cause XmlException or silent misbehavior.

• Slice<T>

  • DASFactoryQueryInformation() is broken: info is undefined (should be var info = asyncInfo as SliceServiceAsyncInfo;). This method is likely unused or untested.
  • SupportedModes is hardcoded — does not reflect actual hardware capabilities.
  • GainList/SamplerateList cloning assumes shallow copy is sufficient (safe for uint[], but risky if types change to reference types).
  • MaxRecordingSamples and SupportedSampleRates are set to fixed values (MaxNumberOfSamples, SamplerateList) — comments indicate these "should be adjusted to real-life", suggesting incomplete implementation.
  • No distinction between QueryStackContents and StackContentsQuery — unclear if they differ in behavior or are legacy variants.

• General

  • Resources.Designer.cs is auto-generated — manual edits will be lost. Localization strings for arming failures suggest error handling is partially implemented but may lack context (e.g., {0} placeholder for device name).
  • No unit tests or examples provided; behavior relies on XML serialization contract and command execution semantics (not visible here).