---
source_files:
  - Common/DTS.Common/Properties/AssemblyInfo.cs
  - Common/DTS.Common/Properties/Settings.Designer.cs
  - Common/DTS.Common/Properties/Annotations.cs
generated_at: "2026-04-16T02:54:58.885340+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "5f5bbf4e9919cd3a"
---

# DTS.Common Module Documentation

## 1. Purpose

This module (`DTS.Common`) is a shared .NET class library containing infrastructure and utility components for the DTS (likely *Digital Transmission System* or similar domain) application suite. Its primary role is to provide centralized configuration management (via strongly-typed settings) and a comprehensive suite of JetBrains-style code annotation attributes to support static analysis tools (e.g., ReSharper) for improved code quality, null-safety guarantees, and contract enforcement across dependent projects. It does not contain business logic but serves as a foundational dependency for consistency and tooling support.

## 2. Public Interface

The module exposes **no public application logic** (no classes, methods, or properties beyond configuration and annotations). Its public surface consists solely of:

### `DTS.Common.Properties.Settings`
- **Type**: `internal sealed partial class Settings : ApplicationSettingsBase`
- **Access**: Exposed via static property `Settings.Default`
- **Behavior**: Provides application-scoped configuration settings. Only one setting is defined:
  - `TilesLocation` (`string`): Returns the configured path `"Assets\\Tiles\\"` (as specified by `DefaultSettingValueAttribute`). This is read-only at runtime (application-scoped).

### `DTS.Common.Annotations` Namespace
A collection of **attribute classes** used for static analysis annotations. These are *metadata-only* and have no runtime behavior. Key attributes include:

| Attribute | Signature | Purpose |
|-----------|-----------|---------|
| `CanBeNullAttribute` | `[AttributeUsage(...)] public sealed class CanBeNullAttribute : Attribute` | Indicates a value *may* be `null`. |
| `NotNullAttribute` | `[AttributeUsage(...)] public sealed class NotNullAttribute : Attribute` | Indicates a value *must not* be `null`. |
| `ItemNotNullAttribute` | `[AttributeUsage(...)] public sealed class ItemNotNullAttribute : Attribute` | For collections/Tasks/Lazy: indicates items/results are non-null. |
| `ItemCanBeNullAttribute` | `[AttributeUsage(...)] public sealed class ItemCanBeNullAttribute : Attribute` | For collections/Tasks/Lazy: indicates items/results *may* be `null`. |
| `StringFormatMethodAttribute` | `[AttributeUsage(...)] public sealed class StringFormatMethodAttribute : Attribute { public StringFormatMethodAttribute(string formatParameterName); public string FormatParameterName { get; } }` | Marks methods that build strings from a format string (like `string.Format`). |
| `ContractAnnotationAttribute` | `[AttributeUsage(..., AllowMultiple = true)] public sealed class ContractAnnotationAttribute : Attribute { public string Contract { get; } }` | Specifies input-output contracts (e.g., `"s:null => true"` for `string.IsNullOrEmpty`). |
| `NotifyPropertyChangedInvocatorAttribute` | `[AttributeUsage(AttributeTargets.Method)] public sealed class NotifyPropertyChangedInvocatorAttribute : Attribute { public string ParameterName { get; } }` | Marks methods used to raise `INotifyPropertyChanged` events. |
| `PublicAPIAttribute` | `[MeansImplicitUse(...)] public sealed class PublicAPIAttribute : Attribute { public string Comment { get; } }` | Marks public API as intentionally preserved (prevents "unused" warnings). |
| `PureAttribute` | `[AttributeUsage(AttributeTargets.Method)] public sealed class PureAttribute : Attribute` | Indicates a method has no side effects. |
| `MustUseReturnValueAttribute` | `[AttributeUsage(AttributeTargets.Method)] public sealed class MustUseReturnValueAttribute : Attribute { public string Justification { get; } }` | Indicates return value must be used. |
| `InstantHandleAttribute` | `[AttributeUsage(AttributeTargets.Parameter)] public sealed class InstantHandleAttribute : Attribute` | Indicates delegates/enumerables are used synchronously within the method. |
| `CollectionAccessAttribute` | `[AttributeUsage(...)] public sealed class CollectionAccessAttribute : Attribute { public CollectionAccessType CollectionAccessType { get; } }` | Describes how a method accesses a collection (e.g., `Read`, `UpdatedContent`). |
| `AssertionMethodAttribute` & `AssertionConditionAttribute` | `[AttributeUsage(...)] public sealed class AssertionMethodAttribute : Attribute`<br>`[AttributeUsage(AttributeTargets.Parameter)] public sealed class AssertionConditionAttribute : Attribute { public AssertionConditionType ConditionType { get; } }` | Marks assertion methods (e.g., `Guard.NotNull(...)`) and their conditions (`IS_TRUE`, `IS_NULL`, etc.). |
| *MVC/Razor/ASP.NET attributes* | e.g., `AspMvcActionAttribute`, `RazorSectionAttribute`, `XamlItemsControlAttribute`, etc. | Provide context hints for static analysis of ASP.NET MVC, Razor, and XAML code. |

> **Note**: All attributes are *passive*—they do not alter runtime behavior. They are consumed by static analysis tools (e.g., ReSharper) to improve code inspection.

## 3. Invariants

- **`Settings.Default.TilesLocation`** is guaranteed to return a non-null string value at runtime, specifically `"Assets\\Tiles\\"` (as defined by `DefaultSettingValueAttribute`). No validation or transformation is applied.
- **Annotation attributes** (`DTS.Common.Annotations.*`) are *compile-time metadata only*. They impose no runtime checks or enforcement.
- The assembly is **not COM-visible** (`ComVisible(false)`).
- Versioning is fixed: `AssemblyVersion("1.0.0.0")` and `AssemblyFileVersion("1.0.0.0")`.

## 4. Dependencies

### Dependencies *of* `DTS.Common`:
- `System.Configuration` (for `ApplicationSettingsBase` and attributes like `ApplicationScopedSettingAttribute`)
- `System.Runtime.CompilerServices`, `System.CodeDom.Compiler`, `System.Diagnostics` (for generated code attributes)
- `System` (core types)

### Dependencies *on* `DTS.Common`:
- **Inferred**: Any project referencing `DTS.Common` can use:
  - `DTS.Common.Properties.Settings.Default.TilesLocation` for configuration.
  - `DTS.Common.Annotations` attributes to annotate their own code for static analysis.
- **No other modules are referenced** in the provided source files.

## 5. Gotchas

- **No runtime logic**: This module provides *no* executable business functionality—only configuration and annotations. Developers may mistakenly expect utility methods (e.g., string helpers, validation) that do not exist here.
- **Settings are read-only at runtime**: `TilesLocation` is `ApplicationScopedSettingAttribute`, meaning it cannot be modified programmatically (only via `app.config`/`web.config`).
- **Annotations are tooling-only**: Using `[NotNull]` or `[ContractAnnotation]` does *not* throw exceptions at runtime if violated. Static analysis tools (e.g., ReSharper) will warn, but the code will run.
- **Generated code warning**: `Settings.Designer.cs` explicitly warns that changes will be lost on regeneration (typical for Visual Studio settings designers).
- **Legacy annotations**: The `TerminatesProgramAttribute` is marked `[Obsolete]` in favor of `[ContractAnnotation("=> halt")]`.
- **No public API surface beyond annotations/settings**: Do not expect classes like `StringUtils`, `ValidationHelper`, etc., in this module.