77 lines
7.3 KiB
Markdown
77 lines
7.3 KiB
Markdown
---
|
|
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. |