This article pertains to the deployment scenario where the Blazor app is placed on a static hosting web server or service, .NET isn't used to serve the Blazor app. This strategy is covered in theStandalone deployment section and other articles in this node for IIS, Azure services, Apache, Nginx, and GitHub Pages.

The following deployment strategies are supported:

• The Blazor app is served by an ASP.NET Core app. This strategy is covered in theHosted deployment with ASP.NET Core section.
• The Blazor app is placed on a static hosting web server or service, where .NET isn't used to serve the Blazor app. This strategy is covered in theStandalone deployment section, which includes information on hosting a Blazor WebAssembly app as an IIS sub-app.
• An ASP.NET Core app hosts multiple Blazor WebAssembly apps. For more information, seeMultiple hosted ASP.NET Core Blazor WebAssembly apps.

When building a Blazor app that runs on the client (.Client project of a Blazor Web App or standalone Blazor WebAssembly app) and targets mobile device browsers, especially Safari on iOS, decreasing the maximum memory for the app with the MSBuild propertyEmccMaximumHeapSize may be required. The default value is 2,147,483,648 bytes, which may be too large and result in the app crashing if the app attempts to allocate more memory with the browser failing to grant it. The following example sets the value to 268,435,456 bytes in theProgram file:

When building a Blazor WebAssembly app that targets mobile device browsers, especially Safari on iOS, decreasing the maximum memory for the app with the MSBuild propertyEmccMaximumHeapSize may be required. The default value is 2,147,483,648 bytes, which may be too large and result in the app crashing if the app attempts to allocate more memory with the browser failing to grant it. The following example sets the value to 268,435,456 bytes in theProgram file:

Webcil packaging format for .NET assemblies

Webcil is a web-friendly packaging format for .NET assemblies designed to enable using Blazor WebAssembly in restrictive network environments. Webcil files use a standard WebAssembly wrapper, where the assemblies are deployed as WebAssembly files that use the standard.wasm file extension.

Webcil is the default packaging format when you publish a Blazor WebAssembly app. To disable the use of Webcil, set the following MSBuild property in the app's project file:

<PropertyGroup>  <WasmEnableWebcil>false</WasmEnableWebcil></PropertyGroup>

Blazor relies on the host to serve the appropriate compressed files. When hosting a Blazor WebAssembly standalone app, additional work might be required to ensure that statically-compressed files are served:

Blazor relies on the host to serve the appropriate compressed files. When using anASP.NET Core Hosted Blazor WebAssembly project, the host project is capable of performing content negotiation and serving the statically-compressed files. When hosting a Blazor WebAssembly standalone app, additional work might be required to ensure that statically-compressed files are served:

Note

If the minified version of thedecode.js script (decode.min.js) fails, try using the unminified version (decode.js) instead.

Blazor Web App:

<script type="module">  import { BrotliDecode } from './decode.min.js';  Blazor.start({    webAssembly: {      loadBootResource: function (type, name, defaultUri, integrity) {        if (type !== 'dotnetjs' && location.hostname !== 'localhost' && type !== 'configuration' && type !== 'manifest') {          return (async function () {            const response = await fetch(defaultUri + '.br', { cache: 'no-cache' });            if (!response.ok) {              throw new Error(response.statusText);            }            const originalResponseBuffer = await response.arrayBuffer();            const originalResponseArray = new Int8Array(originalResponseBuffer);            const decompressedResponseArray = BrotliDecode(originalResponseArray);            const contentType = type ===               'dotnetwasm' ? 'application/wasm' : 'application/octet-stream';            return new Response(decompressedResponseArray,               { headers: { 'content-type': contentType } });          })();        }      }    }  });</script>

Standalone Blazor WebAssembly:

To disable compression, add theCompressionEnabled MSBuild property to the app's project file and set the value tofalse:

<PropertyGroup>  <CompressionEnabled>false</CompressionEnabled></PropertyGroup>

TheCompressionEnabled property can be passed to thedotnet publish command with the following syntax in a command shell:

dotnet publish -p:CompressionEnabled=false

To disable compression, add theBlazorEnableCompression MSBuild property to the app's project file and set the value tofalse:

<PropertyGroup>  <BlazorEnableCompression>false</BlazorEnableCompression></PropertyGroup>

TheBlazorEnableCompression property can be passed to thedotnet publish command with the following syntax in a command shell:

dotnet publish -p:BlazorEnableCompression=false

Hosted deployment with ASP.NET Core

Ahosted deployment serves the Blazor WebAssembly app to browsers from anASP.NET Core app that runs on a web server.

