Cuemon.Extensions.AspNetCore

Overview

Cuemon.Extensions.AspNetCore is the ASP.NET Core adapter layer for Cuemon.AspNetCore. It exposes middleware, dependency injection registrations, and HTTP helper extensions that let Cuemon's cache-busting, diagnostics, hosting, conditional caching, and throttling primitives fit naturally into IServiceCollection, IApplicationBuilder, HttpRequest, and HttpResponse code.

The package also carries the in-memory throttling cache registration that the lower-level ASP.NET Core package does not provide on its own. That makes it the broad integration package for applications that want Cuemon features in the core request pipeline without moving into the MVC- and formatter-specific sibling packages.

Key APIs

AssemblyCacheBusting turns an assembly into a cache-busting version string by hashing either assembly metadata or the full file bytes, depending on AssemblyCacheBustingOptions. AddAssemblyCacheBusting registers that implementation as ICacheBusting, and tests verify that different hash algorithms and the strong byte-for-byte mode change the computed version as expected.

AddServerTiming, AddServerTiming<T>, AddServerTimingOptions, and UseServerTiming wire IServerTiming into the request pipeline. The registration is scoped, the options path validates configurators up front, and the middleware entry point is a single extension method on IApplicationBuilder.

AddFaultDescriptorOptions, AddExceptionDescriptorOptions, PostConfigureAllExceptionDescriptorOptions, and UseFaultDescriptorExceptionHandler connect Cuemon's exception descriptor model to ASP.NET Core error handling. The exception handler inspects the current Accept header, selects a registered formatter when possible, sets the response status from the resolved descriptor, and falls back to a default handler when content negotiation does not find a match.

GetExceptionResponseFormatters and SelectExceptionDescriptorHandlers expose the registered HTTP exception formatters as a flat sequence of response handlers. Tests show that the service-provider helper discovers both XML and JSON formatters and surfaces all declared content types.

UseHostingEnvironment adds a middleware that writes the current hosting environment to an HTTP header. The test coverage shows the default header behavior and confirms that the configured suppression predicate still sees the resolved IHostEnvironment.

UseCorrelationIdentifier, UseRequestIdentifier, UseUserAgentSentinel, UseApiKeySentinel, UseCacheControl, and UseVaryAccept are the pipeline-facing HTTP helpers in the package. They wrap Cuemon middleware types behind concise IApplicationBuilder extensions so common header and request-guard behavior can be added from startup code instead of manual middleware construction.

HttpRequestExtensions and HttpResponseExtensions cover the conditional request workflow. They sort accepted MIME types by quality, detect GET or HEAD requests, evaluate If-None-Match and If-Modified-Since, add ETag and Last-Modified headers, write raw response bodies, and transfer an HttpResponseMessage into an ASP.NET Core response at start time.

ToEntityTagHeaderValue on CacheValidator and ChecksumBuilder bridges Cuemon data-integrity primitives into EntityTagHeaderValue. The tests confirm that weak and strong validators produce the expected quoted tags, which makes these helpers a small but important link between checksum generation and HTTP caching.

AddMemoryThrottlingCache, AddThrottlingCache<T>, AddThrottlingSentinelOptions, and UseThrottlingSentinel provide the package's throttling story. This is where the in-memory MemoryThrottlingCache registration lives, and the options method exposes quota, retry-after, header-name, and response-handler settings for the throttling middleware.

Basic usage

using System;
using Codebelt.Extensions.Xunit;
using Cuemon.Extensions.AspNetCore.Http;
using Microsoft.AspNetCore.Http;
using Microsoft.Net.Http.Headers;
using Xunit;

namespace Contoso.Web.Tests;

public class ConditionalRequestDecisionTest : Test
{
    public ConditionalRequestDecisionTest(ITestOutputHelper output) : base(output)
    {
    }

    [Fact]
    public void ShouldReturnNotModified_WhenConditionalGetMatchesLastModified()
    {
        var lastModified = DateTime.UnixEpoch;
        var context = new DefaultHttpContext();
        context.Request.Method = HttpMethods.Get;
        context.Request.Headers[HeaderNames.IfModifiedSince] = lastModified.ToString("R");

        var statusCode = context.Request.IsGetOrHeadMethod() && context.Request.IsClientSideResourceCached(lastModified)
            ? StatusCodes.Status304NotModified
            : StatusCodes.Status200OK;

        TestOutput.WriteLine($"Conditional request resolved to HTTP {statusCode}.");

        Assert.True(statusCode.IsNotModifiedStatusCode());
    }
}

Use this pattern when middleware or endpoint code needs to honor conditional GET or HEAD requests before writing a response body. It matters because the package keeps cache validation logic close to the request object and status-code decision instead of forcing manual header parsing and numeric comparisons.

Installation

dotnet add package Cuemon.Extensions.AspNetCore

Usage guidance

Choose this package when you want Cuemon's ASP.NET Core primitives to plug directly into service registration, middleware composition, and low-level HTTP request or response handling, especially for conditional caching, server timing, exception formatting, or in-memory throttling. If you only need the underlying abstractions without ASP.NET Core glue, or you are working in MVC or formatter-specific areas, prefer the lower-level Cuemon.AspNetCore package or the narrower sibling packages such as Cuemon.Extensions.AspNetCore.Mvc, Cuemon.Extensions.AspNetCore.Text.Json, or Cuemon.Extensions.AspNetCore.Xml.