DP44/enriched-qwen3-coder-next/DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Utilities.md

---
source_files:
  - DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Utilities/DiskUtility.cs
  - DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Utilities/Exceptional.cs
  - DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Utilities/ExceptionalList.cs
  - DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Utilities/AttributeCoder.cs
generated_at: "2026-04-16T04:58:12.148784+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "290a5af10b3d9412"
---

# Documentation: `DatabaseExport.Utilities` Module

## 1. Purpose  
This module provides foundational utilities for the `DatabaseExport` subsystem, specifically supporting attribute-based encoding/decoding of enum values and basic file/path name validation. It enables a consistent pattern for associating metadata (attributes) with enum members and mapping between those metadata values and the enums themselves. The module also establishes a base class hierarchy (`Exceptional`, `ExceptionalList<T>`) for type-specific exception handling, allowing callers to catch exceptions by their originating class type. This module is part of a legacy codebase targeting database version 57 export functionality.

## 2. Public Interface  

### `DiskUtility`  
A static utility class for validating file and path names.

- **`ValidateFileAndPathNameChars(string nameToValidate)`**  
  - **Signature**: `public static bool ValidateFileAndPathNameChars(string nameToValidate)`  
  - **Behavior**: Returns `true` if `nameToValidate` contains no characters from `Path.GetInvalidFileNameChars()` or `Path.GetInvalidPathChars()`, has non-zero length after trimming, and does **not** contain a period (`.`). Returns `false` otherwise.  
  - **Note**: Explicitly rejects any string containing `.` (e.g., file extensions), beyond standard OS-invalid characters.

### `Exceptional`  
An abstract base class for enabling type-specific exception handling.

- **No public methods or properties**.  
- **Purpose**: Serves as a marker base class. Derived classes may define nested `Exception` types (as shown in the remarks), but the base class itself provides no runtime behavior beyond being serializable.

### `ExceptionalList<T>`  
A generic list class inheriting from `List<T>` for type-specific exception handling.

- **No public methods or properties beyond those inherited from `List<T>`**.  
- **Purpose**: Provides a base type that can be subclassed to define custom exception types (e.g., `MyList : ExceptionalList<int> { public class Exception : System.Exception { ... } }`), per the pattern described in the remarks.

### `AttributeCoder<TargetType, AttributeType, AttributeValueType>`  
A generic helper for mapping between enum values (`TargetType`), their associated attributes (`AttributeType`), and extracted values (`AttributeValueType`).

- **Delegates**:  
  - `AttributeValueExtractionMethod(AttributeType attribute) → AttributeValueType`  
    Defines how to extract an `AttributeValueType` from an `AttributeType` instance.  
  - `AttributeValueEqualityComparisonMethod(AttributeValueType, AttributeValueType) → bool`  
    Defines custom equality logic for `AttributeValueType`. If `null`, defaults to `Equals()`.

- **Constructors**:  
  - `AttributeCoder(AttributeValueExtractionMethod, AttributeValueEqualityComparisonMethod = null)`  
    Initializes the coder. Throws `Exception` if `attributeValueExtractionMethod` is `null`. Stores both delegates.

- **Methods**:  
  - **`DecodeAttributeValue(TargetType target) → AttributeValueType`**  
    Extracts the *single* `AttributeValueType` from the attribute attached to `target`.  
    - Internally calls `DecodeAttributeValues(target)` and asserts exactly one value exists.  
    - Throws `Exception` if no attributes found or if multiple attributes exist.  
  - **`DecodeAttributeValues(TargetType target) → List<AttributeValueType>`**  
    Extracts *all* `AttributeValueType`s from attributes of type `AttributeType` attached to `target`.  
    - Uses reflection: `target.GetType().GetField(target.ToString())` to get the `FieldInfo` of the enum field named by `target.ToString()`.  
    - Retrieves custom attributes of type `AttributeType` on that field.  
    - Applies `_extractAttributeValue` to each attribute to produce the list.  
  - **`EncodeAttributeValue(AttributeValueType attributeValue) → TargetType`**  
    Returns the *single* `TargetType` enum value whose attribute has `attributeValue`.  
    - Internally calls `DehashAttributeValue(attributeValue)` and asserts exactly one match.  
    - Throws `Exception` if zero or multiple matches.  
  - **`DehashAttributeValue(AttributeValueType attributeValue) → List<TargetType>`**  
    Returns *all* `TargetType` enum values whose attributes match `attributeValue`.  
    - Enumerates all values of `TargetType` via `Enum.GetValues(typeof(TargetType))`.  
    - For each, calls `DecodeAttributeValue(target)` and compares to `attributeValue` using either `_areAttributeValuesEqual` (if provided) or `Equals()`.  
    - Throws `Exception` if no matches found.

