Dekiru.Internals.ApiUtils 2.0.2

Dekiru.ApiUtils

A comprehensive ASP.NET Core utility library that provides standardised patterns for error handling, data access, row-level security, authentication, and more — so your team can focus on business logic instead of boilerplate.

Table of Contents

• Installation
• Supported Frameworks
• Features
  • Error Handling & ProblemDetails
  • Generic Data Access (ContextService)
  • Domain Authorization (Row-Level Security)
  • Entity Interfaces
  • JSON & Service Configuration
  • Azure Easy Auth
  • Row Versioning
  • SPA Middleware
• License
• LLM Quick Reference

Installation

dotnet add package Dekiru.Internals.ApiUtils

Supported Frameworks

Features

Error Handling & ProblemDetails

Registers a global exception handler that converts unhandled exceptions into RFC 7807 ProblemDetails responses.

Setup

// Program.cs
builder.Services.AddDefaultProblemDetailsProducer();

var app = builder.Build();
app.UseGlobalExceptionHandler(); // optionally pass showFullCallstack: true in Development

Throwing Typed Errors

ProblemDetailsException provides factory helpers for the most common HTTP error scenarios:

// 404 Not Found
throw ProblemDetailsException.NotFound("Order not found.");

// 400 Bad Request
throw ProblemDetailsException.BadRequest("Invalid date range.");

// 409 Conflict
throw ProblemDetailsException.Conflict("Duplicate entry.");

// 403 Forbidden
throw ProblemDetailsException.Forbidden();

// 410 Gone
throw ProblemDetailsException.Gone("Resource has been permanently removed.");

Attach arbitrary extensions for richer client-side error context:

throw ProblemDetailsException.NotFound("Product not found.")
    .WithExtensions(new Dictionary<string, object?> { ["productId"] = id });

Producing ProblemDetails Directly

return ProblemDetails.NotFound()
    .WithDetail("The requested resource could not be found.")
    .WithExtension("traceId", Activity.Current?.Id);

Custom Error Producer

Implement IProblemDetailsProducer and register it to override the default behaviour:

public class MyErrorProducer : IProblemDetailsProducer
{
    public ProblemDetails Create(HttpContext context, IExceptionHandlerPathFeature? ex, bool showFullCallstack)
    {
        // custom mapping logic
        return ProblemDetails.InternalServerError().WithDetail(ex?.Error.Message);
    }
}

builder.Services.AddCustomProblemDetailsProducer<MyErrorProducer>();

Generic Data Access (ContextService)

ContextServiceBase<TContext> wraps a DbContext and provides type-safe, async CRUD helpers with built-in pagination, predicate filtering, and automatic timestamp stamping.

Define a Service

public class AppContextService : ContextServiceBase<AppDbContext>
{
    public AppContextService(AppDbContext context, IServiceProvider provider)
        : base(context, provider) { }
}

Register It

builder.Services.AddContextService<AppContextService, AppDbContext>();

Common Operations

// Fetch a single entity by primary key
var order = await _service.Set<Order>()
    .FindAsync<Order, Guid>(orderId);

// Create
await _service.CreateAsync(new Order { ... });

// Update (auto-stamps IUpdated.Updated)
await _service.SaveChangesAsync();

// Soft-delete (sets Deleted = true if ISoftDeletable, otherwise hard-deletes)
await _service.DeleteAsync(order);

Request Types

!!! IMPORTANT !!! The request types have been moved to the Dekiru.ApiGenerator.Abstractions package.

Domain Authorization (Row-Level Security)

DomainHandler<T> lets you declare per-entity read/update/delete predicates and create/update/delete authorization checks that are automatically enforced at the EF Core query filter level.

Define a Handler

public class OrderDomainHandler : DomainHandler<Order>
{
    private readonly ICurrentUser _user;

    public OrderDomainHandler(ICurrentUser user)
    {
        _user = user;
        ReadPredicate   = o => o.TenantId == _user.TenantId;
        UpdatePredicate = o => o.TenantId == _user.TenantId && !o.IsLocked;
        DeletePredicate = o => o.TenantId == _user.TenantId && o.IsDraft;
    }

    public override Task<AuthorizationResult> CheckCreateAsync(Order entity)
        => _user.HasPermission("orders.create") ? Pass() : Fail("Not allowed to create orders.");
}

Register & Apply Query Filters

// Register all handlers in DI
builder.Services.AddScoped<DomainHandler<Order>, OrderDomainHandler>();

// In your DbContext.OnModelCreating, apply global query filters
provider.GetRequiredService<DomainHandlerProvider>().RegisterQueryFilters(modelBuilder);

Passthrough Handler

Use PassthroughDomainHandler<T> for entities that need no restriction — it permits all operations and applies no filter.

Entity Interfaces

Implement these interfaces on your EF entities to opt in to automatic behaviour provided by ContextServiceBase.

public class Order : ICreated, IUpdated, ISoftDeletable, IRowVersioned
{
    public Guid Id { get; set; }

    // Auto-set on first SaveChangesAsync
    public DateTimeOffset Created { get; set; }

    // Auto-set on every SaveChangesAsync
    public DateTimeOffset Updated { get; set; }

    // DeleteAsync sets this to true instead of removing the row
    public bool Deleted { get; set; }

