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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.Utilities/Properties/AssemblyInfo.cs Common/DTS.Common.Utilities/Properties/Resources.Designer.cs	2026-04-16T02:11:44.723608+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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.