init

docs/ai/Common/DTS.Common.Utilities/Properties.md

@@ -0,0 +1,182 @@
+---
+source_files:
+  - Common/DTS.Common.Utilities/Properties/AssemblyInfo.cs
+  - Common/DTS.Common.Utilities/Properties/Resources.Designer.cs
+generated_at: "2026-04-17T15:41:14.355961+00:00"
+model: "zai-org/GLM-5-FP8"
+schema_version: 1
+sha256: "b85bddefb00e1aef"
+---
+
+# DTS.Common.Utilities Documentation
+
+## 1. Purpose
+
+This module serves as a common utilities library for the DTS system, providing shared infrastructure for logging, property validation, attribute encoding/decoding, and exception handling. It exists to centralize reusable components that support other DTS applications, including configuration management and diagnostic capabilities. The assembly version is 1.0.0.0, with copyright from 2008.
+
+---
+
+## 2. Public Interface
+
+### Resources Class (Internal)
+**Namespace:** `DTS.Common.Utilities.Properties`
+
+**Signature:**
+```csharp
+internal class Resources
+```
+
+A strongly-typed resource class generated by `StronglyTypedResourceBuilder` for looking up localized strings.
+
+#### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `ResourceManager` | `global::System.Resources.ResourceManager` | Returns the cached ResourceManager instance used by this class. Initialized with base name `"DTS.Utilities.Properties.Resources"`. |
+| `Culture` | `global::System.Globalization.CultureInfo` | Overrides the current thread's CurrentUICulture for resource lookups. |
+
+#### Resource String Properties (Static Getters)
+
+The following static string properties are exposed for use by other components in the assembly:
+
+**APILogger Resources:**
+- `APILogging_DateTime_Format` — Format string `"yyyy-MM-dd HH:mm:ss.fff"`
+- `APILogging_ExceptionFormatter_ExceptionOfTypeOccurredString` — Format `"{0}An {1}exception of type: {2} occurred"`
+- `APILogging_ExceptionFormatter_InnerIndicationString` — `"inner "`
+- `APILogging_ExceptionFormatter_NonInnerIndicationString` — Empty string
+- `APILogging_ExceptionMessageDisplayString` — Format `"{0}Message: {1}"`
+- `APILogging_LevelSeperatorString` — `"=== "`
+- `APILogging_LogEntrySeperatorString` — Separator line `" ========================================"`
+- `APILogging_LogException_NullWriterDelegateString` — Error message for null writer delegate
+- `APILogging_LogString_NullWriterDelegateString` — Error message for null writer delegate
+- `APILogging_ModuleNameDisplayString` — Format `" {0}Module: {1}, Name: {2}"`
+- `APILogging_StackTraceDisplayString` — Format `" {0}StackTrace: {1}"`
+
+**AttributeCoder Resources:**
+- `AttributeCoder_AttributeCoder_NullAttributeValueExtractionMethodReferenceString`
+- `AttributeCoder_DecodeAttributeExceptionString`
+- `AttributeCoder_DecodeAttributesExceptionString`
+- `AttributeCoder_DehashAttributeValue_DehashAttributeValueExceptionString`
+- `AttributeCoder_DehashAttributeValue_UnableToMatchAttributeValueWithTargetString`
+- `AttributeCoder_EncodeAttributeExceptionString`
+- `AttributeCoder_NoTypeAttributesFoundOnTargetString`
+- `AttributeCoder_UnableToFindTargetTypeMappingString`
+
+**Exceptional Resources:**
+- `Exceptional_GenerateMessageFromExceptionTree_BecauseString` — `" because"`
+- `Exceptional_GenerateMessageFromExceptionTree_EndsWithFormatString` — Format `"{0}{1}"`
+- `Exceptional_GenerateMessageFromExceptionTree_ErrorTextTerminatorString` — `"."`
+- `Exceptional_GenerateMessageFromExceptionTree_MessageFormatString` — Format `"{0}{1}{2}"`
+
+**Property Validation Resources:**
+- `PowerOfTwoProperty_GetInvalidValueDescription_ProposedValueIsNotPowerOf2String`
+- `PowerOfTwoProperty_GetInvalidValueDescription_UnableToGetDescriptionString`
+- `PowerOfTwoProperty_IsPowerOf2_UnableToDeterminePowerOf2nessString`
+- `PowerOfTwoProperty_IsValidValue_UnableToDetermineValidityString`
+- `Property_GetInvalidValueDescription_CouldNotSetToValueString`
+- `Property_GetInvalidValueDescription_GetDescriptionFailedString`
+- `Property_Value_CouldNotGetValueString`
+- `Property_Value_CouldNotSetValueString`
+- `Property_Value_NotInitializedString`
+
+**RangeRestrictedDoubleProperty Resources:**
+- `RangeRestrictedDoubleProperty_GetInvalidValueDescription_GetDescriptionFailedString`
+- `RangeRestrictedDoubleProperty_GetInvalidValueDescription_MaximumDescriptionString`
+- `RangeRestrictedDoubleProperty_GetInvalidValueDescription_MinimumDescriptionString`
+- `RangeRestrictedDoubleProperty_GetInvalidValueDescription_ValidValueDescriptionString`
+- `RangeRestrictedDoubleProperty_IsValidValue_UnableToDetermineValidityString`
+- `RangeRestrictedDoubleProperty_MaximumValue_GetValueFailedString`
+- `RangeRestrictedDoubleProperty_MaximumValue_SetValueFailedString`
+- `RangeRestrictedDoubleProperty_MinimumValue_GetValueFailedString`
+- `RangeRestrictedDoubleProperty_MinimumValue_SetValueFailedString`
+- `RangeRestrictedDoubleProperty_MinMustBeLessThanMaxString`
+
+**RangeRestrictedIntProperty Resources:**
+- `RangeRestrictedIntProperty_GetInvalidValueDescription_GetDescriptionFailedString`
+- `RangeRestrictedIntProperty_GetInvalidValueDescription_MaximumDescriptionString`
+- `RangeRestrictedIntProperty_GetInvalidValueDescription_MinimumDescriptionString`
+- `RangeRestrictedIntProperty_GetInvalidValueDescription_ValidValueDescriptionString`
+- `RangeRestrictedIntProperty_IsValidValue_UnableToDetermineValidityString`
+- `RangeRestrictedIntProperty_MaximumValue_GetValueFailedString`
+- `RangeRestrictedIntProperty_MaximumValue_SetValueFailedString`
+- `RangeRestrictedIntProperty_MinimumValue_GetValueFailedString`
+- `RangeRestrictedIntProperty_MinimumValue_SetValueFailedString`
+- `RangeRestrictedIntProperty_MinMustBeLessThanMaxString`
+
+**TextLogger Resources:**
+- `TextLogger_AddMessage_LoggerNotRunningString`
+- `TextLogger_Dispose_WriteThreadExitFailureString`
+- `TextLogger_Dispose_WriteThreadResponseTimeoutString`
+- `TextLogger_Start_LoggerAlreadyRunningString`
+- `TextLogger_Start_NullEmptyFilenameString`
+- `TextLogger_Start_NullEmptyFolderString`
+- `TextLogger_Start_WriteThreadResponseTimeoutString`
+- `TextLogger_Start_WriteThreadStartFailureString`
+- `TextLogger_Stop_LoggerNotRunningString`
+- `TextLogger_Stop_WriteThreadResponseTimeoutString`
+- `TextLogger_Stop_WriteThreadStopFailureString`
+- `TextLogger_TextLogger_EnqueueWriterFailureString`
+- `TextLogger_TextLogger_NullCallbackString`
+- `TextLogger_TextLogger_WriteThreadStartTimeoutString`
+- `TextLogger_Writer_InvalidCommandString`
+
+**Application Settings Resources:**
+- `ApplicationSettings` — `"applicationSettings"`
+- `RegistryDataPROExe` — `"DataPRO.exe"`
+- `NewSettingsCouldNotBeFound`
+- `NewSettingsCouldNotBeProcessed`
+
+**Generic Resources:**
+- `Generic_EncounteredProblemConstructingClassString`
+- `Generic_NullIndicatorString` — `"<null>"`
+
+---
+
+## 3. Invariants
+
+Based on the resource strings, the following invariants are enforced by components in this assembly:
+
+1. **TextLogger Lifecycle:** The logger must be started before adding messages or stopped, and must be stopped before starting again. Methods `Start()` and `Stop()` have mutual exclusion requirements.
+
+2. **TextLogger Parameters:** Folder and filename parameters to `Start()` cannot be null or blank.
+
+3. **TextLogger Callback:** The callback parameter in the constructor cannot be null.
+
+4. **Range-Restricted Properties:** Minimum value must be less than or equal to maximum value for both `RangeRestrictedDoubleProperty` and `RangeRestrictedIntProperty`.
+
+5. **PowerOfTwoProperty:** Values must be exact powers of two to be valid.
+
+6. **APILogger Writer Delegate:** Writer delegate must not be null when calling `LogException()` or `LogString()`.
+
+7. **AttributeCoder:** Attribute value extraction method reference cannot be null.
+
+---
+
+## 4. Dependencies
+
+### This Module Depends On:
+- `System.Reflection`
+- `System.Runtime.CompilerServices`
+- `System.Runtime.InteropServices`
+- `System.Resources` (for ResourceManager)
+- `System.Globalization` (for CultureInfo)
+- `System.CodeDom.Compiler`
+- `System.Diagnostics`
+- `System.ComponentModel`
+
+### What Depends On This Module:
+**Unclear from source alone.** The resource strings reference `DataPRO.exe` and `DataPRO.exe.config`, suggesting the DataPRO application is a consumer. The module appears designed as a general-purpose utilities library for DTS products.
+
+---
+
+## 5. Gotchas
+
+1. **Namespace Inconsistency:** The `ResourceManager` is initialized with base name `"DTS.Utilities.Properties.Resources"` (note: missing "Common."), while the class resides in `DTS.Common.Utilities.Properties`. This could cause runtime resource lookup failures if the .resx file location doesn't match.
+
+2. **Auto-Generated File Warning:** `Resources.Designer.cs` is auto-generated by a tool. Manual changes will be lost upon regeneration. The runtime version noted is `4.0.30319.42000` with generator version `17.0.0.0`.
+
+3. **COM Visibility:** The assembly has `ComVisible(false)`, meaning types are not visible to COM components by default.
+
+4. **Internal Visibility:** The `Resources` class is marked `internal`, so it's only accessible within this assembly, not to external consumers.
+
+5. **Historical Context:** The copyright date (2008) and the presence of thread-based logging (`TextLogger`) with explicit state management suggests this codebase predates modern async/await patterns and may use older threading models.