ASP.NET Core Blazor static files

This article describes Blazor app configuration for serving static files.

Blazor framework static files

In releases prior to .NET 8, Blazor framework static files, such as the Blazor script, are served via Static File Middleware. In .NET 8 or later, Blazor framework static files are mapped using endpoint routing, and Static File Middleware is no longer used.

Static Web Asset Project Mode

This section applies to the .Client project of a Blazor Web App.

The required <StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode> setting in the .Client project of a Blazor Web App reverts Blazor WebAssembly static asset behaviors back to the defaults, so that the project behaves as part of the hosted project. The Blazor WebAssembly SDK (Microsoft.NET.Sdk.BlazorWebAssembly) configures static web assets in a specific way to work in "standalone" mode with a server simply consuming the outputs from the library. This isn't appropriate for a Blazor Web App, where the WebAssembly portion of the app is a logical part of the host and must behave more like a library. For example, the project doesn't expose the styles bundle (for example, BlazorSample.Client.styles.css) and instead only provides the host with the project bundle, so that the host can include it in its own styles bundle.

Changing the value (Default) of <StaticWebAssetProjectMode> or removing the property from the .Client project is not supported.

Static File Middleware

This section applies to server-side Blazor apps.

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

This section applies to server-side static files.

When running an app 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 the Program file.

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();
}

Prefix for Blazor WebAssembly assets

This section applies to Blazor Web Apps.

Use the WebAssemblyComponentsEndpointOptions.PathPrefix endpoint option to set the path string that indicates the prefix for Blazor WebAssembly assets. The path must correspond to a referenced Blazor WebAssembly application project.

endpoints.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode(options => 
        options.PathPrefix = "{PATH PREFIX}");

In the preceding example, the {PATH PREFIX} placeholder is the path prefix and must start with a forward slash (/).

In the following example, the path prefix is set to /path-prefix:

endpoints.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode(options => 
        options.PathPrefix = "/path-prefix");

Static web asset base path

This section applies to standalone Blazor WebAssembly apps.

By default, publishing the 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.

Without setting the <StaticWebAssetBasePath> property, a standalone app is published at /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/.

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

If the <StaticWebAssetBasePath> property 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 standalone Blazor WebAssembly app's project file (.csproj):

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

In published output, the path to the standalone Blazor WebAssembly app is /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/.

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

File mappings and static file options

This section applies to server-side static files.

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. The namespace for the following API is Microsoft.AspNetCore.StaticFiles.

• Configure options through dependency injection (DI) in the Program file using StaticFileOptions:

  var provider = new FileExtensionContentTypeProvider();
  provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";
  
  builder.Services.Configure<StaticFileOptions>(options =>
  {
      options.ContentTypeProvider = provider;
  });
  
  app.UseStaticFiles();
  

• Pass the StaticFileOptions directly to UseStaticFiles in the Program file:

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

Additional resources

App base path