init

enriched-qwen3-coder-next/Common/DTS.Common.Storage/Classes/Static.md

@@ -0,0 +1,43 @@
+---
+source_files:
+  - Common/DTS.Common.Storage/Classes/Static/CustomChannelFieldSizeAttribute.cs
+generated_at: "2026-04-16T02:11:01.276588+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "96c94c51da2a1b2d"
+---
+
+# Static
+
+## 1. Purpose  
+This module provides a mechanism to associate custom, non-default field sizes with enum values representing channel fields in the `MMETables.MMEPossibleChannelsFields` enumeration. It enables runtime retrieval of field-specific size metadata via a custom attribute (`CustomChannelFieldSizeAttribute`) and extension methods, supporting scenarios where the default size inference (e.g., based on underlying type or convention) is insufficient or incorrect.
+
+## 2. Public Interface  
+- **`CustomChannelFieldSizeAttribute(int size)`**  
+  *Constructor.* Creates an attribute instance with the specified field size. `size` must be non-negative (enforced by caller; no validation in constructor).  
+- **`int Size { get; }`**  
+  *Property.* Returns the field size stored in the attribute. Read-only after construction.  
+- **`int GetFieldSize(MMETables.MMEPossibleChannelsFields field)`**  
+  *Extension method.* Retrieves the field size for a given `MMEPossibleChannelsFields` enum value by inspecting its `CustomChannelFieldSizeAttribute`. Throws `NullReferenceException` if the attribute is not applied to the enum value (since `.Size` is accessed on a `null` reference returned by `GetAttribute<>()`).  
+- **`TAttribute GetAttribute<TAttribute>(this Enum value)`**  
+  *Extension method.* Returns the first (and expected only) custom attribute of type `TAttribute` applied to the enum value, or `null` if none exists. Uses reflection to inspect the enum field’s attributes.
+
+## 3. Invariants  
+- `CustomChannelFieldSizeAttribute` is only intended for use on `MMETables.MMEPossibleChannelsFields` enum members.  
+- The `Size` property must be set at construction and remains immutable thereafter.  
+- `GetFieldSize` assumes exactly one `CustomChannelFieldSizeAttribute` per enum member; behavior is undefined if multiple attributes are applied (though `SingleOrDefault()` would return the first if duplicates exist, which is invalid per attribute semantics).  
+- `GetAttribute<TAttribute>` returns `null` if no attribute of type `TAttribute` is present on the enum value.
+
+## 4. Dependencies  
+- **Internal dependencies:**  
+  - `MMETables.MMEPossibleChannelsFields` enum (from `MMETables` namespace—external to this file but referenced in `GetFieldSize`).  
+  - Standard .NET reflection APIs (`System.Type`, `System.Reflection.FieldInfo`, `System.Linq.Enumerable`).  
+- **No external NuGet or third-party dependencies** beyond the base class library.  
+- **Dependent modules:** Any code that needs to retrieve field sizes for `MMEPossibleChannelsFields` values—likely storage or serialization components dealing with channel data.
+
+## 5. Gotchas  
+- **Null reference risk:** `GetFieldSize` will throw `NullReferenceException` if `CustomChannelFieldSizeAttribute` is not applied to the queried enum member (since `GetAttribute<>()` returns `null`, and `.Size` is dereferenced unconditionally). Callers must ensure the attribute is present or guard against `null`.  
+- **No validation on `size`:** The constructor accepts any `int`, including negative values. No runtime checks enforce valid size constraints (e.g., `size ≥ 0`).  
+- **Reflection overhead:** `GetAttribute<TAttribute>` uses reflection on every call; not suitable for hot paths without caching.  
+- **Ambiguity in `MMETables` namespace:** The `MMETables.MMEPossibleChannelsFields` type is referenced but not defined here; its actual definition and available members are unknown from this file alone.  
+- **No XML documentation:** The source contains no comments; behavior is inferred solely from code structure.