ASP.NET Core Configuration

Configuration reference for ModPageSpeed ASP.NET Core middleware. appsettings.json options, hot reload, environment variables, and common patterns.

All configuration uses standard ASP.NET Core configuration: appsettings.json, environment variables, or any IConfiguration provider. No custom config files. No XML. Just the patterns you already know.

Basic configuration

Add a PageSpeed section to your appsettings.json:

{
  "PageSpeed": {
    "Enabled": true,
    "RewriteLevel": "CoreFilters",
    "EnabledFilters": [],
    "DisabledFilters": [],
    "StatisticsEnabled": true,
    "ConsolePath": "/pagespeed-console"
  }
}

Options

Option	Type	Default	Description
`Enabled`	bool	`true`	Master switch. When false, the middleware passes through all responses unchanged.
`RewriteLevel`	string	`CoreFilters`	Base set of filters. `PassThrough` (none), `CoreFilters` (recommended), or `OptimizeForBandwidth` (safe for all content).
`EnabledFilters`	string[]	`[]`	Additional filters to enable on top of the rewrite level.
`DisabledFilters`	string[]	`[]`	Filters to disable from the rewrite level set.
`StatisticsEnabled`	bool	`true`	Enable internal statistics tracking for the console.
`ConsolePath`	string	`/pagespeed-console`	URL path for the built-in diagnostic console.
`CachePath`	string	`pagespeed-cache`	Directory for the on-disk optimization cache. Set an explicit path for containers or persistent volumes.

Hot reload

Configuration changes are picked up automatically through ASP.NET Core’s IOptionsMonitor<T> pattern. Edit appsettings.json while the application is running — changes take effect on the next request. No restart required.

This includes enabling/disabling filters, changing the rewrite level, and toggling the master switch. Cache contents are preserved across configuration changes.

Environment-specific configuration

Use ASP.NET Core’s standard environment layering. Create appsettings.Development.json to override settings during development:

{
  "PageSpeed": {
    "RewriteLevel": "PassThrough",
    "StatisticsEnabled": true
  }
}

This disables optimization in development while keeping the console available for inspection. Production uses the base appsettings.json with full optimization enabled.

Environment variables

All options can be set via environment variables using the standard ASP.NET Core double-underscore convention:

PageSpeed__Enabled=false
PageSpeed__RewriteLevel=OptimizeForBandwidth

Environment variables take precedence over appsettings.json, following ASP.NET Core’s standard configuration precedence.

Common filters

Filters included in CoreFilters are enabled by default. Add others via EnabledFilters.

Filter	In CoreFilters	What it does
`rewrite_images`	Yes	Optimizes images: format conversion, quality tuning, responsive srcsets
`rewrite_css`	Yes	Minifies CSS, combines files, rewrites URLs
`rewrite_javascript`	Yes	Minifies JavaScript, combines files
`prioritize_critical_css`	No	Inlines above-the-fold CSS, defers the rest
`lazyload_images`	No	Adds lazy-loading to below-the-fold images
`defer_javascript`	No	Defers JavaScript execution until after page load
`convert_jpeg_to_webp`	Yes	Serves WebP variant to supporting browsers

For the full filter list, see the ModPageSpeed filter documentation.

Cache path

Optimized resources are stored in a memory-mapped cache on disk. By default, the cache is created in a pagespeed-cache directory relative to the working directory. In containers or production deployments, set an explicit path on a persistent volume:

{
  "PageSpeed": {
    "Enabled": true,
    "RewriteLevel": "CoreFilters",
    "CachePath": "/data/pagespeed-cache",
    "StatisticsEnabled": true,
    "ConsolePath": "/pagespeed-console"
  }
}

The cache directory must be writable by the application process. On Linux, the cache uses memory-mapped I/O for zero-copy serving of cached variants.

Health checks

PageSpeed registers an ASP.NET Core health check that verifies the native library initialized successfully. Add the standard health check middleware to expose it:

app.MapHealthChecks("/healthz");

// PageSpeed registers its own health check automatically.
// It reports unhealthy if the native library fails to initialize.

The health check reports Healthy when the native library is loaded and the cache is accessible. Use this endpoint for container orchestration liveness probes.

Common patterns

Disable optimization for specific paths

PageSpeed optimizes all HTML responses by default. To exclude paths (e.g. an API or webhook endpoint), use standard ASP.NET Core middleware ordering — place UsePageSpeed() after the endpoint routing for those paths, or use MapWhen to conditionally skip the middleware.

Aggressive image optimization

For image-heavy sites, enable additional image filters beyond CoreFilters:

"EnabledFilters": ["lazyload_images", "resize_images", "prioritize_critical_css"]

Bandwidth-safe mode

If you want optimization without altering HTML structure (no rewritten URLs, no inlined CSS), use OptimizeForBandwidth. This applies only lossless compression and format conversion — safe for any content, including sites with strict CSP policies.