62 lines
5.1 KiB
Markdown
62 lines
5.1 KiB
Markdown
---
|
|
source_files:
|
|
- Common/DTS.Common.SharedResource/EnumDescriptionTypeConverterShared.cs
|
|
generated_at: "2026-04-16T14:09:08.524631+00:00"
|
|
model: "zai-org/GLM-5-FP8"
|
|
schema_version: 1
|
|
sha256: "accee265bcf5788d"
|
|
---
|
|
|
|
# Documentation: EnumDescriptionTypeConverterShared
|
|
|
|
## 1. Purpose
|
|
This module provides a custom type converter, `EnumDescriptionTypeConverterShared`, designed to enhance the display of enumeration values in user interfaces (specifically WPF, per source comments). It extends the standard `EnumConverter` to return the value of a `[Description]` attribute applied to an enum member instead of the member's raw string name. Additionally, it integrates with the application's localization resources (`StringResources`) to support translated descriptions, falling back to the literal description text or the enum name when necessary.
|
|
|
|
## 2. Public Interface
|
|
|
|
### Class: `DTS.Common.Converters.EnumDescriptionTypeConverterShared`
|
|
Inherits from: `System.ComponentModel.EnumConverter`
|
|
|
|
#### `public EnumDescriptionTypeConverterShared(Type type)`
|
|
**Signature:** `ctor(Type type)`
|
|
**Description:** Initializes a new instance of the converter for the specified enum `type`. It delegates construction to the base `EnumConverter` class.
|
|
|
|
#### `public override object ConvertTo(ITypeDescriptorContext context, CultureInfo culture, object value, Type destinationType)`
|
|
**Signature:** `ConvertTo(ITypeDescriptorContext, CultureInfo, object, Type) -> object`
|
|
**Description:** Converts the given `value` (expected to be an enum) to the specified `destinationType`.
|
|
* If `destinationType` is not `string`, it delegates to `base.ConvertTo`.
|
|
* If `value` is `null` or the underlying field info cannot be found, it returns `string.Empty`.
|
|
* It retrieves the `DescriptionAttribute` from the enum field.
|
|
* If the attribute exists, it attempts to look up the description string in `StringResources.ResourceManager`.
|
|
* If the lookup fails (returns null/whitespace), it returns the literal `Description` value.
|
|
* If no attribute exists, it returns `value.ToString()` (the enum name).
|
|
|
|
#### `public static string GetEnumDescription(Enum value)`
|
|
**Signature:** `GetEnumDescription(Enum) -> string`
|
|
**Description:** A static utility method that retrieves the display string for an enum value using the same logic as `ConvertTo`.
|
|
* It reflects the field info for the `value`.
|
|
* It looks for a `DescriptionAttribute`.
|
|
* If found, it attempts to resolve the description via `StringResources.ResourceManager`.
|
|
* Returns the localized string, the literal description, or the enum's `ToString()` value as fallbacks.
|
|
|
|
## 3. Invariants
|
|
* **Input Type:** The `ConvertTo` method expects the `value` parameter to be an instance of the Enum type the converter was instantiated with, though it handles `null` gracefully.
|
|
* **Return Type:** `ConvertTo` guarantees a `string` return type when `destinationType` is `string`; otherwise, it returns the result of the base converter.
|
|
* **Attribute Lookup:** The code assumes the `Description` property of the `DescriptionAttribute` serves a dual purpose: it acts as the fallback display text *and* the resource key for `StringResources`.
|
|
* **Null Safety (Instance Method):** `ConvertTo` explicitly checks if `value` is `null` and returns `string.Empty`.
|
|
* **Null Safety (Static Method):** `GetEnumDescription` does **not** check if `value` is `null` before calling `value.GetType()`; passing `null` to this static method will result in a `NullReferenceException`.
|
|
|
|
## 4. Dependencies
|
|
* **Internal Dependencies:**
|
|
* `DTS.Common.SharedResource.Strings.StringResources`: Used to resolve localized strings via its `ResourceManager`.
|
|
* **External Dependencies:**
|
|
* `System.ComponentModel`: Provides `EnumConverter`, `DescriptionAttribute`, and `ITypeDescriptorContext`.
|
|
* `System.Globalization`: Provides `CultureInfo`.
|
|
* `System.Reflection`: Used implicitly via `GetField` and `GetCustomAttributes`.
|
|
* `System.Linq`: Used for `Enumerable.Any()`.
|
|
|
|
## 5. Gotchas
|
|
* **Static Method Null Handling:** Unlike the instance method `ConvertTo`, the static helper `GetEnumDescription` lacks a null check for the `value` parameter. Calling `GetEnumDescription(null)` will throw a `NullReferenceException`.
|
|
* **Resource Key Collision:** The logic treats the `DescriptionAttribute` value as a resource key first. If a developer adds a description like "ID" (intending it as text) but "ID" exists as a key in `StringResources` with a different translation (e.g., "Identifier"), the output will be the translated resource, not the literal "ID".
|
|
* **Performance:** Both `ConvertTo` and `GetEnumDescription` rely on reflection (`GetField`, `GetCustomAttributes`) on every call. In UI scenarios where this converter is bound to large lists or called frequently, this may introduce performance overhead compared to caching the attribute values.
|
|
* **Missing Field Info:** In `ConvertTo`, if `value.GetType().GetField(value.ToString())` returns null (which can happen with flag combinations not explicitly defined in the enum), the method returns `string.Empty` rather than the numeric value or enum name. |