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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.SharedResource/EnumDescriptionTypeConverterShared.cs	2026-04-16T14:09:08.524631+00:00	zai-org/GLM-5-FP8	1	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.