For static assets included in an ASP.NET Core app’s build or publish output, use MapStaticAssets: its build-time pipeline prepares compressed representations rather than compressing a file on each request. Use UseStaticFiles for files outside that asset pipeline, such as files served through a custom provider. Adding UseStaticFiles alone does not make static files negotiate Brotli or gzip.
Choose the serving approach that matches your assets
| Approach | Best fit | Compression behavior | Other considerations |
|---|---|---|---|
MapStaticAssets |
Assets known to the build or publish pipeline, such as the app’s static web assets and assets from referenced projects. | Microsoft documents gzip precompression at build time and both gzip and Brotli precompression during publish. | The pipeline can also provide content fingerprints, ETags, and immutable-cache metadata. |
UseStaticFiles |
Files outside the build-time asset graph, including custom disk locations, custom file providers, and embedded resources. | Static File Middleware does not itself compress static files or negotiate precompressed variants. | Use it when the source or provider requires it; plan separately for compression and cache behavior. |
| Response Compression Middleware | Responses that should be compressed at request time, where the middleware and its configured providers apply. | Negotiates based on the request’s Accept-Encoding; Brotli is preferred when supported, with gzip as fallback. |
The response identifies the chosen encoding and varies on Accept-Encoding. Middleware order, MIME types, payload size, and HTTPS security all matter. |
MapStaticAssets combines build- or publish-time asset information with a runtime component that uses it to serve files efficiently. It is therefore the natural choice for assets the app already knows about. The exact compression behavior depends on the stage: Microsoft documents gzip during development/build and gzip plus Brotli during publish.
These approaches solve different problems. Build-time asset compression prepares static representations ahead of requests. Response Compression Middleware applies runtime compression to eligible responses. Static File Middleware serves files but does not create compressed versions just because a matching .br or .gz file exists.
How request-time compression negotiation works
With Response Compression Middleware active, the browser advertises supported encodings in Accept-Encoding. When Brotli is supported, the middleware prefers it; gzip is the fallback. The server marks the selected representation with Content-Encoding and adds Vary: Accept-Encoding so caches distinguish compressed and uncompressed responses.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minute#1 Best Overall
The default compression providers are Brotli and gzip, unless the application explicitly replaces the provider collection. Middleware order also matters: place UseResponseCompression before middleware that generates or compresses the responses it should handle. This is runtime negotiation, not a way to make UseStaticFiles automatically select sibling .br or .gz files.
Configure the pipeline for the files you serve
- For ordinary app assets: use
MapStaticAssetsfor files handled by the build/publish static-asset pipeline. Confirm the target framework supports the API before adopting it; its availability is framework-version dependent. - For external or custom sources: retain
UseStaticFileswhen files come from a location or provider outside that pipeline. Do not assume the middleware will compress them or negotiate precompressed siblings. - For runtime-compressed responses: register response compression services and configure any needed providers and MIME types. In the request pipeline, put
UseResponseCompressionbefore middleware whose responses should be compressed. - For verification: request the same asset with and without
Accept-Encodingvalues such asbrandgzip. InspectContent-EncodingandVaryin the response using browser developer tools or an HTTP client. - For caching: use fingerprinted URLs or an equivalent cache-invalidation strategy so a deployment cannot leave clients using stale asset bytes.
Check whether compression is worthwhile and safe
- Consider MIME type: limit runtime compression to suitable content types rather than enabling it indiscriminately.
- Check payload size: Microsoft warns that compressing small files can make the result larger. Test representative assets instead of assuming every file benefits.
- Account for HTTPS security: Microsoft documents security considerations for enabling compression over HTTPS. Review those risks against the responses and data your application serves.
- Keep cache variants distinct: when request-time negotiation selects encodings,
Vary: Accept-Encodingis important for caches that might otherwise serve the wrong representation.
Why a static file may not be served as Brotli
- Only
UseStaticFilesis configured: this middleware does not compress static files. A pre-existing.brfile is not, by itself, evidence that the middleware will negotiate and serve it for a request to the original asset URL. - The asset is outside the build-time pipeline:
MapStaticAssetsis intended for assets known to that pipeline. Use the appropriate file provider for external sources and arrange compression behavior separately. - Request-time middleware is absent or ordered too late: for runtime compression, confirm
UseResponseCompressionis configured before the middleware producing the response. - The request and response do not show negotiation: send an
Accept-Encodingheader that includes Brotli, then inspect whether the response containsContent-Encoding: brandVary: Accept-Encoding. If Brotli is not supported by the client, gzip may be selected instead.
Microsoft’s guidance is explicit: “Static files aren’t compressed by static file middleware.” Treat a missing Brotli response as a question of which middleware serves the asset and whether build-time preparation or runtime negotiation applies—not simply whether a compressed file exists beside it.
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
