A file provider wrapper for ASP.NET Core that enables runtime modification of static files. Useful for rewriting HTML base href attributes when hosting under a path base, while preserving proper HTTP caching headers.
When hosting ASP.NET Core applications (especially SPAs) under a path base like /myapp, you often need to dynamically rewrite the <base href="/"> tag in your HTML to match the deployment path. Traditional solutions either:
- Require build-time configuration (different builds for different deployments)
- Use middleware that breaks HTTP caching (loses ETags, LastModified headers)
- Manually copy and modify files on application startup
FileOverlay solves this by creating a transparent file provider overlay that:
- ✅ Modifies files at runtime
- ✅ Preserves all HTTP caching headers (ETags, LastModified)
- ✅ Works seamlessly with ASP.NET Core's static file middleware
- ✅ Supports any IFileProvider source
dotnet add package FileOverlayHere's a complete example showing how to rewrite the base href in your HTML files to use the application's PathBase:
using FileOverlay;
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
// Get the PathBase from configuration or environment
var pathBase = app.Configuration["PathBase"] ?? "/";
// Create an overlay that rewrites base href in index.html
var fileProvider = app.Environment.WebRootFileProvider.WithBaseHrefRewrite(
pathBase: pathBase,
"index.html" // Can specify multiple files: "index.html", "about.html", etc.
);
// Use the overlay file provider for static files
app.UseStaticFiles(new StaticFileOptions
{
FileProvider = fileProvider
});
app.Run();For a typical SPA setup with client-side routing, you'll want to use the full middleware pipeline with MapFallbackToFile:
using FileOverlay;
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
// Get the PathBase from configuration or environment
var pathBase = app.Configuration["PathBase"] ?? "/";
// Create an overlay that rewrites base href in index.html
var fileProvider = app.Environment.WebRootFileProvider.WithBaseHrefRewrite(
pathBase: pathBase,
"index.html"
);
// Optional (relevant if there are api endpoints that are registered)
app.UsePathBase(pathBase)
.UseRouting() // Must be called explicitly for PathBase to have effect, see https://andrewlock.net/using-pathbase-with-dotnet-6-webapplicationbuilder/#option-1-controlling-the-location-of-userouting-
app.UseDefaultFiles()
.UseStaticFiles(new StaticFileOptions
{
FileProvider = fileProvider
});
app.MapFallbackToFile("index.html", new StaticFileOptions
{
FileProvider = fileProvider
});
app.Run();This ensures that:
- Static files are served with the overlayed file provider
- Client-side routes (like
/products,/about) fall back to the transformedindex.html - The base href is correctly rewritten in all scenarios
If your index.html contains:
<!DOCTYPE html>
<html>
<head>
<base href="/" />
<title>My App</title>
</head>
<body>
<!-- Your app content -->
</body>
</html>And you set PathBase to /myapp, the served HTML will automatically become:
<!DOCTYPE html>
<html>
<head>
<base href="/myapp/" />
<title>My App</title>
</head>
<body>
<!-- Your app content -->
</body>
</html>For more complex scenarios, you can use the low-level API to create custom file transformations:
var overlay = new OverlayFileProvider(app.Environment.WebRootFileProvider);
// Create an overlay for a specific file
var indexFile = overlay.CreateOverlay("index.html");
// Apply custom transformations
indexFile.TransformContent(content =>
{
// Replace any placeholder with runtime values
content = content.Replace("{{API_URL}}", app.Configuration["ApiUrl"]);
content = content.Replace("{{VERSION}}", app.Configuration["Version"]);
return content;
});
// Use the overlay for serving static files
app.UseStaticFiles(new StaticFileOptions { FileProvider = overlay });- Overlay Creation: When you call
CreateOverlay(), FileOverlay creates a physical copy of the file in a temporary directory - Transformation: You can then transform the content using
TransformContent() - Transparent Serving: The overlay provider intercepts requests for overlayed files and serves the modified versions
- Cache Preservation: The overlay preserves the original file's
LastModifiedtimestamp, ensuring proper HTTP caching with ETags
Files that are not overlayed are served directly from the original provider without any overhead.
- Runtime Configuration: No need for different builds per environment
- Proper HTTP Caching: Maintains ETags and LastModified headers for optimal performance
- SPA Friendly: Perfect for SPAs deployed under path bases
- Flexible: Works with any
IFileProviderimplementation - Minimal Overhead: Only specified files are copied and modified
// App 1 at /app1
app.Map("/app1", app1 =>
{
var fileProvider = env.WebRootFileProvider.WithBaseHrefRewrite("/app1", "index.html");
app1.UseStaticFiles(new StaticFileOptions { FileProvider = fileProvider });
});
// App 2 at /app2
app.Map("/app2", app2 =>
{
var fileProvider = env.WebRootFileProvider.WithBaseHrefRewrite("/app2", "index.html");
app2.UseStaticFiles(new StaticFileOptions { FileProvider = fileProvider });
});MIT
Contributions are welcome! Please open an issue or submit a pull request on GitHub.