Edit

ASP.NET Core Blazor static files

  • Article

Note

This isn't the latest version of this article. To switch to the latest, use the ASP.NET Core version selector at the top of the table of contents.

Version selector

If the selector isn't visible in a narrow browser window, widen the window or select the vertical ellipsis (⋮) > Table of contents.

Table of contents selector

This article describes the configuration for serving static files in Blazor apps.

For more information on solutions in sections that apply to hosted Blazor WebAssembly apps, see Tooling for ASP.NET Core Blazor.

Static File Middleware

This section applies to Blazor Server apps and the Server app of a hosted Blazor WebAssembly solution.

Configure Static File Middleware to serve static assets to clients by calling UseStaticFiles in the app's request processing pipeline. For more information, see Static files in ASP.NET Core.

Static files in non-Development environments for Blazor Server apps

This section applies to Blazor Server apps.

In Blazor Server apps run locally, static web assets are only enabled by default in the Development environment. To enable static files for environments other than Development during local development and testing (for example, Staging), call UseStaticWebAssets on the WebApplicationBuilder in Program.cs.

Warning

Call UseStaticWebAssets for the exact environment to prevent activating the feature in production, as it serves files from separate locations on disk other than from the project if called in a production environment. The example in this section checks for the Staging environment by calling IsStaging.

if (builder.Environment.IsStaging())
{
    builder.WebHost.UseStaticWebAssets();
}

Static web asset base path

This section applies to standalone Blazor WebAssembly apps and hosted Blazor WebAssembly solutions.

By default, publishing a Blazor WebAssembly app places the app's static assets, including Blazor framework files (_framework folder assets), at the root path (/) in published output. The <StaticWebAssetBasePath> property specified in the project file (.csproj) sets the base path to a non-root path:

<PropertyGroup>
  <StaticWebAssetBasePath>{PATH}</StaticWebAssetBasePath>
</PropertyGroup>

In the preceding example, the {PATH} placeholder is the path.

The <StaticWebAssetBasePath> property is most commonly used to control the paths to published static assets of multiple Blazor WebAssembly apps in a single hosted deployment. For more information, see Multiple hosted ASP.NET Core Blazor WebAssembly apps. The property is also effective in standalone Blazor WebAssembly apps.

Without setting the <StaticWebAssetBasePath> property, the client app of a hosted solution or a standalone app is published at the following paths:

  • In the Server project of a hosted Blazor WebAssembly solution: /BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/
  • In a standalone Blazor WebAssembly app: /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/

In the preceding examples, the {TFM} placeholder is the Target Framework Moniker (TFM) (for example, net6.0).

If the <StaticWebAssetBasePath> property in the Client project of a hosted Blazor WebAssembly app or in a standalone Blazor WebAssembly app sets the published static asset path to app1, the root path to the app in published output is /app1.

In the Client app's project file (.csproj) or the standalone Blazor WebAssembly app's project file (.csproj):

<PropertyGroup>
  <StaticWebAssetBasePath>app1</StaticWebAssetBasePath>
</PropertyGroup>

In published output:

  • Path to the client app in the Server project of a hosted Blazor WebAssembly solution: /BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/app1/
  • Path to a standalone Blazor WebAssembly app: /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/

In the preceding examples, the {TFM} placeholder is the Target Framework Moniker (TFM) (for example, net6.0).

Blazor Server file mappings and static file options

To create additional file mappings with a FileExtensionContentTypeProvider or configure other StaticFileOptions, use one of the following approaches. In the following examples, the {EXTENSION} placeholder is the file extension, and the {CONTENT TYPE} placeholder is the content type.

  • Configure options through dependency injection (DI) in Program.cs using StaticFileOptions:

    using Microsoft.AspNetCore.StaticFiles;

...

var provider = new FileExtensionContentTypeProvider();
provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";

builder.Services.Configure<StaticFileOptions>(options =>
{
    options.ContentTypeProvider = provider;
});

    Because this approach configures the same file provider used to serve blazor.server.js, make sure that your custom configuration doesn't interfere with serving blazor.server.js. For example, don't remove the mapping for JavaScript files by configuring the provider with provider.Mappings.Remove(".js").

  • Use two calls to UseStaticFiles in Program.cs:

    • Configure the custom file provider in the first call with StaticFileOptions.
    • The second middleware serves blazor.server.js, which uses the default static files configuration provided by the Blazor framework.
    using Microsoft.AspNetCore.StaticFiles;

...

var provider = new FileExtensionContentTypeProvider();
provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";

app.UseStaticFiles(new StaticFileOptions { ContentTypeProvider = provider });
app.UseStaticFiles();

  • You can avoid interfering with serving _framework/blazor.server.js by using MapWhen to execute a custom Static File Middleware:

    app.MapWhen(ctx => !ctx.Request.Path
    .StartsWithSegments("/_framework/blazor.server.js"),
        subApp => subApp.UseStaticFiles(new StaticFileOptions() { ... }));

Additional resources