Better SWA docs

[javiercn]

We will want to cover better the MSBuild switches on the csproj that can be used to tweak the build process

[guardrex]

The API/config on the other issue will be placed per my work on dotnet/AspNetCore.Docs#35810.

I'll ping for review when the PR goes up, hopefully later today (Wed, 8/20).

[javiercn]

Here is a collection of all the MSBuild properties.

Property	Description
EnableDefaultCompressedItems	Enables default compression include/exclude patterns
CompressionIncludePatterns	Semicolon-separated list of file patterns to include for compression
CompressionExcludePatterns	Semicolon-separated list of file patterns to exclude from compression
EnableDefaultCompressionFormats	Enables default compression formats (gzip and brotli)
BuildCompressionFormats	Compression formats to use during build
PublishCompressionFormats	Compression formats to use during publish
DisableBuildCompression	Disables compression during build
CompressDiscoveredAssetsDuringBuild	Compresses discovered assets during build
BrotliCompressionLevel	Compression level for Brotli algorithm
LinkAlternativeRepresentationsToOriginalResource	How to link compressed assets to original resources
StaticWebAssetBuildCompressAllAssets	Compresses all assets during build (not just discovered/computed)
StaticWebAssetPublishCompressAllAssets	Compresses all assets during publish (not just discovered/computed)

Property	Description
StaticWebAssetBasePath	Base URL path for all the assets in a library
StaticWebAssetsFingerprintContent	Enables content fingerprinting for cache busting
StaticWebAssetFingerprintingEnabled	Enables fingerprinting feature for static web assets
StaticWebAssetsCacheDefineStaticWebAssetsEnabled	Enables caching for static web asset definitions
StaticWebAssetBuildManifestPath	Path to the build manifest JSON file
StaticWebAssetsBuildManifestCacheFilePath	Path to the build manifest cache file
StaticWebAssetEndpointExclusionPattern	Pattern for excluding endpoints

Item Group	Description	Metadata
StaticWebAssetContentTypeMapping	Maps file patterns to content types and cache headers for endpoints	Pattern, Cache
StaticWebAssetFingerprintPattern	Defines patterns for applying fingerprints to static web assets for cache busting	Pattern, Expression

Metadata Descriptions

Pattern: A glob pattern used to match files. For StaticWebAssetContentTypeMapping, it matches files to determine their content type (e.g., *.js for JavaScript files). For StaticWebAssetFingerprintPattern, it identifies multi-extension files that need special fingerprinting treatment (e.g., *.lib.module.js).

Cache: Specifies the Cache-Control header value for the matched content type. This controls browser caching behavior (e.g., max-age=3600, must-revalidate for media files).

Expression: Defines how the fingerprint is inserted into the filename. The default is #[.{fingerprint}] which inserts the fingerprint before the extension.

---

Here are the runtime config options

Configuration Key	Description
ReloadStaticAssetsAtRuntime	Enables dev-time hot reloading of static assets: serves modified wwwroot files (recomputes ETag, re-compresses if needed) instead of build-time manifest versions. Defaults to enabled only when serving a build manifest unless explicitly set.
DisableStaticAssetNotFoundRuntimeFallback	When true, suppresses the fallback endpoint that serves newly added files not present in the build manifest. When false/absent, a file-exists-checked {**path} fallback (GET/HEAD) logs a warning and serves the file with a computed ETag.
EnableStaticAssetsDevelopmentCaching	When true, preserves original Cache-Control headers on asset descriptors. When false/absent, rewrites any Cache-Control header to no-cache to avoid aggressive client caching during development.
EnableStaticAssetsDevelopmentIntegrity	When true, keeps integrity properties on asset descriptors. When false/absent, removes any integrity property to prevent mismatches when files change during development.

---

Here are recipes for common scenarios

Pipeline execution:

If you want to avoid running the entire middleware pipeline after a static asset is served (similar to how UseStaticFiles works), you can call Shortcircuit() after MapStaticAssets as follows:

app.MapStaticAssets()
   .ShortCircuit();

This will immediately execute the endpoint and return the response, preventing any other middleware from executing for static asset requests.

Auth fallback policy

You can add AllowAnonymous to the files you want to serve without authentication.

app.MapStaticAssets()
    .Add(endpointBuilder => endpointBuilder.Metadata.Add(new AllowAnonymousAttribute()));

This allows you to setup a fallback policy like:

builder.Services.AddAuthorization(o =>
{
    o.FallbackPolicy = new Microsoft.AspNetCore.Authorization.AuthorizationPolicyBuilder()
        .RequireAuthenticatedUser()
        .Build();
});

And auth will be bypassed for static assets.

Large collection of assets

When dealing with large collections of assets (~1000) it is best to use a bundler to reduce the final number of assets served by the app, or to combine MapStaticAssets with UseStaticFiles. MapStaticAssets eagerly loads the precomputed metadata captured during the build process for the resources in order to support compression, caching and fingerprinting. That comes at a cost of more memory usage by the app. For assets that are frequently accessed, that makes sense, but for assets that aren't the trade-off might not be worth it.

If you don't use bundling, we recommend you combine MapStaticAssets with UseStaticFiles in those situations as follows:

Project file configuration (.csproj):

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <StaticWebAssetEndpointExclusionPattern>$(StaticWebAssetEndpointExclusionPattern);lib/icons/**</StaticWebAssetEndpointExclusionPattern>
  </PropertyGroup>

</Project>

Program.cs configuration:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container
builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();

Handles the excluded files (lib/icons/*) and any other files not covered by MapStaticAssets
app.UseStaticFiles();

app.UseAuthorization();

// MapStaticAssets handles critical application files (CSS, JS, images)
app.MapStaticAssets();

...

app.Run();

StaticWebAssetEndpointExclusionPattern) is used to filter out endpoints from the final manifest. Those files then get served by UseStaticFiles but don't benefit from compression, caching or fingerprinting.

[guardrex]

Pipeline execution and Auth fallback policy are already on the PR.

I have some tweaks to make on Large collection of assets. It's on the PR, but you made some new remarks ☝️ to roll into it.

MSBuild properties/Metadata Descriptions and runtime config options will need work. In fact, I can't get that all done today (Friday), so it will be addressed on Monday.

I'll have Dan look first, so we can get the overall organization right. Then, I'll ping you for technical review.