CaeriusNet 11.1.0

CaeriusNet

<p align="center"> <a href="https://www.nuget.org/packages/CaeriusNet"><img src="https://img.shields.io/nuget/v/CaeriusNet?style=flat&logo=nuget" alt="NuGet version"></a> <a href="https://www.nuget.org/packages/CaeriusNet"><img src="https://img.shields.io/nuget/dt/CaeriusNet?style=flat" alt="NuGet downloads"></a> <img src="https://img.shields.io/badge/.NET%2010-512BD4.svg?style=flat&logo=dotnet&logoColor=white" alt=".NET 10"> <img src="https://img.shields.io/badge/C%23%2014-%23239120.svg?style=flat&logo=csharp&logoColor=white" alt="C# 14"> <img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat" alt="MIT License"> </p>

High-performance micro-ORM for C# 14 / .NET 10 that executes SQL Server Stored Procedures, maps DTOs at compile-time, passes Table-Valued Parameters, and caches results — all in a single package, zero reflection at runtime.

Installation

dotnet add package CaeriusNet

AutoContracts is included in CaeriusNet. Set the MSBuild properties when you want build-time SQL Server contract discovery; there is no additional install step.

Prerequisites

• .NET 10 or later
• SQL Server 2019 or later

Quick Start

1. Configure (Program.cs)

// Standard
CaeriusNetBuilder.Create(services)
    .WithSqlServer("Server=.;Database=MyDb;Trusted_Connection=True;")
    .Build();

// .NET Aspire
CaeriusNetBuilder.Create(builder)
    .WithAspireSqlServer("CaeriusNet")
    .WithAspireRedis()
    .Build();

2. Define a DTO

Source-generated (recommended):

[GenerateDto]
public sealed partial record ProductDto(int Id, string Name, decimal Price);
// Generates: ISpMapper<ProductDto> with MapFromDataReader at compile-time

Manual:

public sealed record ProductDto(int Id, string Name, decimal Price) : ISpMapper<ProductDto>
{
    public static ProductDto MapFromDataReader(SqlDataReader reader)
        => new(reader.GetInt32(0), reader.GetString(1), reader.GetDecimal(2));
}

3. Execute a Stored Procedure

var sp = new StoredProcedureParametersBuilder("dbo", "sp_GetProducts", ResultSetCapacity: 1)
    .AddParameter("CategoryId", categoryId, SqlDbType.Int)
    .Build();

ReadOnlyCollection<ProductDto> products =
    await dbContext.QueryAsReadOnlyCollectionAsync<ProductDto>(sp, ct);

Table-Valued Parameters (TVP)

Source-generated:

[GenerateTvp(Schema = "dbo", TvpName = "tvp_int")]
public sealed partial record IntTvp(int Value);

Manual:

public sealed record OrderLineDto(int ProductId, int Qty) : ITvpMapper<OrderLineDto>
{
    public static string TvpTypeName => "dbo.tvp_OrderLine";

    public IEnumerable<SqlDataRecord> MapAsSqlDataRecords(IEnumerable<OrderLineDto> items)
    {
        var meta = new[] { new SqlMetaData("ProductId", SqlDbType.Int), new SqlMetaData("Qty", SqlDbType.Int) };
        foreach (var item in items)
        {
            var record = new SqlDataRecord(meta);
            record.SetInt32(0, item.ProductId);
            record.SetInt32(1, item.Qty);
            yield return record;
        }
    }
}

Usage:

var sp = new StoredProcedureParametersBuilder("dbo", "sp_BulkInsert", ResultSetCapacity: 1)
    .AddTvpParameter("OrderLines", orderLines)
    .Build();

int rows = await dbContext.ExecuteNonQueryAsync(sp, ct);

AutoContracts

AutoContracts validates stored procedure contracts from SQL Server metadata during normal builds. Add CaeriusNet to the project that owns your data-access code, then use MSBuild properties to pull or verify the manifest.

<PropertyGroup>
  <CaeriusContractsMode>Pull</CaeriusContractsMode>
  <CaeriusContractsConnectionName>DefaultConnection</CaeriusContractsConnectionName>
</PropertyGroup>

dotnet build

Pull creates or refreshes caerius.contracts.json. Commit that file with your code. In CI, switch to Verify so the build fails if SQL Server metadata drifts from the committed manifest.

Caching

var sp = new StoredProcedureParametersBuilder("dbo", "sp_GetProducts", ResultSetCapacity: 2)
    .AddParameter("CategoryId", categoryId, SqlDbType.Int)
    .AddFrozenCache("products:all")                          // immutable, process-lifetime
    // .AddInMemoryCache("products:all", TimeSpan.FromMinutes(5))
    // .AddRedisCache("products:all", TimeSpan.FromMinutes(5))
    .Build();

Cache invalidation

Inject the ICaeriusNetCache façade to invalidate entries from any service:

public sealed class ProductsService(ICaeriusNetCache cache)
{
    public async ValueTask InvalidateProductAsync(int id, CancellationToken ct)
    {
        await cache.RemoveAsync($"products:{id}", ct);              // all tiers
        await cache.RemoveAsync("products:all", CacheType.Frozen, ct);
        // await cache.ClearAsync(CacheType.InMemory, ct);          // dangerous; use sparingly
    }
}

