Skip to main content

ASP.NET Core Getting Started

Install ModPageSpeed as ASP.NET Core middleware via NuGet. Same optimization pipeline, no nginx required.

ModPageSpeed runs inside your ASP.NET Core pipeline as middleware. Same optimization pipeline as the nginx integration — image transcoding, CSS/JS minification, critical CSS — but via P/Invoke to the native C/C++ library. No reverse proxy. No sidecar. Just a NuGet package.

Prerequisites

  1. .NET 9 SDK or later — dotnet.microsoft.com
  2. Supported platform: Linux x64, macOS ARM64 (Apple Silicon), or Windows x64
  3. An ASP.NET Core application that serves HTML responses (Razor Pages, MVC, Blazor Server, or minimal APIs returning HTML)

Install the package

The meta-package pulls the correct native library for your platform automatically.

dotnet add package WeAmp.PageSpeed.AspNetCore --prerelease

This installs three packages: the managed middleware, the core abstractions, and the platform-specific native library (linux-x64, osx-arm64, or win-x64).

Add to your pipeline

Register PageSpeed services and add the middleware to your request pipeline.

using WeAmp.PageSpeed.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

// Register PageSpeed services — reads config from appsettings.json
builder.Services.AddPageSpeed(builder.Configuration);

var app = builder.Build();

// Add PageSpeed middleware — should be early in the pipeline
app.UsePageSpeed();

app.MapStaticAssets();
app.MapRazorPages();

app.Run();

Place UsePageSpeed() before any middleware that writes the response body. It needs to intercept responses before they reach the client.

Configure via appsettings.json

Add a PageSpeed section to your appsettings.json. A minimal configuration:

{
  "PageSpeed": {
    "Enabled": true,
    "RewriteLevel": "CoreFilters"
  }
}

See the configuration reference for all options.

Verify it works

Run your application and check for the X-PageSpeed response header.

dotnet run

Check the terminal output for the URL your app is listening on (e.g. http://localhost:5123), then in another terminal:

curl -I http://localhost:<port>

Look for this header in the response:

X-PageSpeed: WeAmp.PageSpeed/0.1.0-preview.1

If the header is present, PageSpeed is active and optimizing responses. View the HTML source to see rewritten image tags, inlined CSS, and deferred scripts.

Preview limitations

This is a preview release. Known limitations:

  • AVIF encoding is disabled on Windows (WebP and JPEG still work)
  • Cache invalidation notifications are stubbed on Windows
  • No licensing enforcement during preview — the preview is free to use
  • API surface may change before GA

Next steps