The client Blazor WebAssembly app is published into the/bin/Release/{TARGET FRAMEWORK}/publish/wwwroot folder of the server app, along with any other static web assets of the server app. The two apps are deployed together. A web server that is capable of hosting an ASP.NET Core app is required. For a hosted deployment, Visual Studio includes theBlazor WebAssembly App project template (blazorwasm template when using thedotnet new command) with theHosted option selected (-ho|--hosted when using thedotnet new command).

For more information, see the following articles:

• ASP.NET Core app hosting and deployment:Host and deploy ASP.NET Core
• Deployment to Azure App Service:Publish an ASP.NET Core app to Azure with Visual Studio
• Blazor project templates:ASP.NET Core Blazor project structure

Hosted deployment of a framework-dependent executable for a specific platform

To deploy a hosted Blazor WebAssembly app as aframework-dependent executable for a specific platform (not self-contained) use the following guidance based on the tooling in use.

Visual Studio

Aself-contained deployment is configured for a generated publish profile (.pubxml). Confirm that theServer project's publish profile contains the<SelfContained> MSBuild property set tofalse.

In the.pubxml publish profile file in theServer project'sProperties folder:

<SelfContained>false</SelfContained>

Set theRuntime Identifier (RID) using theTarget Runtime setting in theSettings area of thePublish UI, which generates the<RuntimeIdentifier> MSBuild property in the publish profile:

<RuntimeIdentifier>{RID}</RuntimeIdentifier>

In the preceding configuration, the{RID} placeholder is theRuntime Identifier (RID).

Publish theServer project in theRelease configuration.

.NET CLI

Configure aself-contained deployment by placing the<SelfContained> MSBuild property in a<PropertyGroup> in theServer project's project file set tofalse:

<SelfContained>false</SelfContained>

Set theRuntime Identifier (RID) usingeither of the following approaches:

• Option 1: Set the RID in a<PropertyGroup> in theServer project's project file:

  <RuntimeIdentifier>{RID}</RuntimeIdentifier>

  In the preceding configuration, the{RID} placeholder is theRuntime Identifier (RID).

  Publish the app in the Release configuration from theServer project:

  dotnet publish -c Release

• Option 2: Pass the RID in thedotnet publish command as the MSBuild property (/p:RuntimeIdentifier), not with the-r|--runtime option:

  dotnet publish -c Release /p:RuntimeIdentifier={RID}

  In the preceding command, the{RID} placeholder is theRuntime Identifier (RID).

For more information, see the following articles:

• .NET application publishing overview
• Host and deploy ASP.NET Core

Important

Unlike the path provided tohref of the<base> tag, don't include a trailing slash (/) when passing the--pathbase argument value. If the app base path is provided in the<base> tag as<base href="/CoolApp/"> (includes a trailing slash), pass the command-line argument value as--pathbase=/CoolApp (no trailing slash).

Configure the Trimmer

Blazor performs Intermediate Language (IL) trimming on each Release build to remove unnecessary IL from the output assemblies. For more information, seeConfigure the Trimmer for ASP.NET Core Blazor.

Configure the Linker

Blazor performs Intermediate Language (IL) linking on each Release build to remove unnecessary IL from the output assemblies. For more information, seeConfigure the Linker for ASP.NET Core Blazor.

Change the file name extension of DLL files

This section applies to .NET 5 through .NET 7. In .NET 8 or later, .NET assemblies are deployed as WebAssembly files (.wasm) using the Webcil file format.

If a firewall, anti-virus program, or network security appliance is blocking the transmission of the app's dynamic-link library (DLL) files (.dll), you can follow the guidance in this section to change the file name extensions of the app's published DLL files.

Changing the file name extensions of the app's DLL files might not resolve the problem because many security systems scan the content of the app's files, not merely check file extensions.

For a more robust approach in environments that block the download and execution of DLL files, takeeither of the following approaches:

• Use .NET 8 or later, which packages .NET assemblies as WebAssembly files (.wasm) using theWebcil file format. For more information, see theWebcil packaging format for .NET assemblies section in a .NET 8 or later version of this article.
• In .NET 6 or later, use acustom deployment layout.

Third-party approaches exist for dealing with this problem. For more information, see the resources atAwesome Blazor.

After publishing the app, use a shell script or DevOps build pipeline to rename.dll files to use a different file extension in the directory of the app's published output.

In the following examples:

