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

---
source_files:
  - DataPRO/IService/SerializableDictionary.cs
  - DataPRO/IService/SLICE Service.Information.cs
  - DataPRO/IService/Resources.Designer.cs
generated_at: "2026-04-16T03:46:23.646675+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "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).