Codebelt
A hand holding a card marked Startup with a browser and Razor page in the background.

Simple ASP.NET Core MVC Razor Setup

Cuemon brings configurable response headers, ETag filters, and versioned asset tag helpers to an ASP.NET Core MVC application with Razor views. This updated walkthrough uses the current hosting model and Cuemon 11 packages.

LIBRARIES
  • Cuemon
  • ASP.NET Core
  • MVC
  • Razor
  • Configuration
  • Caching
A hand holding a card marked Start-up against a dark background.

The original walkthrough explained the Cuemon website's ASP.NET Core MVC 2.1 setup, line by line. Its building blocks remain useful: options binding, cache validation, asset versioning, and diagnostic headers. Their registration APIs and the ASP.NET Core host model have changed.

Note

Originally published on the Cuemon blog on 29 September 2018. The publication date and original image are retained. This version updates the walkthrough for Cuemon 11.0.0 and an ASP.NET Core application with MVC controllers and Razor views; it does not describe the old site's deployed configuration.

Compare with the original Cuemon blog version, captured 14 November 2026: Read archived webpage. The archive includes later edits made on the original blog; historical links are inactive.

Packages and application setup

Start with an ASP.NET Core MVC project targeting .NET 10 or .NET 11. Add these Cuemon packages at the same version:

dotnet add package Cuemon.Extensions.AspNetCore --version 11.0.0
dotnet add package Cuemon.Extensions.AspNetCore.Mvc --version 11.0.0
dotnet add package Cuemon.AspNetCore.Razor.TagHelpers --version 11.0.0

The following explicit entry point replaces the earlier Startup.ConfigureServices and Startup.Configure walkthrough:

using System.Threading.Tasks;
using Cuemon.AspNetCore.Mvc.Filters.Cacheable;
using Cuemon.AspNetCore.Razor.TagHelpers;
using Cuemon.Extensions.AspNetCore.Configuration;
using Cuemon.Extensions.AspNetCore.Hosting;
using Cuemon.Extensions.AspNetCore.Http.Headers;
using Cuemon.Extensions.AspNetCore.Mvc.Filters.Cacheable;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

namespace MvcExamples;

internal static class Program
{
    private static async Task Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        builder.Services.Configure<CdnTagHelperOptions>(
            builder.Configuration.GetSection("CdnTagHelperOptions"));

        builder.Services.Configure<HttpCacheableOptions>(options =>
        {
            options.Filters.AddEntityTagHeader(entityTag =>
            {
                entityTag.UseEntityTagResponseParser = true;
            });
        });

        builder.Services.AddAssemblyCacheBusting();
        builder.Services.AddControllersWithViews(options =>
        {
            options.Filters.Add<HttpCacheableFilter>();
        });

        var app = builder.Build();

        app.UseHttpsRedirection();
        app.UseStaticFiles();
        app.UseHostingEnvironment();
        app.UseCorrelationIdentifier();
        app.UseRouting();
        app.UseAuthorization();
        app.MapControllerRoute(
            name: "default",
            pattern: "{controller=Home}/{action=Index}/{id?}");

        await app.RunAsync();
    }
}

This is the registration portion of an MVC application; keep the template's controllers, views, and production exception handling. AddControllersWithViews registers MVC with Razor view support. MapControllerRoute maps controller endpoints in place of the old UseMvc call. There is no SetCompatibilityVersion call in this setup.

Bind the asset tag-helper options

Configure the CDN host in appsettings.json, or override it per environment. The domain below is an example: replace it with the host that actually serves your files.

{
  "CdnTagHelperOptions": {
    "Scheme": "Https",
    "BaseUrl": "cdn.example.com"
  }
}

Register the packaged tag helpers in Views/_ViewImports.cshtml:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, Cuemon.AspNetCore.Razor.TagHelpers

Then a Razor view can reference an asset through the configured host:

<cdn-link href="css/site.css" />

CdnLinkTagHelper emits a stylesheet link and, when an ICacheBusting service is registered, appends its version as a v query parameter. The registration comes from Cuemon.AspNetCore.Razor.TagHelpers, replacing the original site's custom tag-helper assembly. The configuration changes the generated URL; it does not upload files to a CDN.

