init
This commit is contained in:
145
docs/ai/Common/DTS.Common/Base/Classes.md
Normal file
145
docs/ai/Common/DTS.Common/Base/Classes.md
Normal file
@@ -0,0 +1,145 @@
|
||||
---
|
||||
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<T>` | `protected bool SetProperty<T>(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<T>` | `public bool SetProperty<T>(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<T>(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<Attribute>` - modifiable list of attributes. |
|
||||
| `IsBrowsable`, `IsReadOnly`, `DisplayName`, `Description`, `Category` | Overridable metadata values. |
|
||||
|
||||
#### Methods
|
||||
| Signature | Description |
|
||||
|-----------|-------------|
|
||||
| `public void RemoveAttributesOfType<T>()` | 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<T>` 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
|
||||
Reference in New Issue
Block a user