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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common/Attributes/VersionAttribute.cs Common/DTS.Common/Attributes/DisplayAttributeEx.cs Common/DTS.Common/Attributes/DescriptionAttributeEx.cs Common/DTS.Common/Attributes/ProgrammableTriggerAttributes.cs	2026-04-16T02:54:29.459111+00:00	Qwen/Qwen3-Coder-Next-FP8	1	a6c138fea6a5740b

Documentation: DTS.Common.Attributes Module

1. Purpose

This module provides custom .NET attributes for enriching metadata on types and members (especially enums and properties) with versioning, localized display names, localized descriptions, and programmable trigger configuration. It enables consistent internationalization of UI-facing labels and descriptions via string resources, and supports declarative specification of trigger behavior (pre/post) for enum values—primarily used to annotate programmable trigger types in the system.

2. Public Interface

VersionAttribute

• Constructor: VersionAttribute(int version)
  Initializes the attribute with a specified integer version.
• Property: int Version { get; }
  Returns the version value passed to the constructor.

DisplayAttributeEx

• Constructor: DisplayAttributeEx(string propertyId)
  Stores propertyId for later lookup in string resources.
• Override: override string DisplayName { get; }
  Returns the localized display name by looking up propertyId + "_DisplayName" in StringResources.ResourceManager. If not found, returns "##DisplayNameNotFound##" + propertyId.

DescriptionAttributeEx

• Constructor: DescriptionAttributeEx(string propertyId)
  Stores propertyId for later lookup in string resources.
• Override: override string Description { get; }
  Returns the localized description by looking up propertyId + "_Description" in StringResources.ResourceManager. If not found, returns "##DescriptionNotFound##" + propertyId.

ProgrammableTriggersAttribute

• Constructor: ProgrammableTriggersAttribute(bool preTrigger, bool postTrigger)
  Initializes the attribute with flags indicating whether pre- and post-triggers are programmable.
• Properties:
  • bool PreTrigger { get; set; }
  • bool PostTrigger { get; set; }
• Static Methods:
  • static bool IsPreTriggerProgrammable(Enum value)
    Returns true if the PreTrigger flag is true on the attribute applied to the enum field corresponding to value; otherwise returns true by default (i.e., if no attribute is present).
  • static bool IsPostTriggerProgrammable(Enum value)
    Returns true if the PostTrigger flag is true on the attribute applied to the enum field corresponding to value; otherwise returns true by default.

3. Invariants

• DisplayAttributeEx and DescriptionAttributeEx require that string resources exist with keys formed as {propertyId}_DisplayName and {propertyId}_Description, respectively. If missing, fallback strings are returned (not thrown exceptions).
• ProgrammableTriggersAttribute is only applied to enum fields (not enum types themselves) in practice, as its static methods use value.GetType().GetField(value.ToString()) to retrieve the attribute.
• ProgrammableTriggersAttribute.IsPreTriggerProgrammable and IsPostTriggerProgrammable default to true if no attribute is present on the enum field.
• All attributes are intended for use on Class, Enum, Interface, Delegate, and Property targets (per [AttributeUsage(...)]).

4. Dependencies

• Internal Dependencies:
  • DTS.Common.SharedResource.Strings.StringResources (used by DisplayAttributeEx and DescriptionAttributeEx for localization).
• External Dependencies:
  • System, System.ComponentModel, System.Linq (standard .NET libraries).
• Consumers:
  • Presumably used throughout the codebase to annotate enums (e.g., trigger types) and properties for localization and metadata.
  • ProgrammableTriggersAttribute is likely used on enum fields to control trigger behavior logic elsewhere (e.g., in trigger configuration or execution modules).

5. Gotchas

• Default behavior in ProgrammableTriggersAttribute: If the attribute is not applied to an enum field, both IsPreTriggerProgrammable and IsPostTriggerProgrammable return true. This may be counterintuitive if the expectation is that absence implies false.
• String resource key construction: Keys are formed by appending "_DisplayName" or "_Description" to the propertyId passed to the constructor. Mismatched naming (e.g., missing underscore or suffix) will cause lookup failure.
• Case sensitivity: String resource lookup via ResourceManager.GetString(...) is case-sensitive; inconsistent casing in propertyId will cause fallback strings.
• Typo in justification: The SuppressMessage attributes for S3376 contain a typo ("extebded" instead of "extended"), but this is cosmetic and does not affect behavior.
• No validation in constructors: DisplayAttributeEx and DescriptionAttributeEx accept any string propertyId without validation; invalid or malformed IDs will simply fail to resolve at runtime.
• Thread-safety: Not addressed in source; assumes StringResources.ResourceManager is thread-safe (standard for .NET ResourceManager).
• Enum field lookup limitation: ProgrammableTriggersAttribute.Is*Programmable methods rely on value.ToString() to get the field name, which may fail or misbehave if the enum has [Flags] and value is a composite (bitwise OR) of multiple enum values.