AddAssemblyCacheBusting() registers assembly-derived versioning. It replaces the old parameterless AddCacheBusting() shorthand. AddDynamicCacheBusting() is another option, but rotates the version on a configured time interval; it does not watch CSS files for changes. Choose versioning that matches how assets are deployed.

Configure the HTTP ETag filter

HttpCacheableFilter coordinates the filters registered in HttpCacheableOptions.Filters. In this example, AddEntityTagHeader enables body-based parsing through UseEntityTagResponseParser.

For eligible successful GET and HEAD responses, the ETag filter can buffer the executed result and calculate a validator from the response body. It can also use integrity metadata supplied by an object result. Matching conditional requests can receive a 304 Not Modified response.

Body parsing has a cost: rendering and buffering still occur before a body-derived validator is available. It is unsuitable as a blanket choice for large or streamed responses. An ETag is a cache validator; it does not by itself establish an appropriate cache policy for personalized content. Select filter scope and cache directives for the actual responses your application serves.

Add environment and correlation headers

UseHostingEnvironment() adds X-Hosting-Environment unless its suppression predicate excludes the current environment. The default excludes Production.

UseCorrelationIdentifier() adds the X-Correlation-ID behavior. These are the current replacements for UseHostingEnvironmentHeader() and UseCorrelationIdentifierHeader().

Their position matters. In this pipeline, static-file middleware runs first and may finish the request before the Cuemon components execute. Place the header components earlier if static responses must participate too.

The original sample also called UseWellKnownLocations() from the separate WBPA project for certificate-related files. That project was not part of Cuemon, so the call is omitted from this Cuemon setup. Configure /.well-known/ handling where your current certificate tooling requires it.

The useful separation is unchanged: register dependencies and options before building the application, then assemble the request pipeline in the order that expresses the intended behavior.

Code with passion.

Timeline

These milestones explain the Cuemon APIs used by the walkthrough, rather than the deployment history of the old website. The earliest stable snapshot confirms existing functionality without assigning it a first-ever introduction date.

  1. v5.1.2019 2019-02-09

    MVC caching and assembly-based asset versioning were already available.

    The tagged source contains HttpCacheableFilter and the parameterless AddCacheBusting() shorthand in Cuemon.AspNetCore.Mvc. The shorthand selects AssemblyCacheBusting, matching the earlier setup described in this article.

  2. v6.0.0 2021-04-18

    Cache-busting registration moved out of the MVC-specific assembly.

    Cuemon.Extensions.AspNetCore exposes AddAssemblyCacheBusting() and AddDynamicCacheBusting() in its Configuration namespace. Registration now names the selected strategy explicitly, while the generic AddCacheBusting<T>() remains available.

  3. v6.1.0 2021-05-16

    The packaged tag helpers gained the current CDN naming and shared bases.

    CdnLinkTagHelper targets cdn-link and derives from LinkTagHelper<CdnTagHelperOptions>. The release also documents shared cache-busting bases and separate App tag helpers for application assets.

  4. v8.1.0 2024-02-11

    The MVC cache filter's response-state handling was corrected.

    The response-started check and cache-control handling moved outside the branch limited to cacheable object results. The filter's final execution decision therefore also applies to other MVC result types, including views.

  5. v10.7.0 2026-08-12

    Tag-helper base URLs gained an opt-in automatic mode.

    TagHelperBaseUrlMode.Automatic allows base URLs to be derived from the current HTTP request. Configured remains the default, which preserves the explicit CDN host configuration used in this walkthrough.

  6. v11.0.0 2026-11-11 (current)

    The setup uses the current ASP.NET Core package boundaries.

    Cache-busting registration remains in Cuemon.Extensions.AspNetCore, HttpCacheableFilter remains in Cuemon.AspNetCore.Mvc, and CDN tag helpers remain in Cuemon.AspNetCore.Razor.TagHelpers. The release adds .NET 11 targets and retains .NET 10 support for these web components.

Sources