AspNetStatic

When adding routes to the IStaticResourcesInfoProvider.PageResources collection, follow these rules:

• Base URI: Routes must exclude the site's base URI (e.g., do not include http://localhost:5000 or https://www.example.com).
• Index Pages: Avoid specifying an 'index' page name. Instead, use a route with a terminating slash (e.g., / instead of /index).
• Output Files (OutFile): You can specify a custom pathname for the generated file. This path must be relative to the destination root folder. If left empty, the pathname is determined automatically based on the route and the AlwaysDefaultFile setting.
• Route Parameters: Parameters are treated as part of the route and are used to construct the output file pathname.
• Query Strings (Query): You can specify a Query property. To use the same Route with different query values, you must provide a unique OutFile for each instance.
• Optimization (OptimizationType): You can skip optimization or choose a specific type via the OptimizationType property. The default is OptimizationType.Auto.
• Encoding (OutputEncoding): You can set the encoding for output files. The default is UTF8.

These rules also apply to OtherResources (CSS, JavaScript, and binary files).

The mapping from a URL (route + query) to a physical file on disk depends on the resource type and the AlwaysDefaultFile setting.

Page Resources (PageResource)

For page resources, the mapping depends on whether AlwaysDefaultFile is true or false:

Non-Page Resources (CssResource, JsResource, BinResource)

For these types, AlwaysDefaultFile is not applicable. The mapping is direct:

A Partial Static Site allows some routes to be served as static .html files while others remain dynamic (e.g., APIs or views).

Requirements for Partial SSG:

1. The destination root must be app.Environment.WebRoot (the wwwroot folder).
2. exitWhenDone must be set to false so the app continues running.
3. You must either use the UseStaticPageFallback middleware or allow the generator to update links in <a> and <area> tags.

Implementation Steps:

1. Register services: builder.Services.AddStaticPageFallback();
2. Use fallback middleware: app.UseStaticPageFallback(); (this re-routes requests to generated static files for routes in the PageResources collection).
3. Use standard static files: app.UseStaticFiles();
4. Call app.GenerateStaticContent(...) with app.Environment.WebRoot as the destination.

// 1. Register services
builder.Services.AddStaticPageFallback();

// ... inside app configuration ...

// 2. Use fallback middleware (re-routes to static files)
app.UseStaticPageFallback();

// 3. Standard static files middleware
app.UseStaticFiles();

app.UseRouting();

// ... map routes ...

// 4. Generate content to wwwroot
app.GenerateStaticContent(
  app.Environment.WebRoot,
  exitWhenDone: false,
  alwaysDefaultFile: true,
  dontUpdateLinks: false);

app.Run();

To transition from manual resource management to using Resource Locators, follow these steps:

1. Register the extension: Call builder.Services.AddAspNetStaticContribStekeblad(Action<ContribStekebladOptions>) and enable the desired locators in the options action.
2. Update the Provider: Instead of StaticResourcesInfoProvider, use or derive from LocatingStaticResourcesInfoProvider as your IStaticResourcesInfoProvider implementation.
3. Add Locators: Use AddResourceLocator or the convenience extension methods (e.g., .AddSitemapLocator()) on the provider.
4. Synchronize Execution: You must call app.LocateStaticResources(EventWaitHandle) before app.GenerateStaticContent(...).

CRITICAL: The EventWaitHandle instance passed to LocateStaticResources must be the same instance passed to app.GenerateStaticContent(..., processStartSignal: signal). This ensures the static generator waits for discovery to complete, preventing concurrency exceptions.

// 1. Enable locators in services
builder.Services.AddAspNetStaticContribStekeblad(opts => 
{
    opts.RegisterSitemapResourceLocator = true;
});

// 2. Use LocatingStaticResourcesInfoProvider and add locators
builder.Services.AddSingleton<IStaticResourcesInfoProvider>( 
    new LocatingStaticResourcesInfoProvider()
        .AddSitemapLocator()
        .Add(builder.Environment.GetWebRootCssResources(["**/site.css"]))
);

// ...

// 3. Create a shared signal
var signal = new EventWaitHandle(false, EventResetMode.ManualReset);

// 4. Tell the app to locate resources using the signal
app.LocateStaticResources(signal);

// 5. Pass the SAME signal to GenerateStaticContent
app.GenerateStaticContent(
    app.Environment.WebRootPath,
    // ... other params
    signalTimeoutSeconds: 60, 
    processStartSignal: signal);

To tell AspNetStatic which routes to process, you must implement or configure an IStaticResourcesInfoProvider. You can do this by creating an instance of StaticResourcesInfoProvider (which derives from StaticResourcesInfoProviderBase) and populating its resource collections.

Resource Types

• PageResource: For HTML pages. You can specify the Route and an optional OutFile or Query string.
• CssResource: For CSS files. Supports an OptimizationType property.
• JsResource: For JavaScript files.
• BinResource: For binary assets like images or favicons.

Registration

Register the provider in your DI container (typically in Program.cs) as a singleton.

// Example 1: Using extension methods from AspNetStaticContrib
builder.Services.AddSingleton<IStaticResourcesInfoProvider>(
    new StaticResourcesInfoProvider()
      .AddAllProjectRazorPages(builder.Environment)
      .AddAllWebRootContent(builder.Environment));

// Example 2: Manual configuration of specific routes
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")
    }));

Use GenerateStaticContent to create a completely static website intended for hosting on services like Netlify, Azure, or AWS storage. You can choose between two primary configuration patterns:

Pattern 1: Slash-only default files with link updates

• Generates a default file (e.g., index.html) only for routes ending in a slash.
• Automatically updates href attributes in <a> and <area> tags to point to the new static file paths (e.g., changing /page to /page.html).
• Best for: Simple deployments where you want the generator to handle link integrity.

Pattern 2: Full default files with un-updated links

• Generates a default file for all routes (e.g., /page/ becomes /page/index.html).
• Does not update href attributes in <a> and <area> tags.
• Requires your web server to handle re-routing (e.g., mapping /page/ to /page/index.html).
• Best for: Environments where you have fine-grained control over server routing.

// Pattern 1: Slash-only default files + link updates
app.GenerateStaticContent(
  "../SSG_Output",
  exitWhenDone: true);

// Pattern 2: Full default files + no link updates
// Note: exitWhenDone is often controlled by a CLI argument in SSG mode
app.GenerateStaticContent(
  @"C:\path\to\destination\root\folder",
  exitWhenDone: exitWhenDone,
  alwaysDefaultFile: true,
  dontUpdateLinks: true);