Cuemon.Extensions.AspNetCore.Mvc

Overview

Cuemon.Extensions.AspNetCore.Mvc adds the consumer-facing glue that turns Cuemon.AspNetCore.Mvc primitives into MVC-friendly extension points. It wraps values as ICacheableObjectResult instances for ETag and Last-Modified handling, adds registration helpers for Cuemon MVC filters, and exposes diagnostics helpers for exception-to-HTTP mappings.

The package also includes route-aware Razor helpers and experimental breadcrumb composition for controller views. That makes it useful when you want Cuemon caching and diagnostics behavior to surface directly in controllers, filter collections, MVC builder configuration, and Razor rendering instead of wiring the lower-level pieces by hand.

Key APIs

WithCacheableHeaders<T> wraps a value in an ICacheableObjectResult that carries both timestamp and integrity metadata, so HttpCacheableFilter can emit both Last-Modified and ETag headers from one result object.

WithEntityTagHeader<T> is the focused wrapper for integrity-driven caching. It lets you provide a checksum and weak-versus-strong validation strategy without building the cacheable result yourself.

WithLastModifiedHeader<T> is the timestamp-focused wrapper for scenarios where freshness comes from creation and change timestamps. Tests show it populates both Created and Modified values through the configured providers.

AddEntityTagHeader and AddLastModifiedHeader populate an IList<ICacheableAsyncResultFilter> with the built-in cache validators. AddLastModifiedHeader inserts at index 0, which makes filter ordering explicit when you compose the cache pipeline.

AddFilter<T, TOptions> and InsertFilter<T, TOptions> are the extensibility points for custom ICacheableAsyncResultFilter implementations. They instantiate filters through ActivatorFactory, including constructor-based parameter objects constrained to IParameterObject.

AddHttpFaultResolver<T> adds MVC fault mappings to an IList<HttpFaultResolver> through three overload families: one for HttpStatusCodeException, one for arbitrary exceptions plus an HTTP status code, and one for a fully custom descriptor factory.

AddHttpCacheable, AddFaultDescriptor, AddServerTiming, AddApiKeySentinel, AddThrottlingSentinel, and AddUserAgentSentinel register the corresponding Cuemon MVC filters on FilterCollection, which keeps global filter setup close to standard MVC configuration.

AddFaultDescriptorOptions and AddHttpCacheableOptions push validated option delegates into the underlying service collection for IMvcBuilder. AddFaultDescriptorOptions also mirrors sensitivity settings into ExceptionDescriptorOptions, so MVC fault output and exception descriptor behavior stay aligned.

UseWhenView<T>, UseWhenPage<T>, AddBreadcrumbs<T>, and GetBreadcrumbs() handle route-aware markup and breadcrumb generation for views and Razor Pages. ViewDataDictionaryExtensions is explicitly marked experimental in source, which is a good signal to keep breadcrumb usage narrow and test-backed.

Basic usage

using System;
using System.Collections.Generic;
using System.Linq;
using Cuemon.AspNetCore.Diagnostics;
using Cuemon.Extensions.AspNetCore.Mvc.Filters.Diagnostics;
using Codebelt.Extensions.Xunit;
using Microsoft.AspNetCore.Http;
using Xunit;

namespace MyProject.Tests;

public sealed class HttpFaultResolverExtensionsTest : Test
{
    public HttpFaultResolverExtensionsTest(ITestOutputHelper output) : base(output)
    {
    }

    [Fact]
    public void AddHttpFaultResolver_ShouldDescribeArgumentFailuresAsBadRequest()
    {
        var resolvers = new List<HttpFaultResolver>();
        var resolver = resolvers
            .AddHttpFaultResolver<ArgumentException>(StatusCodes.Status400BadRequest, message: "Payload validation failed.")
            .Single();

        var resolved = resolver.TryResolveFault(new ArgumentException("Missing id."), out var descriptor);

        TestOutput.WriteLine(descriptor.ToString());

        Assert.True(resolved);
        Assert.Equal(StatusCodes.Status400BadRequest, descriptor.StatusCode);
        Assert.Equal("Payload validation failed.", descriptor.Message);
        Assert.Equal("BadRequest", descriptor.Code);
    }
}

Use this pattern when your MVC fault pipeline needs a predictable HTTP response for a specific exception type. It matters because the resolver list stays explicit and testable while the package fills in the standard HTTP metadata for the mapped failure.

Installation

dotnet add package Cuemon.Extensions.AspNetCore.Mvc

Usage guidance

Adopt this package when an ASP.NET Core MVC application already uses Cuemon and you want cache validators, fault resolution, filter registration, or route-aware view helpers exposed as extension methods instead of hand-built plumbing. If you only need the lower-level MVC primitives, specialized formatter packages, or plain framework behavior, prefer Cuemon.AspNetCore.Mvc, a sibling extension package, or the built-in ASP.NET Core APIs over this broader extension layer.