• PowerShell (PS) is used to update the file extensions.
• .dll files are renamed to use the.bin file extension from the command line.
• Files listed in the published Blazor boot manifest with a.dll file extension are updated to the.bin file extension.
• If service worker assets are also in use, a PowerShell command updates the.dll files listed in theservice-worker-assets.js file to the.bin file extension.

To use a different file extension than.bin, replace.bin in the following commands with the desired file extension.

dir {PATH} | rename-item -NewName { $_.name -replace ".dll\b",".bin" }

((Get-Content {PATH}\blazor.boot.json -Raw) -replace '.dll"','.bin"') | Set-Content {PATH}\blazor.boot.json

((Get-Content {PATH}\service-worker-assets.js -Raw) -replace '.dll"','.bin"') | Set-Content {PATH}\service-worker-assets.js

for f in {PATH}/*; do mv "$f" "`echo $f | sed -e 's/\.dll/.bin/g'`"; done

sed -i 's/\.dll"/.bin"/g' {PATH}/blazor.boot.json

sed -i 's/\.dll"/.bin"/g' {PATH}/service-worker-assets.js

To address the compressedblazor.boot.json file, adopt either of the following approaches:

• Recompress the updatedblazor.boot.json file, producing newblazor.boot.json.gz andblazor.boot.json.br files. (Recommended)
• Remove the compressedblazor.boot.json.gz andblazor.boot.json.br files. (Compression is disabled with this approach.)

For aProgressive Web App (PWA)'s compressedservice-worker-assets.js file, adopt either of the following approaches:

• Recompress the updatedservice-worker-assets.js file, producing newservice-worker-assets.js.br andservice-worker-assets.js.gz files. (Recommended)
• Remove the compressedservice-worker-assets.js.gz andservice-worker-assets.js.br files. (Compression is disabled with this approach.)

To automate the extension change on Windows in .NET 6/7, the following approach uses a PowerShell script placed at the root of the project. The following script, which disables compression, is the basis for further modification if you wish to recompress theblazor.boot.json file andservice-worker-assets.js file if the app is aProgressive Web App (PWA). The path to thepublish folder is passed to the script when it's executed.

ChangeDLLExtensions.ps1::

param([string]$filepath)dir $filepath\wwwroot\_framework | rename-item -NewName { $_.name -replace ".dll\b",".bin" }((Get-Content $filepath\wwwroot\_framework\blazor.boot.json -Raw) -replace '.dll"','.bin"') | Set-Content $filepath\wwwroot\_framework\blazor.boot.jsonRemove-Item $filepath\wwwroot\_framework\blazor.boot.json.gzRemove-Item $filepath\wwwroot\_framework\blazor.boot.json.br

If service worker assets are also in use because the app is aProgressive Web App (PWA), add the following commands:

((Get-Content $filepath\wwwroot\service-worker-assets.js -Raw) -replace '.dll"','.bin"') | Set-Content $filepath\wwwroot\service-worker-assets.jsRemove-Item $filepath\wwwroot\service-worker-assets.js.gzRemove-Item $filepath\wwwroot\service-worker-assets.js.br

In the project file, the script is executed after publishing the app for theRelease configuration:

<Target Name="ChangeDLLFileExtensions" AfterTargets="AfterPublish" Condition="'$(Configuration)'=='Release'">  <Exec Command="powershell.exe -command &quot;&amp; {.\ChangeDLLExtensions.ps1 '$(SolutionDir)'}&quot;" /></Target>

After publishing the app, manually recompressblazor.boot.json, andservice-worker-assets.js if used, to re-enable compression.

Usually, the app's server requires static asset configuration to serve the files with the updated extension. For an app hosted by IIS, add a MIME map entry (<mimeMap>) for the new file extension in the static content section (<staticContent>) in a customweb.config file. The following example assumes that the file extension is changed from.dll to.bin:

<staticContent>  ...  <mimeMap fileExtension=".bin" mimeType="application/octet-stream" />  ...</staticContent>

Include an update for compressed files ifcompression is in use:

<mimeMap fileExtension=".bin.br" mimeType="application/octet-stream" /><mimeMap fileExtension=".bin.gz" mimeType="application/octet-stream" />

Remove the entry for the.dll file extension:

- <mimeMap fileExtension=".dll" mimeType="application/octet-stream" />

Remove entries for compressed.dll files ifcompression is in use:

- <mimeMap fileExtension=".dll.br" mimeType="application/octet-stream" />- <mimeMap fileExtension=".dll.gz" mimeType="application/octet-stream" />

For more information on customweb.config files, see theUse of a customweb.config section.