DP44/enriched-qwen3-coder-next/Common/DTS.Common.SerializationPlus.md

---
source_files:
  - Common/DTS.Common.SerializationPlus/EventInfoAggregate.cs
generated_at: "2026-04-16T14:13:19.550350+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "342395eec4a038a1"
---

# Documentation: EventInfoAggregate

## 1. Purpose

`EventInfoAggregate` is an aggregate data structure that consolidates event information from multiple Data Acquisition System (DAS) devices/modules into a single unified view. It implements `IEventInfoAggregate` and serves as a central repository for event metadata during download operations, tracking properties like event identification, duration, channel counts, sample counts, and fault status across multiple hardware units that recorded the same event.

---

## 2. Public Interface

### Properties

| Property | Type | Description |
|----------|------|-------------|
| `EventId` | `string` | Identifier for the test/event. |
| `EventDescription` | `string` | Human-readable description of the event. |
| `DurationSeconds` | `double` | Total event duration in seconds (PreTriggerSeconds + PostTriggerSeconds). |
| `GUID` | `string` | Globally unique identifier for the test. |
| `HasBeenDownloaded` | `bool` | Indicates whether the event data has been downloaded. |
| `WasTriggered` | `bool` | Indicates whether the event was triggered. |
| `NumberOfChannels` | `int` | Total number of channels across all modules. |
| `NumberOfSamples` | `ulong` | Number of samples per channel. |
| `NumberOfBytes` | `ulong` | Calculated total bytes: `NumberOfSamples * NumberOfChannels * 2`. |
| `Faulted` | `bool` | Indicates if any module reported a fault condition. |
| `EventNumber` | `int` | Sequential event number identifier. |

### Methods

#### `EventInfoAggregate(DownloadReport.EventInfo newEvent)`
Constructor that initializes the aggregate from a single `DownloadReport.EventInfo`. Populates all properties and adds the first DAS module to the internal `_eventIndices` dictionary.

#### `void Add(IEventInfo newEvent)`
Merges additional event information from another module into this aggregate. Accumulates channel counts, recalculates `NumberOfBytes`, updates `Faulted` status, and adds the DAS to `_eventIndices`. Logs warnings for mismatched fields but does not throw exceptions.

#### `Slice.Control.Event GetEvent()`
Returns a lazily-instantiated `Slice.Control.Event` object, creating it if necessary.

#### `Slice.Control.Event GetEvent(bool bClear)`
Returns the `Slice.Control.Event` object. If `bClear` is `true`, resets the cached `_event` to null before returning (forcing recreation on next call).

#### `int GetEventIndex(IDASCommunication idas)`
Returns the event index for a specific DAS device. Returns `-1` and logs an error if the DAS is not found in `_eventIndices`.

#### `List<IDASCommunication> GetDasList()`
Returns a lazily-instantiated list of all DAS devices associated with this event. The list is cached after first creation.

---

## 3. Invariants

- **Empty Modules Handling**: When `Modules` collection is empty, `DurationSeconds` and `NumberOfSamples` are set to `0` rather than throwing an exception.
- **Byte Calculation**: `NumberOfBytes` is always calculated as `2 * NumberOfChannels * NumberOfSamples` (assumes 2 bytes per sample per channel).
- **Fault Detection**: An event is considered faulted if `FaultFlags != 0` OR `FaultFlagsEx != 0` on any constituent module.
- **Event Index Dictionary**: `_eventIndices` is always initialized (readonly field) and maps `IDASCommunication` instances to their event numbers.
- **Minimum Value Resolution**: When merging events with mismatched `DurationSeconds` or `NumberOfSamples`, the minimum value is retained.

---

## 4. Dependencies

### This module depends on:
- `System`, `System.Collections.Generic`, `System.Linq` (BCL)
- `DTS.Common.Interface.DASFactory` — provides `IDASCommunication`
- `DTS.Common.Interface.DASFactory.Download` — provides `DownloadReport.EventInfo`, `IEventInfo`, `DASModule`
- `DTS.Common.Utilities.Logging` — provides `APILogger`
- `DTS.DASLib.Service` — namespace import (specific usage unclear from source)
- `Slice.Control.Event` — external type instantiated in `GetEvent()` (assembly/source not specified in imports)

### What depends on this module:
- Not determinable from source alone. The `IEventInfoAggregate` interface suggests consumers depend on the interface rather than concrete implementation.

---

## 5. Gotchas

1. **Silent Mismatch Handling**: The `Add()` method logs warnings for mismatched `TestID`, `Description`, `GUID`, `HasBeenDownloaded`, `WasTriggered`, and `EventNumber` values but **continues processing**. Callers are not notified of data integrity issues beyond log entries.

2. **Minimum Value Strategy**: When `DurationSeconds` or `NumberOfSamples` differ between modules being aggregated, the code silently takes the minimum value. This may result in data loss if larger values are correct.

3. **Empty Modules Edge Case**: The constructor guards against empty `Modules` collections (added per case 15575), but the `Add()` method **does not** — it accesses `newEvent.Modules[0]` without null/empty checks, which will throw `ArgumentOutOfRangeException` if `Modules` is empty.

4. **Lazy Initialization Side Effects**: `GetDasList()` and `GetEvent()` cache their results. The `_das` list is not invalidated when `Add()` is called, potentially returning stale data if `GetDasList()` was called before all `Add()` operations completed.

5. **Index Assignment for Duplicates**: `_eventIndices` uses indexer assignment (`_eventIndices[...] = value`) rather than `.Add()` to silently overwrite duplicate keys. This was added per case 44357 but means duplicate DAS entries are not detected or logged.

6. **Error Return Convention**: `GetEventIndex()` returns `-1` for missing keys rather than throwing an exception. Callers must check for this sentinel value.