73 lines
4.4 KiB
Markdown
73 lines
4.4 KiB
Markdown
---
|
|
source_files:
|
|
- Common/DTS.Common.Storage/Classes/Static/CustomChannelFieldSizeAttribute.cs
|
|
generated_at: "2026-04-16T11:54:41.555458+00:00"
|
|
model: "zai-org/GLM-5-FP8"
|
|
schema_version: 1
|
|
sha256: "96c94c51da2a1b2d"
|
|
---
|
|
|
|
# Documentation: CustomChannelFieldSizeAttribute.cs
|
|
|
|
## 1. Purpose
|
|
|
|
This module provides a mechanism for associating fixed size metadata with enum values (specifically `MMETables.MMEPossibleChannelsFields`), enabling retrieval of custom field sizes via reflection. It exists to decouple size configuration from business logic, allowing channel field sizes to be defined declaratively as attributes on enum members rather than hard-coded elsewhere.
|
|
|
|
---
|
|
|
|
## 2. Public Interface
|
|
|
|
### `CustomChannelFieldSizeAttribute` (Class)
|
|
A custom attribute that stores an integer size value.
|
|
|
|
| Member | Signature | Description |
|
|
|--------|-----------|-------------|
|
|
| Constructor | `internal CustomChannelFieldSizeAttribute(int size)` | Creates an instance with the specified size. **Note: Internal access only.** |
|
|
| Property | `public int Size { get; private set; }` | Gets the size value. Read-only after construction. |
|
|
|
|
### `CustomChannelFieldSizeExtensions` (Static Class)
|
|
Provides helper methods for retrieving field sizes.
|
|
|
|
| Method | Signature | Description |
|
|
|--------|-----------|-------------|
|
|
| `GetFieldSize` | `public static int GetFieldSize(MMETables.MMEPossibleChannelsFields field)` | Retrieves the `Size` value from the `CustomChannelFieldSizeAttribute` applied to the given enum value. **Not an extension method**—must be called statically. |
|
|
|
|
### `EnumExtensions` (Static Class)
|
|
Provides generic reflection-based attribute retrieval for enum values.
|
|
|
|
| Method | Signature | Description |
|
|
|--------|-----------|-------------|
|
|
| `GetAttribute<TAttribute>` | `public static TAttribute GetAttribute<TAttribute>(this Enum value) where TAttribute : Attribute` | Extension method that retrieves a single custom attribute of type `TAttribute` from the given enum value. Returns `null` if not found; throws `InvalidOperationException` if multiple matching attributes exist. |
|
|
|
|
---
|
|
|
|
## 3. Invariants
|
|
|
|
- **Attribute Application**: `GetFieldSize` assumes that `CustomChannelFieldSizeAttribute` is always applied to the passed `MMEPossibleChannelsFields` enum value. If the attribute is missing, a `NullReferenceException` will occur.
|
|
- **Single Attribute Constraint**: `GetAttribute<TAttribute>` uses `SingleOrDefault()`, enforcing that at most one attribute of a given type may be present on any enum value. Multiple attributes of the same type will cause an `InvalidOperationException`.
|
|
- **Immutability**: The `Size` property is set only at construction and cannot be modified thereafter (private setter).
|
|
- **Construction Restriction**: The attribute constructor is `internal`, meaning attributes can only be defined within the same assembly.
|
|
|
|
---
|
|
|
|
## 4. Dependencies
|
|
|
|
### This module depends on:
|
|
- `System` (for `Attribute`, `Enum`, `Type` reflection APIs)
|
|
- `System.Linq` (for `OfType<T>()`, `SingleOrDefault()`)
|
|
- `MMETables.MMEPossibleChannelsFields` — an external enum type that this module is designed to annotate. **Location/assembly not visible in source.**
|
|
|
|
### What depends on this module:
|
|
- Cannot be determined from source alone. Consumers would be any code that needs to retrieve field sizes for `MMEPossibleChannelsFields` enum values.
|
|
|
|
---
|
|
|
|
## 5. Gotchas
|
|
|
|
1. **`GetFieldSize` is NOT an extension method** — Despite being defined in a class named `CustomChannelFieldSizeExtensions`, the method lacks the `this` keyword on its parameter. It must be called as `CustomChannelFieldSizeExtensions.GetFieldSize(field)`, not `field.GetFieldSize()`.
|
|
|
|
2. **Potential `NullReferenceException`** — `GetFieldSize` directly accesses `.Size` on the result of `GetAttribute<CustomChannelFieldSizeAttribute>()` without null-checking. If the enum value lacks this attribute, the method will throw.
|
|
|
|
3. **Internal constructor limits extensibility** — The `internal` constructor means consumers outside this assembly cannot create new instances of `CustomChannelFieldSizeAttribute`. This is likely intentional to control where/how the attribute is applied, but could be restrictive for testing or extension scenarios.
|
|
|
|
4. **Tight coupling to specific enum type** — `GetFieldSize` is hardcoded to `MMETables.MMEPossibleChannelsFields`, making this utility non-reusable for other enums even though `GetAttribute<T>` is generic. |