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

---
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-17T15:39:49.646281+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "21c1e9d4d6a1c464"
---

# DTS.Common Module Documentation

## 1. Purpose

The `DTS.Common` module serves as a shared utility library providing application-wide configuration and static analysis annotations. It contains auto-generated application settings for tile asset locations and integrates JetBrains ReSharper annotations (MIT licensed) to enhance IDE static analysis capabilities including nullability checking, contract annotations, and framework-specific hints for ASP.NET MVC, Razor, and XAML development.

---

## 2. Public Interface

### Settings (DTS.Common.Properties)

**Class:** `internal sealed partial class Settings : ApplicationSettingsBase`

| Member | Signature | Description |
|--------|-----------|-------------|
| `Default` | `public static Settings Default { get; }` | Static singleton property providing thread-safe access to application settings via `ApplicationSettingsBase.Synchronized`. |
| `TilesLocation` | `public string TilesLocation { get; }` | Application-scoped setting returning the path to tile assets. Default value: `"Assets\\Tiles\\"`. |

### Annotation Attributes (DTS.Common.Annotations)

The module exposes numerous attribute classes for static analysis. Key categories include:

#### Nullability Attributes
| Attribute | Targets | Purpose |
|-----------|---------|---------|
| `CanBeNullAttribute` | Method, Parameter, Property, Delegate, Field, Event, Class, Interface, GenericParameter | Indicates value may be `null`; null check required before use. |
| `NotNullAttribute` | Same as above | Indicates value can never be `null`. |
| `ItemNotNullAttribute` | Method, Parameter, Property, Delegate, Field | For IEnumerable/Task/Lazy types; indicates item/Result/Value is never null. |
| `ItemCanBeNullAttribute` | Same as above | For IEnumerable/Task/Lazy types; indicates item/Result/Value may be null. |
| `ImplicitNotNullAttribute` | Class, Struct, Interface, Assembly | Implicitly applies `[NotNull]`/`[ItemNotNull]` to all members in scope. |

#### Contract & Method Behavior Attributes
| Attribute | Targets | Purpose |
|-----------|---------|---------|
| `ContractAnnotationAttribute` | Method | Describes input/output dependencies using FDT syntax (e.g., `"null => null; notnull => notnull"`). |
| `PureAttribute` | Method | Indicates method makes no observable state changes. |
| `MustUseReturnValueAttribute` | Method | Indicates return value must be used. |
| `InstantHandleAttribute` | Parameter | Indicates delegate/enumerable parameter is fully handled during method execution. |
| `AssertionMethodAttribute` | Method | Marks assertion methods that halt control flow. |
| `AssertionConditionAttribute` | Parameter | Marks condition parameter in assertion methods; takes `AssertionConditionType` enum. |
| `TerminatesProgramAttribute` | Method | **[Obsolete]** Use `[ContractAnnotation("=> halt")]` instead. |
| `LinqTunnelAttribute` | Method | Marks pure LINQ methods with postponed enumeration. |
| `NoEnumerationAttribute` | Parameter | Indicates IEnumerable parameter is not enumerated. |

#### String & Format Attributes
| Attribute | Targets | Purpose |
|-----------|---------|---------|
| `StringFormatMethodAttribute` | Constructor, Method, Property, Delegate | Marks method as string format builder; constructor takes format parameter name. |
| `ValueProviderAttribute` | Parameter, Property, Field | Indicates parameter expects values from specified type's fields. |
| `InvokerParameterNameAttribute` | Parameter | Indicates argument should be string literal matching a caller's parameter name. |
| `RegexPatternAttribute` | Parameter | Indicates parameter is a regular expression pattern. |

#### Implicit Usage Attributes
| Attribute | Targets | Purpose |
|-----------|---------|---------|
| `UsedImplicitlyAttribute` | All | Marks symbol as used implicitly (reflection, external libraries). |
| `MeansImplicitUseAttribute` | Class, GenericParameter | Applied to attributes; prevents marking attributed symbols as unused. |
| `PublicAPIAttribute` | All | Marks publicly available API that should not be removed. |

#### ASP.NET MVC Attributes
| Attribute | Targets | Purpose |
|-----------|---------|---------|
| `AspMvcActionAttribute` | Parameter, Method | Marks parameter as MVC action name. |
| `AspMvcAreaAttribute` | Parameter | Marks parameter as MVC area. |
| `AspMvcControllerAttribute` | Parameter, Method | Marks parameter as MVC controller. |
| `AspMvcViewAttribute` | Parameter, Method | Marks parameter as MVC view. |
| `AspMvcPartialViewAttribute` | Parameter, Method | Marks parameter as MVC partial view. |
| `AspMvcActionSelectorAttribute` | Parameter, Property | Marks parameter as MVC action name in attribute context. |
| `AspMvc*LocationFormatAttribute` | Assembly | Various location format attributes for master, partial view, and view locations. |

