80 lines
5.2 KiB
Markdown
80 lines
5.2 KiB
Markdown
|
---
|
||
|
|
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-16T12:03:42.508191+00:00"
|
||
|
|
model: "zai-org/GLM-5-FP8"
|
||
|
|
schema_version: 1
|
||
|
|
sha256: "e93e9dbcf99f35a2"
|
||
|
|
---
|
||
|
|
|
||
|
|
# Documentation: DTS.CommonCore Properties
|
||
|
|
|
||
|
|
## 1. Purpose
|
||
|
|
This module provides assembly-level metadata, application configuration management, and static analysis annotations for the `DTS.CommonCore` library. It defines the assembly identity (version 1.0.0.0, title "Common"), exposes a strongly-typed settings accessor for file paths (specifically `TilesLocation`), and embeds a comprehensive suite of JetBrains ReSharper annotations within the `DTS.Common.Annotations` namespace to support nullability checks, method contracts, and MVC/Razor inspections during development.
|
||
|
|
|
||
|
|
## 2. Public Interface
|
||
|
|
|
||
|
|
### Class: `DTS.Common.Properties.Settings`
|
||
|
|
Defined in `Settings.Designer.cs`. This is an internal, sealed class inheriting from `System.Configuration.ApplicationSettingsBase`.
|
||
|
|
|
||
|
|
* **`static Settings Default { get; }`**
|
||
|
|
* Returns the singleton instance of the settings class, synchronized for thread safety.
|
||
|
|
* **`string TilesLocation { get; }`**
|
||
|
|
* An application-scoped setting representing a directory path.
|
||
|
|
* Default Value: `"Assets\\Tiles\\"`
|
||
|
|
|
||
|
|
### Namespace: `DTS.Common.Annotations`
|
||
|
|
Defined in `Annotations.cs`. Contains attributes used for static code analysis. Key classes include:
|
||
|
|
|
||
|
|
**Nullability & State:**
|
||
|
|
* `CanBeNullAttribute`: Indicates an element value can be null.
|
||
|
|
* `NotNullAttribute`: Indicates an element value can never be null.
|
||
|
|
* `ItemNotNullAttribute`: Indicates collection items/Task results are not null.
|
||
|
|
* `ItemCanBeNullAttribute`: Indicates collection items/Task results can be null.
|
||
|
|
* `PureAttribute`: Indicates a method has no observable side effects.
|
||
|
|
|
||
|
|
**Contracts & Logic:**
|
||
|
|
* `ContractAnnotationAttribute`: Describes input/output dependencies (e.g., `"null => null"`).
|
||
|
|
* `AssertionMethodAttribute`: Marks a method as an assertion that halts flow.
|
||
|
|
* `AssertionConditionAttribute`: Marks a parameter as the condition for an assertion.
|
||
|
|
* `TerminatesProgramAttribute`: (Obsolete) Indicates method termination.
|
||
|
|
|
||
|
|
**Usage & Visibility:**
|
||
|
|
* `UsedImplicitlyAttribute`: Suppresses "unused" warnings for symbols accessed via reflection.
|
||
|
|
* `MeansImplicitUseAttribute`: Applied to attributes to suppress "unused" warnings on targets.
|
||
|
|
* `PublicAPIAttribute`: Marks API as publicly available and treated as used.
|
||
|
|
* `InstantHandleAttribute`: Indicates a parameter (delegate/enumerable) is fully handled during the method execution.
|
||
|
|
|
||
|
|
**MVC & Razor Specifics:**
|
||
|
|
* `AspMvcActionAttribute`, `AspMvcControllerAttribute`, `AspMvcViewAttribute`: Hints for MVC routing parameters.
|
||
|
|
* `RazorSectionAttribute`, `RazorImportNamespaceAttribute`: Hints for Razor syntax.
|
||
|
|
|
||
|
|
**Templates:**
|
||
|
|
* `SourceTemplateAttribute`: Marks an extension method as a source template for code completion.
|
||
|
|
* `MacroAttribute`: Defines macros for source template parameters.
|
||
|
|
|
||
|
|
### Assembly Metadata (`AssemblyInfo.cs`)
|
||
|
|
* **Title:** "Common"
|
||
|
|
* **Version:** "1.0.0.0"
|
||
|
|
* **GUID:** `d16201c7-478c-4b92-ba6e-a0d39fd5f081`
|
||
|
|
* **ComVisible:** `false`
|
||
|
|
|
||
|
|
## 3. Invariants
|
||
|
|
* **Thread Safety:** The `Settings.Default` property is guaranteed to be thread-safe due to the `Synchronized` wrapper used in its initialization.
|
||
|
|
* **Scope:** The `Settings` class is defined as `internal sealed`, restricting access to within the `DTS.CommonCore` assembly.
|
||
|
|
* **Read-Only Settings:** The `TilesLocation` property is application-scoped (`ApplicationScopedSettingAttribute`), meaning it is read-only at runtime and cannot be modified by user code.
|
||
|
|
* **Analysis Only:** Attributes defined in `Annotations.cs` do not affect runtime behavior; they are strictly for static analysis tools (specifically ReSharper/Rider).
|
||
|
|
|
||
|
|
## 4. Dependencies
|
||
|
|
* **System.Configuration:** Required by `Settings.Designer.cs` for `ApplicationSettingsBase`.
|
||
|
|
* **System.Reflection:** Required by `AssemblyInfo.cs` for assembly attributes.
|
||
|
|
* **System.Runtime.CompilerServices:** Required for `CompilerGeneratedAttribute` and `InternalsVisibleTo` logic.
|
||
|
|
* **System.Runtime.InteropServices:** Required for `ComVisible` and `Guid` attributes.
|
||
|
|
|
||
|
|
## 5. Gotchas
|
||
|
|
* **Namespace Discrepancy:** The assembly title is "Common", the file path suggests "DTS.CommonCore", but the settings reside in the `DTS.Common.Properties` namespace. The annotations reside in `DTS.Common.Annotations`. Developers should verify the correct namespace when referencing these components.
|
||
|
|
* **Hardcoded Path Separator:** The `TilesLocation` setting uses Windows-style backslashes (`"Assets\\Tiles\\"`). This may cause cross-platform compatibility issues if the application is run on non-Windows systems without path normalization logic elsewhere in the codebase.
|
||
|
|
* **Auto-Generated Code:** `Settings.Designer.cs` contains a header warning that manual changes will be lost if the code is regenerated. Settings should be managed via the Visual Studio settings designer or the `app.config` file.
|
||
|
|
* **Company Metadata:** The `AssemblyInfo.cs` lists `AssemblyCompany` as "Microsoft". This appears to be template boilerplate and may not reflect the actual ownership of the proprietary codebase.
|