👁 Image
AspNetStatic 0.27.8

AspNetStatic

👁 Platform Support: ASP.NET Core 6.0+
👁 License: Apache 2
    👁 Build-And-Test

Transform ASP.NET Core into a Static Site Generator

Okay, so you want to create a static website. After doing some research, you learn that all the cool kids are using tools like Jekyll, Hugo, Gatsby, or Statiq. But what you also learn is that all of these tools require you to learn an entirely new way of constructing sites and pages. And this is when you'll wonder to yourself, as I did, Why!? I already know how to use ASP.NET Core to create websites; why do I need to learn & use a whole other stack just for SSG? Isn't there a better way that lets me use the tools and skills I already have?

Well, now there is!

Create a static site using ASP.NET Core

AspNetStatic lets you generate a static website with the same ASP.NET Core tools you love and use every day. Just add this package and tell it which routes (page, css, js, etc.) to process.

AspNetStatic works equally well with Blazor (SSR), Razor Pages, and MVC (controllers + views).

But wait, there's more!

AspNetStatic can also be used in a mixed mode configuration where some of the pages in your site are static html files (generated with the same _layout & page layers that define the look & feel of the rest of your site), while others remain dynamically generated per request. See Partial Static Site under Scenarios section below.

No Frameworks. No Engines. No Opinions!

Build your ASP.NET site the way you always have. AspNetStatic doesn't have any opinions about how you should structure your server-rendered site. AspNetStatic is not a framework. It's not a CMS. There's no blog engine. It has no templating system. AspNetStatic does just one thing; create static files for selected routes in your ASP.NET Core project. That means you can use whatever framework, component, package, or architectural style you like. Want to use a blog engine? No problem. Want to use a CMS? No problem. Want to create a documentation site using a markdown processor to render page content? No problem! AspNetStatic doesn't care; it will create optimized static files no matter how the content is produced by the server.

<br/>

Great. So how do I use it?

It's a piece of cake.

1. Add the Nuget Package to your ASP.NET Core project

   dotnet add package AspNetStatic
   

2. Specify the routes for which you want static files to be generated
   • Create an instance of StaticResourcesInfoProvider (or an object that derives from StaticResourcesInfoProviderBase or implements the IStaticResourcesInfoProvider interface)
   • Populate the PageResources and/or OtherResources collections
     • Set required Route property of each item
     • Set other properties as appropriate
   • Set other IStaticResourcesInfoProvider attributes as appropriate
   • Register it in the DI container

   builder.Services.AddSingleton<IStaticResourcesInfoProvider>(
    new StaticResourcesInfoProvider()
    .AddAllProjectRazorPages(builder.Environment) // from AspNetStaticContrib project
    .AddAllWebRootContent(builder.Environment)); // from AspNetStaticContrib project
   
   -- OR --
   
   builder.Services.AddSingleton<IStaticResourcesInfoProvider>(
    new StaticResourcesInfoProvider(
    new []
    {
    new PageResource("/"),
    new PageResource("/privacy"),
    new PageResource("/blog/articles/posts/1") { OutFile = "blog/post-1.html" },
    new PageResource("/blog/articles/posts/2") { OutFile = "blog/post-2-dark.html", Query = "?theme=dark" },
    new CssResource("/bootstrap/bootstrap.min.css") { OptimizationType = OptimizationType.None },
    new CssResource("/site.css"),
    new JsResource("/site.js"),
    new BinResource("/favicon.png")
    }));
   

3. Add a call to the AspNetStatic module in the app startup

   ...
   app.MapRazorPages();
   ...
   app.GenerateStaticContent(@"C:\SSG-Output-Folder");
   app.Run();
   

4. Run your app

   dotnet run
   

AspNetStatic is the EASY button for doing SSG with ASP.NET

You can use AspNetStatic in traditional SSG mode (generate files and exit the app), or in a 'partial-static site' mode. There is also an option to periodically regenerate the static content while your app is running. See the Scenarios section below for details.

<br/>

Routes

Keep the following in mind when specifying routes in the IStaticResourcesInfoProvider.PageResources collection.