## 3. Invariants  

- **`DiskUtility.ValidateFileAndPathNameChars`**:  
  - A valid name must be non-empty after trimming, contain no invalid filename/path characters (per `Path.GetInvalidFileNameChars()`/`Path.GetInvalidPathChars()`), and contain no `.` characters.  
  - **Critical constraint**: The presence of `.` alone causes rejection, regardless of other validity.

- **`AttributeCoder`**:  
  - `DecodeAttributeValue` and `EncodeAttributeValue` assume *exactly one* attribute per enum field and *exactly one* enum field per attribute value, respectively. They throw if this is violated.  
  - `DecodeAttributeValues` and `DehashAttributeValue` do *not* assume uniqueness and return lists.  
  - `DecodeAttributeValues` relies on the `TargetType` being an `enum` and that `target.ToString()` yields a valid field name on the enum type.  
  - The `AttributeType` must be applied as a custom attribute on the enum *field* (not the value itself), and `GetField(target.ToString())` must succeed.  
  - `AttributeValueExtractionMethod` must be non-null; `AttributeValueEqualityComparisonMethod` may be `null` (defaults to `Equals`).

## 4. Dependencies  

### This module depends on:  
- `System.IO` (for `Path.GetInvalidFileNameChars()`, `Path.GetInvalidPathChars()`)  
- `System.Linq` (for `Cast<T>()`, `Where()`, `Select()`, `ToList()`)  
- `System.Diagnostics` (for `Debug.Assert`)  
- `System.Collections.Generic` (for `List<T>`)  
- `System` (for `Exception`, `SerializableAttribute`, `Enum`)  

### This module is depended upon by:  
- **Inferred**: Other modules in `DatabaseExport` (not visible here) likely use `AttributeCoder` to map between enums and metadata (e.g., database column types, export options).  
- `DiskUtility` is likely used by export logic that constructs file paths dynamically.  
- `Exceptional`/`ExceptionalList<T>` are base types; specific subclasses (not provided) are used throughout the codebase for typed exceptions.

## 5. Gotchas  

- **`DiskUtility.ValidateFileAndPathNameChars`**:  
  - The explicit ban on `.` is non-standard and may conflict with typical file naming conventions (e.g., `.txt`, `data.csv`). This is likely intentional to prevent extension confusion in internal naming, but is a critical constraint.  
  - Validation is case-sensitive for content (e.g., `..` is invalid, but `..` is not explicitly checked beyond `.` presence).  

- **`AttributeCoder`**:  
  - **Fragile reflection usage**: `target.GetType().GetField(target.ToString())` assumes the `TargetType` is an `enum` and that `ToString()` returns the exact field name. If `TargetType` is not an enum, or if custom `ToString()` overrides exist, this will fail.  
  - **No support for multiple attributes per field**: `DecodeAttributeValues` collects all attributes of `AttributeType`, but `DecodeAttributeValue` expects exactly one and throws otherwise.  
  - **Equality semantics**: If `_areAttributeValuesEqual` is `null`, `Equals()` is used. Value types (e.g., `int`, `string`) usually work, but reference types may require custom equality (e.g., for case-insensitive strings).  
  - **Exception messages are not localized**: Commented-out `Resources.*` strings indicate localization was intended but not implemented. All exceptions use hardcoded English strings.  
  - **No null-safety on `target`**: Passing `null` to `DecodeAttributeValue`/`DecodeAttributeValues` will throw `NullReferenceException` before reaching intended error handling.  
  - **`EncodeAttributeValue`/`DehashAttributeValue` are inverses only if the mapping is bijective**: If multiple enum values map to the same attribute value, `EncodeAttributeValue` will fail.  

- **`Exceptional`/`ExceptionalList<T>`**:  
  - These classes provide *no runtime behavior* beyond inheritance. Their utility relies on subclasses defining nested `Exception` types (as shown in remarks), which are not present in the provided source. Callers must infer usage from comments.  
  - `ExceptionalList<T>` adds no functionality beyond `List<T>`; it is only a marker for exception hierarchy.