init

enriched-qwen3-coder-next/Common/DTS.CommonCore/Classes/ISO/ExtraProperties.md

@@ -0,0 +1,51 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Classes/ISO/ExtraProperties/TextPastedArgs.cs
+generated_at: "2026-04-16T02:41:57.941514+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "0e778602f67f4f38"
+---
+
+# ExtraProperties
+
+### 1. Purpose  
+`TextPastedArgs` is a concrete implementation of the `ITextPastedEventArgs` interface, used to encapsulate event data for text-paste operations within the ISO Extra Properties subsystem. It carries contextual information—including the pasted text, the originating `IExtraProperty` instance (as `Sender`), a unique identifier (`Id`), and an arbitrary user-defined object (`Tag`)—to event handlers subscribed to text-paste events. This class enables decoupled communication between components that trigger text paste actions and those that consume or react to them.
+
+### 2. Public Interface  
+- **`TextPastedArgs(string text, IExtraProperty extraProperty, string id, object tag)`**  
+  Constructor initializing all properties. Assigns `text` to `Text`, `extraProperty` to `Sender`, `id` to `Id`, and `tag` to `Tag`. All assignments are direct and unvalidated (no null checks or transformations are performed in the constructor).
+
+- **`string Text { get; }`**  
+  Read-only property containing the text that was pasted. Value is set at construction and immutable thereafter.
+
+- **`object Sender { get; }`**  
+  Read-only property referencing the `IExtraProperty` instance that triggered the paste event. Stored as `object` (not strongly typed) per interface contract.
+
+- **`string Id { get; }`**  
+  Read-only property holding a string identifier associated with the paste operation. Likely used to correlate events or identify the source property.
+
+- **`object Tag { get; }`**  
+  Read-only property for attaching arbitrary user-defined state or metadata to the event. Can be `null`.
+
+### 3. Invariants  
+- `Text`, `Sender`, `Id`, and `Tag` are immutable after construction (no setters beyond initialization).
+- `Sender` is *intended* to hold an instance implementing `IExtraProperty`, though the property type is `object`, allowing non-conforming values if passed incorrectly.
+- No validation is enforced on input arguments (e.g., `text` or `id` may be `null` or empty; `extraProperty` may be `null`).
+- The class itself is not thread-safe; concurrent access to instances is not guaranteed safe.
+
+### 4. Dependencies  
+- **Depends on**:  
+  - `System` (core types: `string`, `object`, `EventArgs` implied via interface)  
+  - `DTS.Common.Events` (likely contains `ITextPastedEventArgs` definition)  
+  - `DTS.Common.Interface.ISO.ExtraProperties` (contains `IExtraProperty` interface)  
+- **Depended on by**:  
+  - Event publishers/consumers in the ISO Extra Properties subsystem that raise or handle `TextPasted` events (e.g., UI components or property editors invoking paste operations).  
+  - Any code expecting an `ITextPastedEventArgs` implementation (e.g., event handlers with signature `void OnTextPasted(object sender, ITextPastedEventArgs e)`).
+
+### 5. Gotchas  
+- `Sender` is stored as `object` despite being initialized from an `IExtraProperty`; callers must cast it back to `IExtraProperty` to access its members, risking `InvalidCastException` if misused.  
+- No null-safety: passing `null` for `text`, `extraProperty`, `id`, or `tag` is permitted and will result in `null` property values—handlers must defensively check for null.  
+- The `Id` and `Tag` parameters are not validated for uniqueness or type; misuse (e.g., passing mutable objects as `Tag`) could lead to unexpected side effects.  
+- The class name `TextPastedArgs` (with past-tense "Pasted") may be inconsistent with naming conventions (e.g., `TextPasteEventArgs`), potentially causing confusion during discovery or search.  
+- No documentation comments are present in the source; behavioral assumptions (e.g., semantics of `Id` or `Tag`) are inferred solely from usage context.