#### Razor Attributes
| Attribute | Targets | Purpose |
|-----------|---------|---------|
| `RazorSectionAttribute` | Parameter, Method | Marks parameter/method as Razor section. |
| `RazorImportNamespaceAttribute` | Assembly | Specifies namespace import for Razor. |
| `RazorInjectionAttribute` | Assembly | Specifies Razor injection configuration. |
| `RazorDirectiveAttribute` | Assembly | Specifies Razor directive. |

#### XAML Attributes
| Attribute | Targets | Purpose |
|-----------|---------|---------|
| `XamlItemsControlAttribute` | Class | Marks type as ItemsControl-derived for DataContext resolution. |
| `XamlItemBindingOfItemsControlAttribute` | Property | Marks property as binding for ItemsControl items. |

#### Collection & Enumeration
| Type | Purpose |
|------|---------|
| `CollectionAccessAttribute` | Indicates how method affects collection content. |
| `CollectionAccessType` (enum) | Flags: `None`, `Read`, `ModifyExistingContent`, `UpdatedContent`. |

#### Enums
| Enum | Values |
|------|--------|
| `ImplicitUseKindFlags` | `Default`, `Access`, `Assign`, `InstantiatedWithFixedConstructorSignature`, `InstantiatedNoFixedConstructorSignature` |
| `ImplicitUseTargetFlags` | `Default`, `Itself`, `Members`, `WithMembers` |
| `AssertionConditionType` | `IS_TRUE`, `IS_FALSE`, `IS_NULL`, `IS_NOT_NULL` |

---

## 3. Invariants

- **Settings Singleton**: The `Settings.Default` property always returns a synchronized, thread-safe singleton instance via `ApplicationSettingsBase.Synchronized()`.
- **TilesLocation Format**: The `TilesLocation` setting is an application-scoped string with a default value of `"Assets\\Tiles\\"` (trailing backslash included).
- **Assembly Version**: The assembly version is fixed at `1.0.0.0` for both `AssemblyVersion` and `AssemblyFileVersion`.
- **COM Visibility**: All types in this assembly have `ComVisible(false)` by default.
- **Annotations Namespace**: All annotation attributes reside in `DTS.Common.Annotations` namespace and are designed for compile-time static analysis only; they have no runtime behavior.
- **Settings Designer**: `Settings.Designer.cs` is auto-generated; manual changes will be lost upon regeneration.

---

## 4. Dependencies

### This Module Depends On:
- `System.Reflection` - For assembly metadata attributes
- `System.Runtime.CompilerServices` - For compiler-generated attributes and `CompilerGeneratedAttribute`
- `System.Runtime.InteropServices` - For `ComVisible` and `Guid` attributes
- `System.Configuration.ApplicationSettingsBase` - Base class for settings management
- `System.CodeDom.Compiler` - For `GeneratedCodeAttribute`
- `System.Diagnostics` - For `DebuggerNonUserCodeAttribute`

### What Depends On This Module:
- **Unclear from source alone** - The source files do not show consumers of this module. The `TilesLocation` setting suggests tile-based UI components may depend on this configuration.

---

## 5. Gotchas

1. **Auto-Generated Settings File**: `Settings.Designer.cs` contains a warning header indicating it is tool-generated. Modifications will be lost if the code is regenerated by Visual Studio's `SettingsSingleFileGenerator`.

2. **JetBrains Annotations License**: The `Annotations.cs` file is MIT-licensed from JetBrains (copyright 2016). While permissive, the license header must be preserved in copies.

3. **Obsolete Attribute**: `TerminatesProgramAttribute` is marked `[Obsolete("Use [ContractAnnotation('=> halt')] instead")]`. New code should use `ContractAnnotationAttribute`.

4. **Internal Settings Visibility**: The `Settings` class is marked `internal sealed`, limiting access to within the assembly. External assemblies cannot directly access these settings.

5. **Hardcoded Tiles Path**: The `TilesLocation` default value `"Assets\\Tiles\\"` uses Windows-style path separators. Cross-platform compatibility is unclear from source alone.

6. **Empty Assembly Description**: `AssemblyDescription` is empty in `AssemblyInfo.cs`, which may affect documentation generation tools.