• Routes must exclude the site's base URI (e.g. http:<span>//</span>localhost:5000, https:<span>//www</span>.example.com)
• As a rule, don't specify an 'index' page name; instead, opt for a route with a terminating slash (/ instead of /index).
• You can directly specify the pathname of the file to be generated for routes you add to the PageResources collection (see OutFile property). The only requirement is that the specified path be relative to the destination root folder. If you do not specify a value for OutFile, the pathname for the generated file will be determined as demonstrated below.
• You can specify route parameters for routes you add to the PageResources collection. The route parameters are treated as part of the route, and are used in constructing the output file pathname.
• You can specify a query string for routes you add to the PageResources collection (see Query property). You can specify the same Route with different Query values, but you will need to specify a unique OutFile value for each instance of that route.
• You can skip content optimization¹ or choose a specific optimization type for routes you add to the PageResources collection (see OptimizationType property). The default optimization type setting, OptimizationType.Auto, automatically applies the appropriate optimization.
• You can set the encoding for content written to output files for routes you add to the PageResources collection (see OutputEncoding property). Default is UTF8.

Routes vs. Generated Static Files (page resources)

Routes vs. Generated Static Files (non-page resources)

Fallback Middleware: Routes vs. Served Content

// Sample routes: /, /index, and /page
//-------------------------------------

// generated links: /, /index, and /page
builder.Services.AddRouting(
 options =>
 { // default configuration in ASP.NET Core
 options.AppendTrailingSlash = false;
 });
...
// fallback static pages: /index.html, /index.html, and /page.html
builder.Services.AddStaticPageFallback(
 cfg =>
 {
 cfg.AlwaysDefaultFile = false;
 });
...
// generated static pages: /index.html, /index.html, and /page.html
app.GenerateStaticContent(
 alwaysDefaultFile: false);

-- OR --

// generated links: /, /index/, and /page/
builder.Services.AddRouting(
 options =>
 {
 options.AppendTrailingSlash = true;
 });
...
// fallback static pages: /index.html, /index/index.html, and /page/index.html
builder.Services.AddStaticPageFallback(
 cfg =>
 {
 cfg.AlwaysDefaultFile = true;
 });
...
// generated static pages: /index.html, /index/index.html, and /page/index.html
app.GenerateStaticContent(
 alwaysDefaultFile: true);

<br/>

Scenarios

Static Site Generation (Standalone SSG)

In this scenario, you want to generate a completely static website (to host on Netlify or Azure/AWS storage, for instance). Once the static pages are generated, you will take the files in the destination folder and xcopy deploy them to your web host.

Sample Configuration 1:

• Specify any accessible folder as the destination-root for the generated static files.
• Generate a default file only for routes ending with a slash.
• Update the href attribute for <a> and <area> tags that refer to static pages (e.g. /page to /page.html).

  app.GenerateStaticContent(
   "../SSG_Output",
   exitWhenDone: true); // exit the app after static generation
  

Sample Configuration 2:

• Specify any accessible folder as the destination-root for the generated static files.
• Generate a default file for all routes (e.g. /page and /page/ to /page/index.html).
• Don't update the href attribute for <a> and <area> tags that refer to static pages.
• Use your web server's features to re-route requests (e.g. /page/ or /page/index to /page/index.html).

  // true when app is executed with one of the marker args, such as SSG.
  // dotnet run -- ssg
  var exitWhenDone = args.HasExitWhenDoneArg();
  
  app.GenerateStaticContent(
   @"C:\path\to\destination\root\folder",
   exitWhenDone: exitWhenDone,
   alwaysDefaultFile: true,
   dontUpdateLinks: true);
  

If you want to omit static-file generation while you're still developing the site, you can configure a launchSettings profile for SSG mode operation. To enable this, you would surround the GenerateStaticContent() call with an IF gate.

"profiles": {
 "SSG": {
 "commandName": "Project",
 "commandLineArgs": "ssg",
 "launchBrowser": false,
 "applicationUrl": "https://localhost:5000",
 }
}

