init

enriched-qwen3-coder-next/Common/DTS.Common.Utilities/Properties.md

@@ -0,0 +1,124 @@
+---
+source_files:
+  - Common/DTS.Common.Utilities/Properties/AssemblyInfo.cs
+  - Common/DTS.Common.Utilities/Properties/Resources.Designer.cs
+generated_at: "2026-04-16T02:11:44.723608+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "350fbb2a7eb1ba61"
+---
+
+# DTS.Common.Utilities Module Documentation
+
+## 1. Purpose
+
+This module provides foundational utility types and services for the DTS application ecosystem, specifically focusing on logging infrastructure (`APILogger`, `TextLogger`), strongly-typed resource management for localized strings, and property validation helpers (e.g., `PowerOfTwoProperty`, `RangeRestrictedIntProperty`, `RangeRestrictedDoubleProperty`). It serves as a shared dependency for other DTS components, centralizing cross-cutting concerns such as exception formatting, attribute-based serialization/deserialization (`AttributeCoder`), and runtime validation of numeric and configuration properties. The module does not contain business logic but enables consistent behavior and error reporting across the broader system.
+
+## 2. Public Interface
+
+The source files provided contain **no public classes, methods, or properties**—only internal implementation details and auto-generated resource classes. The `AssemblyInfo.cs` file defines assembly-level metadata, and `Resources.Designer.cs` defines an `internal` strongly-typed resource class (`Resources`) with only `internal` properties.
+
+However, based on the *names* and *structure* of the resource strings, the following public APIs are *inferred* to exist elsewhere in the assembly (but are **not present in the provided source**):
+
+- `APILogger.LogString(string message, Action<string> writer)`  
+  *Inferred from:* `APILogging_NullWriterDelegateString`, `APILogging_LogException_NullWriterDelegateString`  
+  *Behavior:* Logs a string message using a provided writer delegate; throws if writer is null.
+
+- `APILogger.LogException(Exception ex, Action<string> writer)`  
+  *Inferred from:* `APILogging_LogException_NullWriterDelegateString`  
+  *Behavior:* Logs an exception using a formatted message; throws if writer is null.
+
+- `AttributeCoder.EncodeAttribute<TAttribute>(object value)`  
+  *Inferred from:* `AttributeCoder_EncodeAttributeExceptionString`, `AttributeCoder_DecodeAttributeExceptionString`, etc.  
+  *Behavior:* Encodes an object into an attribute value string; throws on failure.
+
+- `AttributeCoder.DecodeAttribute<TAttribute>(string encodedValue)`  
+  *Inferred from:* `AttributeCoder_DecodeAttributeExceptionString`, `AttributeCoder_DehashAttributeValue_UnableToMatchAttributeValueWithTargetString`, etc.  
+  *Behavior:* Decodes an encoded string into a strongly-typed value; throws on failure.
+
+- `PowerOfTwoProperty` (class)  
+  *Inferred from:* `PowerOfTwoProperty_IsPowerOf2_UnableToDeterminePowerOf2nessString`, `PowerOfTwoProperty_GetInvalidValueDescription_ProposedValueIsNotPowerOf2String`  
+  *Behavior:* Validates that a value is a power of two; provides descriptive error messages.
+
+- `RangeRestrictedIntProperty` (class)  
+  *Inferred from:* `RangeRestrictedIntProperty_IsValidValue_UnableToDetermineValidityString`, `RangeRestrictedIntProperty_MinMustBeLessThanMaxString`, etc.  
+  *Behavior:* Validates integer values against configurable min/max bounds.
+
+- `RangeRestrictedDoubleProperty` (class)  
+  *Inferred from:* `RangeRestrictedDoubleProperty_IsValidValue_UnableToDetermineValidityString`, `RangeRestrictedDoubleProperty_MinMustBeLessThanMaxString`, etc.  
+  *Behavior:* Validates double values against configurable min/max bounds.
+
+- `TextLogger` (class)  
+  *Inferred from:* `TextLogger_Start_NullEmptyFilenameString`, `TextLogger_AddMessage_LoggerNotRunningString`, etc.  
+  *Behavior:* A file-based logger with a dedicated write thread; supports `Start`, `Stop`, `AddMessage`, and disposal.
+
+> ⚠️ **Note:** None of the above APIs appear in the provided source files. This list is inferred solely from the resource string keys. Actual signatures and behaviors must be verified in the corresponding `.cs` files (not included here).
+
+## 3. Invariants
+
+The source files themselves do not define runtime invariants, but the *resource strings* imply the following constraints:
+
+- `TextLogger` must be started before `AddMessage`, `Stop`, or `Dispose` can succeed.  
+  *Evidence:* `TextLogger_AddMessage_LoggerNotRunningString`, `TextLogger_Stop_LoggerNotRunningString`.
+
+- `TextLogger.Start` requires non-null/non-empty `folder` and `filename` parameters.  
+  *Evidence:* `TextLogger_Start_NullEmptyFolderString`, `TextLogger_Start_NullEmptyFilenameString`.
+
+- `TextLogger` constructor requires a non-null callback delegate.  
+  *Evidence:* `TextLogger_TextLogger_NullCallbackString`.
+
+- `APILogger.LogString` and `APILogger.LogException` require non-null writer delegates.  
+  *Evidence:* `APILogging_NullWriterDelegateString`, `APILogging_LogException_NullWriterDelegateString`.
+
+- `AttributeCoder` operations require valid attribute metadata and target type mappings.  
+  *Evidence:* `AttributeCoder_AttributeCoder_NullAttributeValueExtractionMethodReferenceString`, `AttributeCoder_UnableToFindTargetTypeMappingString`.
+
+- `RangeRestricted*Property` classes enforce `Minimum ≤ Maximum`.  
+  *Evidence:* `RangeRestrictedIntProperty_MinMustBeLessThanMaxString`, `RangeRestrictedDoubleProperty_MinMustBeLessThanMaxString`.
+
+- `PowerOfTwoProperty` validates that values are powers of two.  
+  *Evidence:* `PowerOfTwoProperty_GetInvalidValueDescription_ProposedValueIsNotPowerOf2String`.
+
+## 4. Dependencies
+
+- **.NET Framework Runtime**:  
+  Uses `System.Resources`, `System.CodeDom.Compiler`, `System.Diagnostics`, `System.Runtime.CompilerServices`, `System.ComponentModel`.  
+  *Evidence:* Attributes and types in `AssemblyInfo.cs` and `Resources.Designer.cs`.
+
+- **Strongly-Typed Resource Infrastructure**:  
+  Relies on `System.Resources.ResourceManager` and `System.Globalization.CultureInfo`.  
+  *Evidence:* `Resources.ResourceManager` property and `Culture` setter.
+
+- **Inferred Dependencies (from resource strings)**:  
+  - `System.Configuration` (for `ApplicationSettings`, `DataPRO.exe.config` references).  
+  - `System.IO` (for file logging in `TextLogger`).  
+  - `System.Threading` (for `TextLogger` write thread management).  
+  - Reflection (`System.Reflection`) for `AttributeCoder`.
+
+- **Depended upon by**:  
+  Unknown from source alone. The assembly name `DTS.Common.Utilities` and namespace `DTS.Common.Utilities.Properties` suggest it is a shared library consumed by other DTS modules (e.g., `DataPRO.exe`).
+
+## 5. Gotchas
+
+- **Auto-generated Resource Class**:  
+  `Resources.Designer.cs` is auto-generated. Manual edits will be overwritten. Resource strings (e.g., `APILogging_DateTime_Format`) are localized and may vary by culture—ensure `Culture` is set appropriately before lookups.
+
+- **Internal API Surface**:  
+  The only public surface in the provided files is `Resources` (internal) and assembly attributes. No public APIs are exposed here—actual functionality resides in other files not included.
+
+- **Thread Safety of `TextLogger`**:  
+  Resource strings imply a dedicated write thread with explicit start/stop lifecycle management. Failure to call `Start` before `AddMessage` or `Stop` will cause exceptions. Thread synchronization issues may occur if `Start`/`Stop`/`Dispose` are called concurrently.
+
+- **Exception Handling in `AttributeCoder`**:  
+  Multiple exception strings (`AttributeCoder_*ExceptionString`) indicate that encoding/decoding/dehashing can fail at multiple stages. Callers must handle exceptions for invalid type mappings, missing attributes, or malformed data.
+
+- **Power-of-Two Validation Edge Cases**:  
+  The string `PowerOfTwoProperty_IsPowerOf2_UnableToDeterminePowerOf2nessString` suggests that determination may fail for certain values (e.g., very large integers, negative numbers, or non-integer doubles). Clarify expected behavior for edge cases.
+
+- **Null Handling**:  
+  `Generic_NullIndicatorString` (`"<null>"`) is used for display, but `Property_Value_NotInitializedString` (`"property has not been initialized."`) implies that uninitialized properties are distinct from null values.
+
+- **No Public API Documentation in Source**:  
+  The provided files contain no XML comments or public signatures. All functional behavior must be inferred from resource strings and external code.
+
+> **None identified from source alone** for public APIs—only implementation details (e.g., auto-generation, threading assumptions) are evident.