--- source_files: - Common/DTS.Common/Base/Classes/BaseUserControl.cs - Common/DTS.Common/Base/Classes/BasePropertyChanged.cs - Common/DTS.Common/Base/Classes/DisplayResourceAttribute.cs - Common/DTS.Common/Base/Classes/DescriptionResourceAttribute.cs - Common/DTS.Common/Base/Classes/DynamicTypeDescriptor.cs generated_at: "2026-04-17T15:36:38.292547+00:00" model: "zai-org/GLM-5-FP8" schema_version: 1 sha256: "584aa4e7cd1ac4ca" --- # Documentation: DTS.Common.Base Classes ## 1. Purpose This module provides foundational infrastructure for the DTS codebase, including: - **Property change notification base classes** (`BasePropertyChanged`, `BaseUserControl`) that implement the `INotifyPropertyChanged` pattern for data binding scenarios in both UI and non-UI contexts. - **Localizable attribute classes** (`DisplayResourceAttribute`, `DescriptionResourceAttribute`) that enable runtime resource lookup for property display names and descriptions, supporting internationalization. - **Dynamic type introspection** (`DynamicTypeDescriptor`) that enables runtime modification of type metadata, allowing dynamic addition/removal of properties and modification of attributes for scenarios like PropertyGrid customization. --- ## 2. Public Interface ### BaseUserControl (abstract class) **Namespace:** `DTS.Common.Base.Classes` **Inherits:** `System.Windows.Controls.UserControl` | Member | Signature | Description | |--------|-----------|-------------| | `PropertyChanged` | `event PropertyChangedEventHandler PropertyChanged` | Event raised when a property value changes. | | `SetProperty` | `protected bool SetProperty(ref T storage, T value, String propertyName = null)` | Sets the field value if different; returns `true` if changed, `false` if values are equal. Raises `PropertyChanged` on change. | | `OnPropertyChanged` | `protected void OnPropertyChanged(string propertyName = null)` | Raises the `PropertyChanged` event. | --- ### BasePropertyChanged (abstract class) **Namespace:** `DTS.Common.Base` **Implements:** `IBasePropertyChanged` (interface definition not provided in source) | Member | Signature | Description | |--------|-----------|-------------| | `PropertyChanged` | `public virtual event PropertyChangedEventHandler PropertyChanged` | Virtual event for property change notification. | | `SetProperty` | `public bool SetProperty(ref T storage, T value, String propertyName = null)` | Sets the field value if different; returns `true` if changed. Public visibility (unlike `BaseUserControl`). | | `OnPropertyChanged` | `public virtual void OnPropertyChanged(string propertyName = null)` | Virtual method to raise `PropertyChanged` event. | --- ### DisplayResourceAttribute **Namespace:** `DTS.Common.Base.Classes` **Inherits:** `System.ComponentModel.DisplayNameAttribute` | Member | Signature | Description | |--------|-----------|-------------| | Constructor | `public DisplayResourceAttribute(string resourceId)` | Initializes with a resource identifier to look up. | | `DisplayName` | `public override string DisplayName` | Looks up the localized string via `Strings.Strings.ResourceManager.GetString(_resourceId)`. Returns `"##ResourceNotFound##" + _resourceId` if not found. | --- ### DescriptionResourceAttribute **Namespace:** `DTS.Common.Base.Classes` **Inherits:** `System.ComponentModel.DescriptionAttribute` | Member | Signature | Description | |--------|-----------|-------------| | Constructor | `public DescriptionResourceAttribute(string resourceId)` | Initializes with a resource identifier to look up. | | `Description` | `public override string Description` | Looks up the localized string via `Strings.Strings.ResourceManager.GetString(_resourceId)`. Returns `"##DescriptionNotFound##" + _resourceId` if not found. | --- ### DynamicTypeDescriptor (sealed class) **Namespace:** `DTS.Common.Base.Classes` **Implements:** `System.ComponentModel.ICustomTypeDescriptor`, `System.ComponentModel.INotifyPropertyChanged` #### Constructors | Signature | Description | |-----------|-------------| | `public DynamicTypeDescriptor(Type type)` | Creates a descriptor for the specified type, extracting properties, attributes, editors, and events via `TypeDescriptor`. Throws `ArgumentNullException` if `type` is null. | #### Properties | Name | Type | Description | |------|------|-------------| | `Component` | `object` | The component instance this descriptor wraps (set via `FromComponent`). | | `ClassName` | `string` | Optional override for class name. | | `ComponentName` | `string` | Optional override for component name. | | `OriginalProperties` | `PropertyDescriptorCollection` | Properties from the original type via `TypeDescriptor.GetProperties(type)`. | | `Properties` | `PropertyDescriptorCollection` | Modifiable collection of properties (excludes non-browsable by default). | #### Public Methods | Signature | Description | |-----------|-------------| | `public T GetPropertyValue(string name, T defaultValue)` | Gets a property value by name, returning `defaultValue` if not found or on conversion failure. | | `public void SetPropertyValue(string name, object value)` | Sets a property value by name. | | `public PropertyDescriptor AddProperty(Type type, string name, object value, string displayName, string description, string category, bool hasDefaultValue, object defaultValue, bool readOnly)` | Adds a new dynamic property. | | `public PropertyDescriptor AddProperty(..., Type uiTypeEditor)` | Adds a new dynamic property with a UI type editor. | | `public void AddProperty(PropertyDescriptor property)` | Adds an existing `PropertyDescriptor` to the `Properties` collection. | | `public void RemoveProperty(string name)` | Removes all properties matching the given name. | | `public DynamicTypeDescriptor FromComponent(object component)` | Creates a new `DynamicTypeDescriptor` bound to a specific component instance. Throws if component type is not assignable to `_type`. | #### Events | Member | Description | |--------|-------------| | `public event PropertyChangedEventHandler PropertyChanged` | Raised when a property value changes via `DynamicProperty.SetValue`. | --- ### DynamicTypeDescriptor.DynamicProperty (sealed class) **Namespace:** `DTS.Common.Base.Classes.DynamicTypeDescriptor` **Inherits:** `System.ComponentModel.PropertyDescriptor` **Implements:** `System.ComponentModel.INotifyPropertyChanged` #### Properties | Name | Description | |------|-------------| | `Value` | The property value (used when no existing `PropertyDescriptor` is wrapped). | | `AttributesList` | `IList` - modifiable list of attributes. | | `IsBrowsable`, `IsReadOnly`, `DisplayName`, `Description`, `Category` | Overridable metadata values. | #### Methods | Signature | Description | |-----------|-------------| | `public void RemoveAttributesOfType()` | Removes all attributes of type `T` from the property. | | `public void SetBrowsable(bool browsable)` | Overrides the `IsBrowsable` value. | | `public void SetIsReadOnly(bool readOnly)` | Overrides the `IsReadOnly` value. | | `public void SetDisplayName(string displayName)` | Overrides the `DisplayName` value. | | `public void SetDescription(string description)` | Overrides the `Description` value. | | `public void SetCategory(string category)` | Overrides the `Category` value. | | `public void SetEditor(Type editorBaseType, object obj)` | Sets or removes a custom editor for this property. | --- ## 3. Invariants ### BaseUserControl / BasePropertyChanged - `SetProperty` uses `Equals(storage, value)` for equality comparison; if values are equal, no event is raised and the method returns `false`. - `propertyName` parameter defaults to `null`; caller is responsible for passing the correct property name (no `CallerMemberName` usage observed). ### DisplayResourceAttribute / DescriptionResourceAttribute - The `_resourceId` field is stored but never validated for null/empty at construction time. - Resource lookup is performed on every access to `DisplayName`/`Description` (no caching observed). - Failure to find a resource results in a fallback string prefixed with `##ResourceNotFound##` or `##DescriptionNotFound##`. ### Dynamic