---
source_files:
  - Common/DTS.CommonCore/Interface/ISO/ExtraProperties/IExtraPropertiesListView.cs
  - Common/DTS.CommonCore/Interface/ISO/ExtraProperties/IExtraPropertiesListViewModel.cs
  - Common/DTS.CommonCore/Interface/ISO/ExtraProperties/IExtraProperty.cs
generated_at: "2026-04-16T02:31:01.486440+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "785426dcfee2c243"
---

# ExtraProperties

## 1. Purpose  
This module defines the core interfaces for managing a list of *extra properties*—custom key-value metadata associated with ISO-compliant data objects—in a WPF-based UI layer. It establishes a clean separation between view (`IExtraPropertiesListView`), view model (`IExtraPropertiesListViewModel`), and individual property data (`IExtraProperty`) to support data binding, editing, validation, and user interactions (copy, delete, sort, filter, paste) in a structured, testable manner. The module exists to abstract the UI logic for handling dynamic, user-defined properties while enforcing consistency with the broader `DTS.Common` architecture.

## 2. Public Interface  

### `IExtraPropertiesListView`  
- **Inherits**: `IBaseView`  
- **Description**: A marker interface for the view (e.g., XAML user control) that renders the extra properties list. No additional members—behavior is entirely driven by the view model.

### `IExtraPropertiesListViewModel`  
- **Inherits**: `IBaseViewModel`  
- **Properties**:  
  - `IExtraPropertiesListView View { get; set; }` — Binds to the associated view instance.  
  - `ObservableCollection<IExtraProperty> ExtraProperties { get; set; }` — The mutable collection of properties displayed/managed.  
  - `bool IsReadOnly { get; set; }` — Controls whether edits are permitted.  
  - `IExtraProperty[] SelectedProperties { get; }` — Returns currently selected items in the UI (read-only snapshot).  
- **Methods**:  
  - `void SetPage(IDataPROPage page)` — Associates the view model with a specific data page context (likely for persistence or scoping).  
  - `void SetParent(object parent)` — Sets a parent object (e.g., containing entity), though its exact use is not specified in the interface.  
  - `void SetExtraProperties(IList<IExtraProperty> properties)` — Replaces the current `ExtraProperties` collection with a new list.  
  - `void CopySelected()` — Copies selected properties (likely to clipboard or internal buffer).  
  - `void DeleteSelected()` — Removes selected properties from `ExtraProperties`.  
  - `void Filter(object tag, string term)` — Filters the displayed properties based on a search term (`term`) and optional `tag` (e.g., column or field identifier).  
  - `void Sort(object o, bool columnClick)` — Sorts the properties, where `o` likely identifies the sort key/column and `columnClick` indicates whether the sort was triggered by UI interaction.  
  - `bool Validate(ref List<string> errors)` — Validates all properties in `ExtraProperties`; returns `false` and populates `errors` if any property fails validation.  

### `IExtraProperty`  
- **Inherits**: `INotifyPropertyChanged`  
- **Properties**:  
  - `string Key { get; set; }` — The property’s name/identifier.  
  - `string Value { get; set; }` — The property’s value.  
  - `UIItemStatus ItemStatus { get; set; }` — Current UI validation/status state (e.g., `Success`, `Failed`, `Warning`—values defined in `DTS.Common.Enums`).  
- **Commands**:  
  - `ICommand PasteCommand { get; set; }` — Handles paste operations, supporting multi-row pastes (e.g., CSV) into a single field.  

## 3. Invariants  
- `ExtraProperties` must be an `ObservableCollection<IExtraProperty>` to support UI data binding and change notifications.  
- `IsReadOnly` controls mutability: when `true`, operations like `DeleteSelected()` and edits to `Key`/`Value` should be disabled (enforced by the view or view model implementation).  
- `SelectedProperties` is a *snapshot* of the current selection at the time of access—its contents may change independently of the view model’s internal state.  
- `Validate(ref List<string> errors)` must populate `errors` with human-readable messages for *all* invalid properties, not just the first failure.  
- `PasteCommand` is expected to handle multi-line or multi-property pastes (e.g., pasting multiple rows into one cell), though the exact behavior is implementation-defined.  

## 4. Dependencies  
- **Depends on**:  
  - `DTS.Common.Base` (for `IBaseView`, `IBaseViewModel`)  
  - `DTS.Common.Enums` (for `UIItemStatus`)  
  - `System.Collections.ObjectModel` (for `ObservableCollection<T>`)  
  - `System.Windows.Input` (for `ICommand`)  
- **Depended on by**:  
  - Likely consumed by UI components (e.g., `UserControl` implementing `IExtraPropertiesListView`) and higher-level view models managing ISO data pages (e.g., `IDataPROPage` implementations).  
  - `IDataPROPage` (referenced in `SetPage`) is assumed to be defined elsewhere in `DTS.Common.Base`.  

## 5. Gotchas  
- **Ambiguous `SetParent` usage**: The `object parent` parameter lacks type safety or documentation—implementers must infer its role (e.g., parent entity, container, or context object).  
- **`Filter`/`Sort` signature ambiguity**: The `object tag` and `object o` parameters in `Filter` and `Sort` are untyped; their expected types (e.g., `string`, `int`, or custom enum) are not specified.  
- **`SelectedProperties` is read-only**: The array is not live-updated; consumers must re-query after selection changes.  
- **No explicit thread-safety guarantees**: `ObservableCollection` is not thread-safe; modifications must occur on the UI thread (standard WPF constraint).  
- **`PasteCommand` behavior is underspecified**: While documented as handling multi-row pastes, the interface does not define how pasted data is parsed or distributed (e.g., row/column splitting).  
- **No event for selection changes**: The interface lacks a `SelectedPropertiesChanged` event—consumers must rely on external mechanisms (e.g., binding to `ICollectionView.SelectionChanged`).  

*None identified beyond the above.*