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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common/Properties/AssemblyInfo.cs Common/DTS.Common/Properties/Settings.Designer.cs Common/DTS.Common/Properties/Annotations.cs	2026-04-16T02:54:58.885340+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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 [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.