74 lines
5.4 KiB
Markdown
74 lines
5.4 KiB
Markdown
---
|
|
source_files:
|
|
- Common/DTS.Common.Utilities/Properties/AssemblyInfo.cs
|
|
- Common/DTS.Common.Utilities/Properties/Resources.Designer.cs
|
|
generated_at: "2026-04-16T11:56:30.722696+00:00"
|
|
model: "zai-org/GLM-5-FP8"
|
|
schema_version: 1
|
|
sha256: "350fbb2a7eb1ba61"
|
|
---
|
|
|
|
# Documentation: DTS.Common.Utilities
|
|
|
|
## 1. Purpose
|
|
`DTS.Common.Utilities` is a class library intended to provide shared infrastructure and helper components for the DTS software ecosystem. Based on the assembly metadata and embedded resource strings, the library encapsulates cross-cutting concerns such as structured logging (specifically for APIs and text files), exception formatting, attribute-based encoding/decoding (potentially for serialization), and specialized property validation logic (range restriction and power-of-two validation). It also appears to manage configuration settings related to an application named "DataPRO".
|
|
|
|
## 2. Public Interface
|
|
|
|
The provided source files consist of assembly metadata and an auto-generated resource accessor. The actual implementation classes (e.g., `APILogger`, `TextLogger`) are not present in the source, but their existence and behavior can be inferred from the `Resources` class.
|
|
|
|
**Assembly Attributes**
|
|
* `AssemblyTitle`: "DTS.Common.Utilities"
|
|
* `AssemblyVersion`: "1.0.0.0"
|
|
* `ComVisible`: `false` (Types are not exposed to COM by default).
|
|
|
|
**Class: `DTS.Common.Utilities.Properties.Resources`**
|
|
This `internal` class provides strongly-typed access to localized string resources used throughout the library.
|
|
|
|
* **Properties**: The class exposes numerous `internal static string` properties. Key categories include:
|
|
* **Logging Configuration**:
|
|
* `APILogging_DateTime_Format`: Format string (e.g., "yyyy-MM-dd HH:mm:ss.fff").
|
|
* `APILogging_LogEntrySeperatorString`: Visual separator for log entries.
|
|
* **Error Messages**:
|
|
* `APILogging_LogException_NullWriterDelegateString`: Error for null writer delegate.
|
|
* `TextLogger_Start_NullEmptyFilenameString`: Validation error for logger initialization.
|
|
* `AttributeCoder_DecodeAttributeExceptionString`: Error for attribute decoding failures.
|
|
* **Validation Messages**:
|
|
* `RangeRestrictedDoubleProperty_MinMustBeLessThanMaxString`: Invariant error for range properties.
|
|
* `PowerOfTwoProperty_GetInvalidValueDescription_ProposedValueIsNotPowerOf2String`: Validation error.
|
|
|
|
**Inferred Components (Not in source, implied by resources)**
|
|
* `APILogger`: Likely a static or singleton class for logging exceptions and strings.
|
|
* `TextLogger`: A class managing a background writer thread for text logging. Implies methods `Start`, `Stop`, `AddMessage`, and `Dispose`.
|
|
* `AttributeCoder`: A class for encoding/decoding and "dehashing" attribute values.
|
|
* `RangeRestrictedDoubleProperty` / `RangeRestrictedIntProperty`: Classes or structures enforcing min/max value constraints.
|
|
* `PowerOfTwoProperty`: A class validating that values are powers of two.
|
|
|
|
## 3. Invariants
|
|
|
|
* **COM Visibility**: The assembly is marked `ComVisible(false)`. Types must explicitly opt-in to be visible to COM components.
|
|
* **Range Validation**: For `RangeRestrictedDoubleProperty` and `RangeRestrictedIntProperty`, the minimum value must always be less than or equal to the maximum value (implied by `RangeRestricted...MinMustBeLessThanMaxString`).
|
|
* **Logger State**:
|
|
* `TextLogger` requires `Start` to be called before `AddMessage` or `Stop`.
|
|
* `TextLogger` cannot `Start` if already running.
|
|
* `TextLogger` requires non-null/non-empty folder and filename arguments for `Start`.
|
|
* **Resource Access**: The `Resources` class is `internal` and intended only for use within this assembly.
|
|
|
|
## 4. Dependencies
|
|
|
|
**Internal Dependencies (Inferred)**
|
|
* `System.Reflection`
|
|
* `System.Runtime.CompilerServices`
|
|
* `System.Runtime.InteropServices`
|
|
* `System.Resources` (for `ResourceManager`)
|
|
* `System.Globalization` (for `CultureInfo`)
|
|
* `System.CodeDom.Compiler`
|
|
|
|
**External Dependencies**
|
|
* **DataPRO**: The library appears to interact with or configure an external application named "DataPRO" (referenced in `RegistryDataPROExe` and `NewSettingsCouldNotBeFound` strings).
|
|
|
|
## 5. Gotchas
|
|
|
|
* **Namespace Mismatch in ResourceManager**: The `Resources` class is located in the namespace `DTS.Common.Utilities.Properties`, but the `ResourceManager` constructor is initialized with the resource path `"DTS.Utilities.Properties.Resources"`. This discrepancy (missing `.Common`) suggests a potential runtime failure (`MissingManifestResourceException`) if the actual `.resx` file location does not match the hardcoded string, or it indicates a historical namespace refactoring that was not fully applied to the resource generator.
|
|
* **Threading Complexity in TextLogger**: The resource strings reveal complex lifecycle management for the `TextLogger`'s background writer thread (e.g., `TextLogger_Dispose_WriteThreadExitFailureString`, `TextLogger_Start_WriteThreadResponseTimeoutString`). Developers implementing or debugging this class must be aware that thread synchronization issues (timeouts, failure to start/stop) are explicitly handled and may result in specific error states rather than silent failures.
|
|
* **Hardcoded DateTime Format**: The `APILogging_DateTime_Format` resource suggests a specific fixed format ("yyyy-MM-dd HH:mm:ss.fff") is expected by the logging mechanism, which may not be culture-aware. |