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

source_files, generated_at, model, schema_version, sha256

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