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

---
source_files:
  - Common/DTS.Common/Attributes/VersionAttribute.cs
  - Common/DTS.Common/Attributes/DisplayAttributeEx.cs
  - Common/DTS.Common/Attributes/DescriptionAttributeEx.cs
  - Common/DTS.Common/Attributes/ProgrammableTriggerAttributes.cs
generated_at: "2026-04-16T02:54:29.459111+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "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.