Host and deploy ASP.NET Core Blazor

This article explains how to host and deploy Blazor apps.

Publish the app

Apps are published for deployment in Release configuration.

dotnet publish

dotnet publish -c Release

Publishing the app triggers a restore of the project's dependencies and builds the project before creating the assets for deployment. As part of the build process, unused methods and assemblies are removed to reduce app download size and load times.

Empty the target publish folder

When using the dotnet publish command in a command shell to publish an app, the command generates the necessary files for deployment based on the current state of the project and places the files into the specified output folder. The command doesn't automatically clean the target folder before publishing the app.

To empty the target folder automatically before the app is published, add the following MSBuild target to the app's project file (.csproj) under the root <Project> element:

<Target Name="_RemovePublishDirBeforePublishing" BeforeTargets="BeforePublish">
  <RemoveDir Directories="$(PublishDir)" Condition="'$(PublishDir)' != ''" />
</Target>

Default publish locations

IIS

To host a Blazor app in IIS, see the following resources:

• IIS hosting
  • Publish an ASP.NET Core app to IIS
  • Host ASP.NET Core on Windows with IIS
• Host and deploy ASP.NET Core server-side Blazor apps: Blazor Web Apps (.NET 8 or later) and Blazor Server apps (.NET 7 or earlier) running on IIS, including IIS with Azure Virtual Machines (VMs) running Windows OS and Azure App Service.
• Host and deploy ASP.NET Core Blazor WebAssembly with IIS: Standalone Blazor WebAssembly apps (all .NET releases) and hosted Blazor WebAssembly apps (.NET 7 or earlier).
• IIS sub-application hosting
  • Follow the app base path guidance prior to publishing the app. The examples use an app base path of /CoolApp and show how to obtain the base path from app settings or other configuration providers.
  • Follow the sub-application configuration guidance in Advanced configuration. The sub-app's folder path under the root site becomes the virtual path of the sub-app. For an app base path of /CoolApp, the Blazor app is placed in a folder named CoolApp under the root site and the sub-app takes on a virtual path of /CoolApp.

Sharing an app pool among ASP.NET Core apps isn't supported, including for Blazor apps. Use one app pool per app when hosting with IIS, and avoid the use of IIS's virtual directories for hosting multiple apps.

<WasmBundlerFriendlyBootConfig>true</WasmBundlerFriendlyBootConfig>

Blazor Server MapFallbackToPage configuration

This section only applies to Blazor Server apps. MapFallbackToPage isn't supported in Blazor Web Apps and Blazor WebAssembly apps.

In scenarios where an app requires a separate area with custom resources and Razor components:

• Create a folder within the app's Pages folder to hold the resources. For example, an administrator section of an app is created in a new folder named Admin (Pages/Admin).

• Create a root page (_Host.cshtml) for the area. For example, create a Pages/Admin/_Host.cshtml file from the app's main root page (Pages/_Host.cshtml). Don't provide an @page directive in the Admin _Host page.

• Add a layout to the area's folder (for example, Pages/Admin/_Layout.razor). In the layout for the separate area, set the <base> tag href to match the area's folder (for example, <base href="/Admin/" />). For demonstration purposes, add ~/ to the static resources in the page. For example:

  • ~/css/bootstrap/bootstrap.min.css
  • ~/css/site.css
  • ~/BlazorSample.styles.css (the example app's namespace is BlazorSample)
  • ~/_framework/blazor.server.js (Blazor script)

• If the area should have its own static asset folder, add the folder and specify its location to Static File Middleware in Program.cs (for example, app.UseStaticFiles("/Admin/wwwroot")).

• Razor components are added to the area's folder. At a minimum, add an Index component to the area folder with the correct @page directive for the area. For example, add a Pages/Admin/Index.razor file based on the app's default Pages/Index.razor file. Indicate the Admin area as the route template at the top of the file (@page "/admin"). Add additional components as needed. For example, Pages/Admin/Component1.razor with an @page directive and route template of @page "/admin/component1.

• In Program.cs, call MapFallbackToPage for the area's request path immediately before the fallback root page path to the _Host page:

  ...
  app.UseRouting();
  
  app.MapBlazorHub();
  app.MapFallbackToPage("~/Admin/{*clientroutes:nonfile}", "/Admin/_Host");
  app.MapFallbackToPage("/_Host");
  
  app.Run();