    // Concurrency token — use with RowVersion helpers
    public byte[] RowVersion { get; set; } = [];
}

JSON & Service Configuration

A single extension method configures all recommended JSON serialiser settings:

builder.Services.ConfigureJson();
// Applies: camelCase property naming, ignore null values,
//          ignore reference cycles, string enum converter,
//          byte[] ↔ Base64 row-version converter

Register the row-version converter independently if needed:

builder.Services.AddRowVersionJsonConverter();

Azure Easy Auth

Parses the x-ms-client-principal header injected by Azure App Service / Container Apps Easy Auth into a standard ClaimsPrincipal.

builder.Services.AddEasyAuthAuthentication();

Use it the same way as any other ASP.NET Core authentication scheme — HttpContext.User is populated automatically. Extend EasyAuthHandler to customise claim transformation.

Row Versioning

Protect against lost-update conflicts with optimistic concurrency.

// In your EF model configuration
entity.Property(e => e.RowVersion).IsRowVersion();

// Validate incoming version from a client request
if (!entity.HasVersion(incomingVersion))
    throw ProblemDetailsException.Conflict("The resource has been modified. Please refresh and retry.");

// Convert between byte[] and Base64 string (e.g. for API payloads)
string base64 = RowVersion.ToString(entity.RowVersion);
byte[] bytes  = RowVersion.FromString(base64);

When AddRowVersionJsonConverter() (or ConfigureJson()) is registered, byte[] properties are automatically serialised as Base64 strings in all JSON responses.

SPA Middleware

Serve a Single Page Application with optional file-level content transformations (e.g. injecting environment variables into index.html at runtime).

app.UseSpaWithTransforms(
    contentPath: Path.Combine(Directory.GetCurrentDirectory(), "wwwroot"),
    config: (spa, values) =>
    {
        spa.Options.SourcePath = "ClientApp";
        // values can be used to substitute placeholders in static files
    });

Provide a StaticFileTransformerOptions instance for full control over caching headers, MIME types, and custom IFileProvider implementations.

License

MIT © Dekiru Solutions AB

LLM Quick Reference

This section is structured for AI code assistants. It provides a dense, scannable API surface so you can answer "how do I do X with this library?" without re-reading the full documentation above.

Library Mission

Dekiru.ApiUtils is a multi-targeted ASP.NET Core library (net8.0 / net9.0 / net10.0) that provides standardised, reusable infrastructure for REST APIs: RFC 7807 error responses, generic EF Core CRUD, row-level security, entity auditing, optimistic concurrency, Azure Easy Auth, JSON configuration, and SPA middleware.

Minimum Bootstrap (Program.cs)

// Error handling (required for ProblemDetailsException to produce HTTP responses)
builder.Services.AddDefaultProblemDetailsProducer();

// JSON (camelCase, null-ignore, cycle-safe, enum-as-string, row-version as Base64)
builder.Services.ConfigureJson();

// Domain authorization (row-level security via EF query filters)
builder.Services.AddDomainHandlers(); // scans calling assembly

// Context service (generic CRUD wrapper around DbContext)
builder.Services.AddContextService<AppContextService, AppDbContext>();

// Azure Easy Auth (optional — Azure App Service / Container Apps only)
builder.Services.AddEasyAuthAuthentication();

var app = builder.Build();
app.UseGlobalExceptionHandler(); // converts unhandled exceptions → ProblemDetails

Namespace Map

Scenario → API Reference

Complete Public Type Catalog

Interfaces (Dekiru.ApiUtils.Interfaces)

Error Handling (Dekiru.ApiUtils.ErrorHandling)

Services (Dekiru.ApiUtils.Services)

Domain Authorization (Dekiru.ApiUtils.Domain)

Utils (Dekiru.ApiUtils.Utils)

SPA (Dekiru.ApiUtils.Spa)

Entity Interface Decision Guide

All four can be combined on the same entity. ContextServiceBase handles stamping and deletion automatically during SaveChangesAsync and DeleteAsync.

Key Conventions

Component Wiring

The three main runtime components — DbContext, ContextServiceBase<TContext>, and DomainHandler<T> — connect as follows:

1. Registration (Program.cs): Call AddContextService<TService, TContext>() and AddDomainHandlers(). Both are scoped to the HTTP request.

2. Model creation (DbContext.OnModelCreating): Resolve DomainHandlerProvider from the service provider and call RegisterQueryFilters(modelBuilder). This iterates every registered DomainHandler<T> and attaches its ReadPredicate as an EF Core global query filter. The filter runs on every DbSet<T> query for the lifetime of the context.

3. Request handling: Inject your ContextServiceBase<TContext> subclass. Call ListAsync, CreateAsync, DeleteAsync, etc. Before any write, ContextServiceBase internally:

   • Calls DomainHandlerProvider.CheckCreateAsync<T>() / CheckUpdateAsync<T>() / CheckDeleteAsync<T>() to enforce authorization.
   • Calls PreSaveCheck(context) to stamp timestamps and handle soft-delete flags.

4. Error flow: If any authorization check or validation fails, a ProblemDetailsException is thrown. UseGlobalExceptionHandler() middleware catches it and writes a RFC 7807 JSON body with the correct HTTP status code.