Then, in the startup code (Program.cs)

if (args.HasExitWhenDoneArg())
{
 app.GenerateStaticContent(
 @"path\to\destination\root\folder",
 exitWhenDone: true,
 );
}

Now you can use the SSG profile to launch your app in SSG mode (to generate static content, then exit), and a differrent launch profile while you're in development mode, editing the site content. (The BlazorSSG sample demonstrates this approach.)

Partial Static Site

In this scenario, you want some of the pages in your ASP.NET Core app to be static, but still want other routes to be served as dynamic content per request (e.g. pages/views, JSON API's, etc.). When the app runs, static (.html) files will be generated for routes you specify. The website will then serve these static files for the specified routes, and dynamic content (as usual) for others.

The configuration options are generally the same as for a standalone static site, except the following differences:

• The destination root folder must be app.Environment.WebRoot (i.e. wwwroot).
• You must do one of the following (can do both):
  • Use the AspNetStatic fallback middleware.
  • Allow links in generated static files to be updated (href of <a> and <area> tags).
• Do not exit the app after static files are generated (obviously, right?)

Like this:

...
builder.Services.AddStaticPageFallback();
...
app.UseStaticPageFallback(); // re-route to the static file (page resources only)
app.UseStaticFiles();
...
app.UseRouting();
...
app.Map...();
...
app.GenerateStaticContent(
 app.Environment.WebRoot, // must specify wwwroot
 exitWhenDone: false, // don't exit after generating static files
 alwaysDefaultFile: true/false,
 dontUpdateLinks: false); // update links so they refer to static files
...
app.Run();

Periodic Regeneration

If the data used in the content of static files changes while the app is running, you can configure periodic regeneration by specifying a value for the regenerationInterval parameter in the GenerateStaticContent() call. This will result in static files being generated when the app starts, and then periodically based on the specified interval.

app.GenerateStaticContent(
 ...
 exitWhenDone: false,
 regenerationInterval: TimeSpan.FromHours(2) // re-generate static files every 2 hours
);

<br/>

Content Optimization

Before proceeding, let's clarify what an "optimizer" is in AspNetStatic. An optimizer is simply a component that performs some sort of processing on the content retrieved for a static resource (i.e. page, css, js, image, etc.) An optimizer is called by AspNetStatic after the content of a resource is retrieved, but just before that content is written to the destination file.

Enabling Optimization

The "optimizer" feature in AspNetStatic is enabled by default and requires no configuration to use. To disable the feature, pass true as the argument for the dontOptimizeContent parameter in the GenerateStaticContent call.

app.GenerateStaticContent(
 ...
 dontOptimizeContent: true);

This will prevent the IOptimizerSelector and any optimizers from being called.

Optimizer Selector

The optimizer to be executed by AspNetStatic for a given resource (page, css, etc.) is determined by the registered IOptimizerSelector component, which by default is DefaultOptimizerSelector.

An IOptimizerSelector implementation can select an optimizer based on the attributes of the resource (e.g. the resource type, its stated OptimizationType, the source or destination file extension or path).

DefaultOptimizerSelector uses the resource type and OptimizationType information to select an optimizer.

To use your own custom selector, implement the IOptimizerSelector interface and register it in the DI container.

public class MyCustomOptimizerSelector : IOptimizerSelector
{
 public IMarkupOptimizer SelectFor(PageResource pageResource, string outFilePathname) { ... }
 public ICssOptimizer SelectFor(CssResource cssResource, string outFilePathname) { ... }
 public IJsOptimizer SelectFor(JsResource jsResource, string outFilePathname) { ... }
 public IBinOptimizer SelectFor(BinResource binResource, string outFilePathname) { ... }
}
...
builder.Services.AddSingleton<IOptimizerSelector, MyCustomOptimizerSelector>();

builder.Services.AddDefaultOptimizers(); // register default optimizers & minifiers
builder.Services.AddSingleton<IJsMinifier, YuiJsMinifier>(); // override default minifier
builder.Services.AddSingleton<IMarkupOPtimizer, MyCustomMarkupOptimizer>()); // override default optimizer

