Skip to content

Latest commit

 

History

History
363 lines (237 loc) · 19 KB

static-files.md

File metadata and controls

363 lines (237 loc) · 19 KB
Raw
title author description monikerRange ms.author ms.custom ms.date uid
ASP.NET Core Blazor static files
guardrex
Learn how to configure and manage static files for Blazor apps.
>= aspnetcore-3.1
riande
mvc
11/09/2021
blazor/fundamentals/static-files

ASP.NET Core Blazor static files

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 xref:blazor/tooling#visual-studio-solution-file-sln.

:::moniker range=">= aspnetcore-6.0"

Static File Middleware

This section applies to Blazor Server apps and the :::no-loc text="Server"::: app of a hosted Blazor WebAssembly solution.

Configure Static File Middleware to serve static assets to clients by calling xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A in the app's request processing pipeline. For more information, see xref:fundamentals/static-files.

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 xref:Microsoft.Extensions.Hosting.Environments.Development environment. To enable static files for environments other than xref:Microsoft.Extensions.Hosting.Environments.Development during local development and testing (for example, xref:Microsoft.Extensions.Hosting.Environments.Staging), call xref:Microsoft.AspNetCore.Hosting.WebHostBuilderExtensions.UseStaticWebAssets%2A on the xref:Microsoft.AspNetCore.Builder.WebApplicationBuilder in Program.cs.

Warning

Call xref:Microsoft.AspNetCore.Hosting.WebHostBuilderExtensions.UseStaticWebAssets%2A 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 xref:Microsoft.Extensions.Hosting.Environments.Staging environment by calling xref:Microsoft.Extensions.Hosting.HostEnvironmentEnvExtensions.IsStaging%2A.

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 xref:blazor/host-and-deploy/multiple-hosted-webassembly. 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 :::no-loc text="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 :::no-loc text="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 :::no-loc text="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 :::no-loc text="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 xref:Microsoft.AspNetCore.StaticFiles.FileExtensionContentTypeProvider or configure other xref:Microsoft.AspNetCore.Builder.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 xref:Microsoft.AspNetCore.Builder.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 xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A in Program.cs:

    • Configure the custom file provider in the first call with xref:Microsoft.AspNetCore.Builder.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 xref:Microsoft.AspNetCore.Builder.MapWhenExtensions.MapWhen%2A 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

  • App base path
  • xref:blazor/host-and-deploy/multiple-hosted-webassembly

:::moniker-end

:::moniker range=">= aspnetcore-5.0 < aspnetcore-6.0"

Static File Middleware

This section applies to Blazor Server apps and the :::no-loc text="Server"::: app of a hosted Blazor WebAssembly solution.

Configure Static File Middleware to serve static assets to clients by calling xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A in the app's request processing pipeline. For more information, see xref:fundamentals/static-files.

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 xref:Microsoft.Extensions.Hosting.Environments.Development environment. To enable static files for environments other than xref:Microsoft.Extensions.Hosting.Environments.Development during local development and testing (for example, xref:Microsoft.Extensions.Hosting.Environments.Staging), call xref:Microsoft.AspNetCore.Hosting.WebHostBuilderExtensions.UseStaticWebAssets%2A on the xref:Microsoft.AspNetCore.Hosting.IWebHostBuilder in Program.cs.

Warning

Call xref:Microsoft.AspNetCore.Hosting.WebHostBuilderExtensions.UseStaticWebAssets%2A for the exact environment to prevent activating the feature in production, as it serves files from separate locations on disk other than the project if called in a production environment. The example in this section checks explicitly for the xref:Microsoft.Extensions.Hosting.Environments.Staging environment.

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        if (webBuilder.GetSetting(WebHostDefaults.EnvironmentKey) == 
            Environments.Staging)
        {
            webBuilder.UseStaticWebAssets();
        }

        webBuilder.UseStartup<Startup>();
    });

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 xref:blazor/host-and-deploy/multiple-hosted-webassembly. 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 :::no-loc text="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 :::no-loc text="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 :::no-loc text="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 :::no-loc text="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 xref:Microsoft.AspNetCore.StaticFiles.FileExtensionContentTypeProvider or configure other xref:Microsoft.AspNetCore.Builder.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 Startup.ConfigureServices (Startup.cs) using xref:Microsoft.AspNetCore.Builder.StaticFileOptions:

    using Microsoft.AspNetCore.StaticFiles;

...

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

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 xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A in Startup.Configure (Startup.cs):

    • Configure the custom file provider in the first call with xref:Microsoft.AspNetCore.Builder.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 xref:Microsoft.AspNetCore.Builder.MapWhenExtensions.MapWhen%2A 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

  • App base path
  • xref:blazor/host-and-deploy/multiple-hosted-webassembly

:::moniker-end

:::moniker range="< aspnetcore-5.0"

Static File Middleware

Configure Static File Middleware to serve static assets to clients by calling xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A in the app's request processing pipeline. Multiple calls to xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A is supported when static files exist at multiple locations:

app.UseStaticFiles();
app.UseStaticFiles("/static");

For more information, see xref:fundamentals/static-files.

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 xref:blazor/host-and-deploy/multiple-hosted-webassembly. 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 :::no-loc text="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 :::no-loc text="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 :::no-loc text="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 :::no-loc text="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 xref:Microsoft.AspNetCore.StaticFiles.FileExtensionContentTypeProvider or configure other xref:Microsoft.AspNetCore.Builder.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 Startup.ConfigureServices (Startup.cs) using xref:Microsoft.AspNetCore.Builder.StaticFileOptions:

    using Microsoft.AspNetCore.StaticFiles;

...

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

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 xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles%2A in Startup.Configure (Startup.cs):

    • Configure the custom file provider in the first call with xref:Microsoft.AspNetCore.Builder.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 xref:Microsoft.AspNetCore.Builder.MapWhenExtensions.MapWhen%2A 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

  • App base path
  • xref:blazor/host-and-deploy/multiple-hosted-webassembly

:::moniker-end