Host and deploy ASP.NET Core Blazor WebAssembly with IIS

[!INCLUDE]

This article explains how to host and deploy Blazor WebAssembly using Internet Information Services (IIS).

IIS is a capable static file server for Blazor apps. To configure IIS to host Blazor, see Build a Static Website on IIS.

Published assets are created in the /bin/Release/{TARGET FRAMEWORK}/publish or bin/Release/{TARGET FRAMEWORK}/browser-wasm/publish folder, where the {TARGET FRAMEWORK} placeholder is the target framework. Host the contents of the publish folder on the web server or hosting service.

web.config file

When a Blazor project is published, a web.config file is created with the following IIS configuration:

• MIME types
• HTTP compression is enabled for the following MIME types:
  • application/octet-stream
  • application/wasm
• URL Rewrite Module rules are established:
  • Serve the sub-directory where the app's static assets reside (wwwroot/{PATH REQUESTED}).
  • Create SPA fallback routing so that requests for non-file assets are redirected to the app's default document in its static assets folder (wwwroot/index.html).

Use of a custom web.config

To use a custom web.config file:

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

1. Place the custom web.config file in the project's root folder.
2. Publish the project. For more information, see xref:blazor/host-and-deploy/index.

:::moniker-end

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

1. Place the custom web.config file in the project's root folder. For a hosted Blazor WebAssembly solution, place the file in the :::no-loc text="Server"::: project's folder.
2. Publish the project. For a hosted Blazor WebAssembly solution, publish the solution from the :::no-loc text="Server"::: project. For more information, see xref:blazor/host-and-deploy/index.

:::moniker-end

If the SDK's web.config generation or transformation during publish either doesn't move the file to published assets in the publish folder or modifies the custom configuration in your custom web.config file, use any of the following approaches as needed to take full control of the process:

• If the SDK doesn't generate the file, for example, in a standalone Blazor WebAssembly app at /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot or bin/Release/{TARGET FRAMEWORK}/browser-wasm/publish, where the {TARGET FRAMEWORK} placeholder is the target framework, set the <PublishIISAssets> property to true in the project file (.csproj). Usually for standalone WebAssembly apps, this is the only required setting to move a custom web.config file and prevent transformation of the file by the SDK.

  xmlCopy

  <PropertyGroup>
    <PublishIISAssets>true</PublishIISAssets>
  </PropertyGroup>
  

• Disable the SDK's web.config transformation in the project file (.csproj):

  xmlCopy

  <PropertyGroup>
    <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
  </PropertyGroup>
  

• Add a custom target to the project file (.csproj) to move a custom web.config file. In the following example, the custom web.config file is placed by the developer at the root of the project. If the web.config file resides elsewhere, specify the path to the file in SourceFiles. The following example specifies the publish folder with $(PublishDir), but provide a path to DestinationFolder for a custom output location.

  xmlCopy

  <Target Name="CopyWebConfig" AfterTargets="Publish">
    <Copy SourceFiles="web.config" DestinationFolder="$(PublishDir)" />
  </Target>
  

Install the URL Rewrite Module

The URL Rewrite Module is required to rewrite URLs. The module isn't installed by default, and it isn't available for install as a Web Server (IIS) role service feature. The module must be downloaded from the IIS website. Use the Web Platform Installer to install the module:

1. Locally, navigate to the URL Rewrite Module downloads page. For the English version, select WebPI to download the WebPI installer. For other languages, select the appropriate architecture for the server (x86/x64) to download the installer.
2. Copy the installer to the server. Run the installer. Select the Install button and accept the license terms. A server restart isn't required after the install completes.

Configure the website

Set the website's Physical path to the app's folder. The folder contains:

• The web.config file that IIS uses to configure the website, including the required redirect rules and file content types.
• The app's static asset folder.

Host as an IIS sub-app

If a standalone app is hosted as an IIS sub-app, perform either of the following:

• Disable the inherited ASP.NET Core Module handler.

  Remove the handler in the Blazor app's published web.config file by adding a <handlers> section to the `` section of the file:

  xmlCopy

  <handlers>
    <remove name="aspNetCore" />
  </handlers>
  

• Disable inheritance of the root (parent) app's `` section using a <location> element with inheritInChildApplications set to false:

  xmlCopy

  <?xml version="1.0" encoding="utf-8"?>
  <configuration>
    <location path="." inheritInChildApplications="false">
      
        <handlers>
          <add name="aspNetCore" ... />
        </handlers>
        <aspNetCore ... />
      
    </location>
  </configuration>
  

  [!NOTE] Disabling inheritance of the root (parent) app's `` section is the default configuration for published apps using the .NET SDK.

Removing the handler or disabling inheritance is performed in addition to configuring the app's base path. Set the app base path in the app's index.html file to the IIS alias used when configuring the sub-app in IIS.

Configure the app's base path by following the guidance in xref:blazor/host-and-deploy/app-base-path.

Brotli and Gzip compression

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

This section only applies to standalone Blazor WebAssembly apps.

:::moniker-end

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

This section only applies to standalone Blazor WebAssembly apps. Hosted Blazor apps use a default ASP.NET Core app web.config file, not the file linked in this section.

:::moniker-end

IIS can be configured via web.config to serve Brotli or Gzip compressed Blazor assets for standalone Blazor WebAssembly apps. For an example configuration file, see web.config.

Additional configuration of the example web.config file might be required in the following scenarios:

• The app's specification calls for either of the following:
  • Serving compressed files that aren't configured by the example web.config file.
  • Serving compressed files configured by the example web.config file in an uncompressed format.
• The server's IIS configuration (for example, applicationHost.config) provides server-level IIS defaults. Depending on the server-level configuration, the app might require a different IIS configuration than what the example web.config file contains.

For more information on custom web.config files, see the Use of a custom web.config section.

Troubleshooting

If a 500 - Internal Server Error is received and IIS Manager throws errors when attempting to access the website's configuration, confirm that the URL Rewrite Module is installed. When the module isn't installed, the web.config file can't be parsed by IIS. This prevents the IIS Manager from loading the website's configuration and the website from serving Blazor's static files.

For more information on troubleshooting deployments to IIS, see xref:test/troubleshoot-azure-iis.