Optimizers

AspNetStatic supports the following optimizer types:

• IMarkupOptimizer: Called when processing PageResource objects
• ICssOptimizer: Called when processing CssResource objects
• IJsOptimizer: Called when processing JsResource objects
• IBinOptimizer: Called when processing BinResource objects

AspNetStatic provides "default" implementations for these interfaces: DefaultMarkupOptimizer, DefaultCssOptimizer, and DefaultJsOptimizer. There is no default IBinOptimizer implementation.

To use a custom optimizer, implement (and register in DI) the relevant interface. You can derive and extend the "default" implementation, if you wish. For instance, if you want to perform some pre and post processing operations on CSS resources (in addition to the built-in minification), derive and extend the DefaultCssOptimizer, like so:

// OPTION 1: Implement from scratch

public MyCustomCssOptimizer : ICssOptimizer
{
 public CssOptimizerResult Execute(string content, ...)
 {
 // your custom processing here...
 }
}

// OPTION 2: inherit from DefaultCssOptimizer

public MyCustomCssOptimizer : DefaultCssOptimizer
{
 public override CssOptimizerResult Execute(string content, ...)
 {
 content = DoPreProcessing(content);
 var result = base.Execute(content, ...); // do usual minification
 result.OptimizedContent = DoPostProcessing(result.OptimizedContent);
 return result;
 }
 private string DoPreProcessing(string css) { ... }
 private string DoPostProcessing(string css) { ... }
}

// -- OPTION 3: create decorator over DefaultCssOptimizer

public MyCustomCssOptimizer(
 DefaultCssOptimizer defaultCssOptimizer) : 
 ICssOptimizer
{
 public CssOptimizerResult Execute(string content, ...)
 {
 content = DoPreProcessing(content);
 var result = defaultCssOptimizer.Execute(content, ...); // do usual minification
 result.OptimizedContent = DoPostProcessing(result.OptimizedContent);
 return result;
 }
 private string DoPreProcessing(string css) { ... }
 private string DoPostProcessing(string css) { ... }
}

...

// register default optimizers & minifiers
builder.Services.AddDefaultOptimizers(); 

// Register your custom implementation...
builder.Services.AddSingleton<ICssOptimizer, MyCustomCssOptimizer>();

// Call following method if you want DefaultCssOptimizer to use 
// the AspNetStatic defaults for these services, otherwise it will 
// use the WebMarkupMin internal defaults.
// This call is not needed if you've already called AddDefaultOptimizers.
builder.Services.AddDefaultMinifiers(); 

Configuring Default Optimizers

The default optimizers provided by AspNetStatic (DefaultMarkupOptimizer, DefaultCssOptimizer, and DefaultJsOptimizer) use the WebMarkupMin package to minify HTML, CSS and JS content. To override the default minification settings used by AspNetStatic, register the appropriate objects as described below.

AspNetStatic uses the default WebMarkupMin configuration settings (determined internally by WebMarkupMin) for minifying HTML, XHTML, and XML content. To override this behavior, register one or more of the following configuration objects:

using WebMarkupMin.Core;

// HTML minifier settings
builder.Services.AddSingleton(
 sp => new HtmlMinificationSettings()
 {
 ...
 });

// XHTML minifier settings
builder.Services.AddSingleton(
 sp => new XhtmlMinificationSettings()
 {
 ...
 });

// XML minifier settings
builder.Services.AddSingleton(
 sp => new XmlMinificationSettings()
 {
 ...
 });

AspNetStatic uses KristensenCssMinifier for ICssMinifier, and CrockfordJsMinifier for IJsMinifier by default. To override this behavior, register alternative implementations:

using WebMarkupMin.Core;

// ICssMinifier
builder.Services.AddSingleton<ICssMinifier>(
 sp => new YuiCssMinifier(...));

// IJsMinifier
builder.Services.AddSingleton<IJsMinifier>(
 sp => new YuiJsMinifier(...));

<br/>

License

Apache 2.0

<br/>

If you like this project, or find it useful, please give it a star. Thank you.