CasCap.Common

A .NET class library repository containing 14 NuGet packages with helper functions, extensions, utilities, AI integration, and abstract classes for .NET applications.

Library	Package
CasCap.Common.Abstractions
CasCap.Common.AI
CasCap.Common.Caching
CasCap.Common.Configuration
CasCap.Common.Extensions
CasCap.Common.Extensions.Diagnostics.HealthChecks
CasCap.Common.Logging
CasCap.Common.Logging.Serilog
CasCap.Common.Net
CasCap.Common.OpenTelemetry
CasCap.Common.Serialization.Json
CasCap.Common.Serialization.MessagePack
CasCap.Common.Services
CasCap.Common.Testing

Libraries

Library	Description	Targets	Packable
CasCap.Common.Abstractions	Core interface definitions (IAppConfig, IFeature<T>, ILocalCache, IEventSink<T>, INotifier)	netstandard2.0; net8.0; net9.0; net10.0	✅
CasCap.Common.AI	AI agent framework — multi-provider agent creation, session management, MCP tool/prompt resolution, chat history compaction	net10.0	✅
CasCap.Common.Caching	Distributed caching (cache-aside pattern) with Memory/Disk local cache, Redis remote cache, and optional distributed locking	netstandard2.0; net8.0; net9.0; net10.0	✅
CasCap.Common.Configuration	Configuration bootstrapping — standard IConfiguration pipeline, Azure Key Vault, and validated IOptions<T> binding	netstandard2.0; net8.0; net9.0; net10.0	✅
CasCap.Common.Extensions	Common extension methods and helper utilities	netstandard2.0; net8.0; net9.0; net10.0	✅
CasCap.Common.Extensions.Diagnostics.HealthChecks	Custom health check extensions	netstandard2.0; net8.0; net9.0; net10.0	✅
CasCap.Common.Logging	Static logging abstraction via ApplicationLogging	netstandard2.0; net8.0; net9.0; net10.0	✅
CasCap.Common.Logging.Serilog	Reusable Serilog configuration with standard enrichers, console sink, and health-check filtering	net8.0; net9.0; net10.0	✅
CasCap.Common.Net	HttpClientBase, BasicAuthenticationHandler, HTTP client wrappers (net8.0+ only via #if)	netstandard2.0; net8.0; net9.0; net10.0	✅
CasCap.Common.OpenTelemetry	Reusable OpenTelemetry configuration with standard metrics, traces, and log exporters via OTLP gRPC	net8.0; net9.0; net10.0	✅
CasCap.Common.Serialization.Json	System.Text.Json serialization helpers	netstandard2.0; net8.0; net9.0; net10.0	✅
CasCap.Common.Serialization.MessagePack	MessagePack serialization helpers	netstandard2.0; net8.0; net9.0; net10.0	✅
CasCap.Common.Services	FeatureFlagBgService<T> and IFeature<T> abstractions	net8.0; net9.0; net10.0	✅
CasCap.Common.Testing	xUnit test logging utilities	netstandard2.0; net8.0; net9.0; net10.0	✅

Test Projects

Project	Targets
CasCap.Common.Caching.Tests	net8.0; net9.0; net10.0
CasCap.Common.Extensions.Tests	net8.0; net9.0; net10.0
CasCap.Common.Net.Tests	net8.0; net9.0; net10.0
CasCap.Common.Serialization.Tests	net8.0; net9.0; net10.0

Dependency Graph

Project reference relationships between libraries (NuGet-only dependencies omitted).

graph TD
    Logging[CasCap.Common.Logging]
    LoggingSerilog[CasCap.Common.Logging.Serilog]
    Abstractions[CasCap.Common.Abstractions]
    Extensions[CasCap.Common.Extensions]
    Configuration[CasCap.Common.Configuration]
    SerJson[CasCap.Common.Serialization.Json]
    SerMsgPack[CasCap.Common.Serialization.MessagePack]
    Net[CasCap.Common.Net]
    Caching[CasCap.Common.Caching]
    Services[CasCap.Common.Services]
    HealthChecks[CasCap.Common.Extensions.Diagnostics.HealthChecks]
    Testing[CasCap.Common.Testing]
    AI[CasCap.Common.AI]
    OTel[CasCap.Common.OpenTelemetry]

    Extensions --> Logging
    LoggingSerilog --> Logging
    Configuration --> Abstractions
    Configuration --> Logging
    SerJson --> Extensions
    SerJson --> Logging
    SerMsgPack --> Logging
    Net --> Abstractions
    Net --> SerJson
    Net --> Logging
    HealthChecks --> Extensions
    HealthChecks --> Logging
    Testing --> Logging
    Services --> Abstractions
    Services --> Extensions
    Caching --> Abstractions
    Caching --> Extensions
    Caching --> SerJson
    Caching --> SerMsgPack
    Caching --> Logging
    AI --> Abstractions
    AI --> Caching
    AI --> Extensions
    AI --> LoggingSerilog
    OTel --> Abstractions
    OTel --> LoggingSerilog
    OTel --> Services

Test project relationships:

graph TD
    Testing[CasCap.Common.Testing]
    CachingTests[CasCap.Common.Caching.Tests] --> Caching[CasCap.Common.Caching]
    CachingTests --> Testing
    ExtTests[CasCap.Common.Extensions.Tests] --> Extensions[CasCap.Common.Extensions]
    ExtTests --> Testing
    NetTests[CasCap.Common.Net.Tests] --> Net[CasCap.Common.Net]
    NetTests --> Testing
    SerTests[CasCap.Common.Serialization.Tests] --> SerJson[CasCap.Common.Serialization.Json]
    SerTests --> SerMsgPack[CasCap.Common.Serialization.MessagePack]
    SerTests --> Testing

Prerequisites

• .NET SDK: 10.0.x stable (see global.json — allowPrerelease: false)
• Docker: Required for Redis in caching tests

Build and Test

# 1. Restore (required before build)
dotnet restore

# 2. Build
dotnet build --no-restore

# 3. Start Redis (required before caching tests)
docker run -d -p 6379:6379 --name cascap-redis redis

# 4. Run tests — ALWAYS use --maxcpucount:1
dotnet test --no-build --maxcpucount:1

CRITICAL: Always use --maxcpucount:1 — parallel execution causes failures due to InlineData and Redis ClearOnStartup property conflicts.

Expected Build Behaviour

• Build produces nullability warnings (CS8604, CS8765) — these are accepted and must not be "fixed".
• Multi-target builds take ~15–20 seconds.

Project Configuration

Key Files

File	Purpose
Directory.Build.props	C# 14.0, ImplicitUsings, Nullable: enable, IsPackable: false by default
Directory.Packages.props	Central package version management (ManagePackageVersionsCentrally: true)
.editorconfig	Code style rules (4-space indent, LF line endings, full formatting rules)
global.json	SDK constraint — stable releases only
docker-compose.yml	Redis and Redis UI (p3x-redis-ui) services
GitVersion.yml	Semantic versioning configuration

Suppressed Warnings

Configured in Directory.Build.props: IDE1006, IDE0079, IDE0042, CS0162, CS1574, S125, NETSDK1233, NU1901, NU1902, NU1903

CI/CD Pipeline

GitHub Actions (.github/workflows/ci.yml)

Triggers: Push (except preview/**), PRs to main, manual dispatch.

Jobs:

1. lint — Reusable workflow from f2calv/gha-workflows
2. versioning — GitVersion-based semantic versioning
3. build — Ubuntu-latest with Redis service container; uses f2calv/gha-dotnet-nuget@v2; test args include --maxcpucount:1
4. release — GitHub release (main branch only, when tag doesn't already exist)

Making Changes

Adding Code

1. Place code in the correct project by functionality
2. Follow .editorconfig style rules
3. Add XML documentation to all public API surface
4. Add tests in the corresponding .Tests project
5. Validate: dotnet build --no-restore → 0 errors
6. Validate: dotnet test --no-build --maxcpucount:1 → all pass

Adding Dependencies

1. Add version to Directory.Packages.props

2. Reference in .csproj without a version attribute:

   <PackageReference Include="PackageName" />
   

3. Run dotnet restore

Creating New Projects

• Library projects inherit Directory.Build.props automatically
• Set <IsPackable>true</IsPackable> explicitly only for NuGet packages
• Test projects must not be packable (default) and must target net8.0;net9.0;net10.0

Validation Checklist

• dotnet restore succeeds
• dotnet build --no-restore completes with 0 errors
• Redis is running (if testing caching)
• dotnet test --no-build --maxcpucount:1 passes all tests
• Public API has XML documentation
• Properties separated by blank lines
• ServiceProvider instances are disposed in tests
• No shared mutable static state in test helpers

Contributing

1. Fork the repository and create a feature branch
2. Follow all conventions documented above
3. Run the full validation checklist before submitting a PR
4. PRs target the main branch and require CI to pass
5. Versioning is automated via GitVersion — do not manually edit version numbers
6. When using Copilot to implement code quality or legibility improvements, update the copilot-instructions.md to capture any new conventions so they are applied consistently in future sessions