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

---
source_files:
  - Common/DTS.CommonCore/Properties/AssemblyInfo.cs
  - Common/DTS.CommonCore/Properties/Settings.Designer.cs
  - Common/DTS.CommonCore/Properties/Annotations.cs
generated_at: "2026-04-16T02:15:24.461897+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "e93e9dbcf99f35a2"
---

# DTS.CommonCore Module Documentation

## 1. Purpose

This module (`DTS.CommonCore`) is a shared infrastructure library containing assembly metadata, application settings, and JetBrains Annotations for static code analysis. It serves as a foundational component for other modules in the DTS ecosystem by providing standardized configuration (e.g., tile asset paths), compile-time nullability contracts, and tooling annotations that enable ReSharper and similar analyzers to improve code correctness and maintainability. It does not contain business logic but supports consistency and correctness across dependent modules.

## 2. Public Interface

### Classes

#### `DTS.Common.Properties.Settings`
- **`public static Settings Default { get; }`**  
  Returns the singleton instance of the application settings. This is the primary access point for reading settings values.

#### `DTS.Common.Properties.Settings.TilesLocation`
- **`public string TilesLocation { get; }`**  
  Returns the configured path to tile assets, with a default value of `"Assets\\Tiles\\"`. This is an application-scoped setting (read-only at runtime).

### JetBrains Annotation Attributes (Namespace: `DTS.Common.Annotations`)

These are *metadata attributes only*—they have no runtime behavior but guide static analysis tools.

- **`[CanBeNull]`**  
  Indicates a value *may* be `null`. Applied to parameters, return values, fields, properties, etc.

- **`[NotNull]`**  
  Indicates a value *must not* be `null`. Applied to parameters, return values, fields, properties, etc.

- **`[ItemCanBeNull]` / `[ItemNotNull]`**  
  Applied to collections, `Task<T>`, or `Lazy<T>` to indicate whether *items/values* may be `null`.

- **`[StringFormatMethod(string formatParameterName)]`**  
  Marks methods that build strings using a format string (e.g., `string.Format`-style). The `formatParameterName` argument specifies which parameter holds the format string.

- **`[ContractAnnotation(string contract)]`**  
  Describes input/output relationships (e.g., `"s:null => true"` for `string.IsNullOrEmpty`). Supports complex contracts using FDT syntax.

- **`[NotifyPropertyChangedInvocator]`**  
  Marks methods used to raise `INotifyPropertyChanged` events. Enables tooling to validate property name strings.

- **`[PublicAPI(string comment)]`**  
  Marks members as part of the public API surface, preventing them from being flagged as unused.

- **`[Pure]`**  
  Indicates a method has no side effects (like `System.Diagnostics.Contracts.PureAttribute`).

- **`[MustUseReturnValue]`**  
  Indicates the return value of a method *must* be used; ignoring it triggers a warning.

- **`[InstantHandle]`**  
  Indicates a delegate or enumerable parameter is consumed synchronously within the method.

- **`[AssertionMethod]` / `[AssertionCondition(AssertionConditionType)]`**  
  Marks assertion methods (e.g., `ThrowIfNull`) and specifies the condition under which execution continues.

- **`[NoReorder]`**  
  Prevents IDE member reordering for the marked type.

> **Note**: All other attributes in `DTS.Common.Annotations` are similarly annotation-only and serve static analysis purposes. Their full semantics are documented in the source file comments.

## 3. Invariants

- **Settings immutability**: `TilesLocation` is an `ApplicationScopedSettingAttribute`, meaning its value is fixed at compile time and cannot be modified at runtime.
- **Nullability contracts**: Annotations like `[NotNull]` and `[CanBeNull]` are *declarative only*—they do not enforce null checks at runtime. Violations are detected only by static analysis tools.
- **No side effects for pure methods**: Methods marked `[Pure]` must not mutate observable state; this is a *contract* enforced by tooling, not the runtime.
- **No runtime behavior**: All attributes in `DTS.Common.Annotations` are inert at runtime (i.e., `Attribute.IsDefined` checks will work, but they do not alter execution flow).

## 4. Dependencies

### Dependencies *of* this module:
- **`System.Configuration`** (for `ApplicationSettingsBase`, `ApplicationScopedSettingAttribute`)
- **`System.Reflection`** (for assembly attributes)
- **`System.Runtime.InteropServices`** (for COM interop attributes)

### Dependencies *on* this module:
- Any module referencing `DTS.CommonCore` can use:
  - `DTS.Common.Properties.Settings.Default.TilesLocation` for tile asset paths.
  - All annotation attributes in `DTS.Common.Annotations` to annotate their own code for static analysis.

## 5. Gotchas

- **No runtime validation**: Annotations like `[NotNull]` do *not* throw `NullReferenceException` or `ArgumentNullException` automatically. Developers must manually enforce these contracts (e.g., via `Guard` clauses).
- **Settings are compile-time constants**: `TilesLocation` cannot be overridden via `app.config` or user settings—it is fixed at build time.
- **Tooling-dependent**: Annotations only provide value when using JetBrains ReSharper or compatible analyzers (e.g., Rider, Roslyn with ReSharper plugin). They are ignored by the C# compiler and .NET runtime.
- **Auto-generated code**: `Settings.Designer.cs` is auto-generated. Manual edits will be overwritten—changes should be made in the `.settings` designer or via `Settings.cs` (if present).
- **COM visibility disabled**: `ComVisible(false)` means types in this assembly are not exposed to COM. This is intentional for a .NET-only library.
- **Versioning**: Assembly version is hardcoded to `1.0.0.0` (with `AssemblyFileVersion` identical). No automatic build/revision numbering is configured.