ASP.NET Core Web Optimizer

WebOptimizer sets up a transformation pipeline for static files (CSS and JS) that runs at runtime.

Key characteristics:

• On-demand generation: No output is generated until the first time a file is requested by a browser.
• In-memory storage: Transformed files are stored in memory and served quickly; no files are written to disk.
• Pipeline orchestration: Files can undergo multiple transformations (e.g., minification $\rightarrow$ fingerprinting $\rightarrow$ inlining) before being sent to the browser.
• High performance: Uses server-side and client-side caching to ensure minimal overhead.

If you provide an absolute URL to the cdnUrl option, the Web Optimizer Tag Helpers will automatically prepend this URL to any <script> or <link> tags on your page.

Example: If cdnUrl is set to http://my-cdn.com, the following HTML:

<script src="/js/file.js"></script>

will be rendered as:

<script src="http://my-cdn.com/js/file.js"></script>

<script src="/js/file.js"></script>
<!-- Becomes -->
<script src="http://my-cdn.com/js/file.js"></script>

You can manually compose the WebOptimizer pipeline by chaining methods to define how files are processed. This allows you to create custom bundling and minification workflows for non-standard file extensions or specific content types.

To create a bundle, use AddBundle(path, contentType, pattern) as the starting point. You can then chain processing steps such as .AdjustRelativePaths(), .Concatenate(), .FingerprintUrls(), and specific minifiers like .MinifyCss() or .MinifyJs().

services.AddWebOptimizer(pipeline =>
{
    pipeline.AddBundle("/bundle.css", "text/css; charset=utf-8", "/dir/*.txt")
            .AdjustRelativePaths()
            .Concatenate()
            .FingerprintUrls()
            .MinifyCss();
});

When using services.AddResponseCompression, WebOptimizer's cache-busted assets might be excluded because the Content-Type is changed to text/javascript, which is not in the default allowed list for some ASP.NET Core versions.

For ASP.NET Core 7.0 or later: Support for text/javascript is included by default. No action is required.

For versions prior to 7.0: You must manually add text/javascript to the allowed MIME types:

services.AddResponseCompression(options => {
    options.MimeTypes = ResponseCompressionDefaults.MimeTypes.Concat(
        new[] { "text/javascript"}
    );
});

Note: app.UseResponseCompression() must be called before app.UseWebOptimizer() in the Configure method.

Bundling combines multiple source files into a single output file, which is then automatically minified. The output is kept in memory.

Create a CSS bundle:

services.AddWebOptimizer(pipeline =>
{
    pipeline.AddCssBundle("/css/bundle.css", "css/a.css", "css/b.css");
});

Create a bundle using globbing patterns:

services.AddWebOptimizer(pipeline =>
{
    pipeline.AddCssBundle("/css/bundle.css", "css/**/*.css");
});

Usage in HTML: Update your <link> or <script> tags to point to the bundle route:

<link rel="stylesheet" href="/css/bundle.css" />

The AddBundle method is the fundamental building block for creating bundles in WebOptimizer. It is the underlying method used by convenience methods like AddJsBundle and AddCssBundle.

Signature Pattern: AddBundle(string path, string contentType, params string[] filePatterns)

• path: The URL path where the resulting bundle will be served.
• contentType: The MIME type for the output file (e.g., "text/css; charset=utf-8").
• filePatterns: A list of glob patterns representing the source files to be included in the bundle.

By default, bundles do not generate source maps. To enable them, pass a JsSettings object to the AddJavaScriptBundle method:

services.AddWebOptimizer(pipeline =>
{
    pipeline.AddJavaScriptBundle("/js/scripts.js",
        new WebOptimizer.Processors.JsSettings { GenerateSourceMap = true },
        "a.js", "b.js");
});

By default, source files are relative to the Web Root (wwwroot).

Use the Content Root: To use files from the project root (e.g., node_modules), use .UseContentRoot():

services.AddWebOptimizer(pipeline =>
{
    pipeline.AddCssBundle("/css/bundle.css", "node_modules/jquery/dist/*.js")
            .UseContentRoot();
});

Use a custom File Provider: To use a completely custom IFileProvider:

services.AddWebOptimizer(pipeline =>
{
    var provider = new Microsoft.Extensions.FileProviders.PhysicalFileProvider(@"C:\path\to\my\root\folder");
    pipeline.AddJavaScriptBundle("/js/scripts.js", "a.js", "b.js")
        .UseFileProvider(provider);
});

pipeline.AddCssBundle("/css/bundle.css", "node_modules/jquery/dist/*.js").UseContentRoot();

You can control which files are automatically minified by interacting with the pipeline in AddWebOptimizer. Paths are relative to the wwwroot folder.

Minify specific JavaScript files:

services.AddWebOptimizer(pipeline =>
{
    pipeline.MinifyJsFiles("js/a.js", "js/b.js", "js/c.js");
});

Minify CSS files using globbing patterns:

services.AddWebOptimizer(pipeline =>
{
    pipeline.MinifyCssFiles("css/**/*.css");
});

Note: WebOptimizer uses NUglify under the hood.

services.AddWebOptimizer(pipeline =>
{
    pipeline.MinifyJsFiles("js/a.js", "js/b.js");
    pipeline.MinifyCssFiles("css/**/*.css");
});