ClearAsync(CacheType.Redis) intentionally throws NotSupportedException — clearing a shared distributed cache from a single service is almost never what you want.

To bound the in-memory tier, configure it explicitly at startup:

CaeriusNetBuilder.Create(services)
    .WithSqlServer(connectionString)
    .WithInMemoryCacheOptions(new MemoryCacheOptions { SizeLimit = 50_000 })
    .Build();

When SizeLimit is set, every cached entry is sized as 1 so the limit acts as a maximum entry count.

Transactions

Stored-procedure transactions reuse a single SqlConnection for the whole scope and attach the underlying SqlTransaction to every command. Caching is bypassed inside a transaction.

await using var tx = await dbContext.BeginTransactionAsync(IsolationLevel.ReadCommitted, ct);

var debit = new StoredProcedureParametersBuilder("dbo", "sp_DebitAccount", ResultSetCapacity: 2)
    .AddParameter("AccountId", fromId, SqlDbType.Int)
    .AddParameter("Amount", amount, SqlDbType.Decimal)
    .Build();

var credit = new StoredProcedureParametersBuilder("dbo", "sp_CreditAccount", ResultSetCapacity: 2)
    .AddParameter("AccountId", toId, SqlDbType.Int)
    .AddParameter("Amount", amount, SqlDbType.Decimal)
    .Build();

await tx.ExecuteNonQueryAsync(debit, ct);
await tx.ExecuteNonQueryAsync(credit, ct);

await tx.CommitAsync(ct);   // omit -> auto-rollback on dispose

Design constraints (enforced at runtime):

Write Operations

var sp = new StoredProcedureParametersBuilder("dbo", "sp_CreateProduct", ResultSetCapacity: 2)
    .AddParameter("Name", name, SqlDbType.NVarChar)
    .AddParameter("Price", price, SqlDbType.Decimal)
    .Build();

int rows = await dbContext.ExecuteNonQueryAsync(sp, ct);

// Or retrieve a scalar return value
int newId = await dbContext.ExecuteScalarAsync<int>(sp, ct);

Multi-Result Sets

var sp = new StoredProcedureParametersBuilder("dbo", "sp_GetDashboard", ResultSetCapacity: 0).Build();

(IEnumerable<ProductDto> products, IEnumerable<CategoryDto> categories) =
    await dbContext.QueryMultipleIEnumerableAsync<ProductDto, CategoryDto>(sp, ct);

Supported up to 5 result sets: QueryMultipleIEnumerableAsync<T1,T2> through QueryMultipleIEnumerableAsync<T1,T2,T3,T4,T5>. The multi-result APIs return ValueTask to match the rest of the async execution API.

Available Query Methods

Supported DTO Types

The source generator maps C# types to SQL Server types and generates the correct SqlDataReader calls.

Types without a native mapping fall back to sql_variant with compile-time warning CAERIUS005.

Observability

CaeriusNet uses [LoggerMessage] source-generated structured logging with zero-allocation event methods.

All events include structured properties (cache key, schema, procedure name, elapsed time, row count) for integration with OpenTelemetry, Seq, Application Insights, or any ILogger sink.

Tracing & Metrics (OpenTelemetry / Aspire)

CaeriusNet also publishes OpenTelemetry-compatible traces and metrics through the BCL primitives — no OpenTelemetry SDK package is added to the library. Consumers (typically an Aspire ServiceDefaults project) opt-in by registering the source/meter named CaeriusNet:

using CaeriusNet.Telemetry;

builder.Services.AddOpenTelemetry()
    .WithTracing(t => t.AddSource(CaeriusDiagnostics.SourceName))
    .WithMetrics(m => m.AddMeter(CaeriusDiagnostics.SourceName));

Spans are ActivityKind.Client, named SP {schema}.{procedure}, and tagged with the OpenTelemetry DB semantic conventions (db.system = mssql, db.operation, db.statement) plus library-specific attributes:

• caerius.sp.schema, caerius.sp.name, caerius.sp.command, caerius.sp.parameters (names only by default; CaptureParameterValues defaults to false — set it to true on CaeriusTelemetryOptions to also capture @name=value pairs, but keep it disabled in production to avoid leaking PII or secrets into telemetry back-ends)
• caerius.tvp.used (true/false) and caerius.tvp.type_name when a Table-Valued Parameter is attached
• caerius.resultset.multi and caerius.resultset.expected_count (1 by default, 2/3/4/5 for the multi-RS overloads)
• caerius.cache.tier / caerius.cache.hit (set on the active span when a cache lookup occurs)
• caerius.tx = true when the call runs inside an ICaeriusNetTransaction
• caerius.rows_returned / caerius.rows_affected on success

Metrics exposed by the CaeriusNet meter:

• caerius.sp.duration (Histogram, ms)
• caerius.sp.executions (Counter)
• caerius.sp.errors (Counter)
• caerius.cache.lookups (Counter, tagged with caerius.cache.tier and caerius.cache.hit)

When a cache hit short-circuits the SQL call, no DB span is created — only caerius.cache.lookups{hit=true} is emitted, so the Aspire dashboard accurately reflects that the database was not contacted.

Documentation

Full documentation, samples, and API reference: https://caerius.net

Source code & releases: https://github.com/CaeriusNET/CaeriusNet

License

MIT