In web development, Blazor WebAssembly stands as a game-changer. It allows developers to build interactive client-side web applications using .NET and C#, instead of JavaScript. This not only opens up new possibilities for web development but also brings along new methods for hosting and deploying these applications.
In this article, we will explore the different methods to host and deploy Blazor WebAssembly applications. We will delve into the details of various hosting models and environments, compare the trade-offs of different deployment modes, and provide practical tips and tools for publishing and deploying your apps.
Table of contents:
Hosted Deployment
Standalone Deployment
Amazon S3
Azure App Service
GitHub Pages
IIS
Framework-dependent
Self-contained
Host and Deploy Blazor WebAssembly
Understanding different hosting and deployment methods in Blazor WebAssembly is crucial for several reasons:
Performance: Different hosting and deployment methods can have a significant impact on the performance of your Blazor WebAssembly app. For example, Ahead-of-Time (AOT) compilation can result in runtime performance improvements.
Flexibility: Understanding different methods allows you to choose the one that best fits your needs. For example, if you want to take full advantage of server capabilities, you might choose a hosted deployment. If you want your app to remain functional if the server goes offline, you might choose a standalone deployment.
Efficiency: Different methods can affect the efficiency of your app. For example, trimming .NET Intermediate Language (IL) after AOT compilation can reduce the size of the published app.
Scalability: Some hosting and deployment methods are better suited to scaling than others. Understanding the pros and cons of each can help you choose the right method for your app as it grows.
Cost: Hosting and deployment methods can also have cost implications. For example, hosting on a Content Delivery Network (CDN) might incur different costs compared to hosting on an ASP.NET Core server.
The two main ways to host a Blazor WebAssembly app are hosted and standalone:
Hosted Deployment: In this model, the Blazor WebAssembly app is served from an ASP.NET Core app. This setup allows the Blazor app to take full advantage of server capabilities, such as server-side rendering, fast prerendering, and thin client.
Standalone Deployment: In standalone deployment, the Blazor WebAssembly app is served from a static web server. This model treats the Blazor WebAssembly app as static files that can be hosted by any web server capable of serving static files.
Let's go into detail!
Hosting Models
1. Hosted Deployment
In the hosted deployment model, the Blazor WebAssembly app is served by an ASP.NET Core app that runs on a web server. The ASP.NET Core app can also provide server-side features, such as authentication, authorization, data access, and prerendering. The Blazor app, its dependencies, and the .NET runtime are downloaded to the browser in parallel.
The app is then executed directly on the browser UI thread. This model is different from the standalone deployment model, where the Blazor WebAssembly app is self-contained and does not depend on any server-side code or services.
This model is particularly useful when you want to offload some of the processing to the server or take advantage of server-side APIs. However, this model also has some drawbacks, such as requiring an active connection to the server, increasing the server load, and complicating the deployment process.
Note: This model allows Blazor WebAssembly to run in environments that block the download and execution of DLL files, which are required by Blazor WebAssembly apps. In these environments, you can use the Webcil file format, which packages the DLLs as WebAssembly files with the .wasm extension. Webcil is the default packaging format when you publish a Blazor WebAssembly app.
Advantages and use cases of hosted deployment
The hosted deployment model offers several benefits:
The Blazor WebAssembly app can take full advantage of server capabilities.
The app remains functional if the server goes offline.
Client resources and capabilities are fully leveraged.
Work is offloaded from the server to the client.
This model is particularly useful when you want to offload some of the processing to the server or take advantage of server-side APIs.
Note: This model requires an active connection to the server, and the server must have the necessary resources to handle the client load.
Step-by-step guide on how to host and deploy using ASP.NET Core
STEP 1: Publish the Application:
Use the dotnet publish command to create a deployment package. This package contains your compiled code, its dependencies, and other necessary assets.
dotnet publish -c Release -o ./publishThe above command will publish the application in the release configuration and output the published files into a folder named "publish".
You can specify the target runtime environment using the -r option followed by the runtime identifier (e.g., -r win-x64).
You have two options for deployment:
Framework-dependent: This mode relies on the .NET Core runtime installed on the target server, and produces smaller packages.
Self-contained: This mode includes the runtime in the package, making the application more portable, but also increases the size of the package.
STEP 2: Choose a Hosting Environment:
Choose a hosting environment that supports ASP.NET Core apps, such as:
Internet Information Services (IIS): Install the .NET Core Hosting Bundle on the Windows server, and configure IIS to handle requests using either in-process or out-of-process hosting models.
Azure App Service: Create an App Service plan and deploy the app using Visual Studio, Azure CLI, or Azure PowerShell.
Third-party hosting providers: Follow their specific instructions for deploying ASP.NET Core apps, which often involve file transfer and configuration. Some examples are AWS, Google Cloud, or Heroku.
Containers: Package the app in a Docker container and deploy it to a container orchestrator like Docker Swarm or Kubernetes.
STEP 3: Configure the Hosting Environment:
Set up the following components for the hosting environment:
Process manager: Ensure the app starts when requests arrive and restarts if it crashes. For example, you can use Windows Service, systemd, or launchd.
Reverse proxy (if needed): Configure a reverse proxy like Nginx or Apache to forward requests to the app, especially for non-Windows environments. The reverse proxy can also handle SSL/TLS termination.
Environment variables: Provide necessary configuration values for the app, such as ASPNETCORE_ENVIRONMENT, ASPNETCORE_URLS, or DOTNET_ENVIRONMENT.
Logging and monitoring: Set up logging and monitoring tools for troubleshooting and performance analysis. For example, you can use Application Insights, Serilog, or NLog.
STEP 4: Deploy the Published App:
Copy the published files to the designated folder on the hosting server. The folder depends on the hosting environment and the hosting model. For example, if you use IIS and the in-process hosting model, the folder is usually %SystemDrive%\inetpub\wwwroot. If you use Azure App Service, the folder is usually D:\home\site\wwwroot.
Ensure appropriate permissions and access rights are set for the folder and the files.
STEP 5: Test and Verify:
Thoroughly test the deployed app to ensure it functions correctly in the hosting environment. You can use the following methods to test and verify the app:
Check the app’s URL and see if it loads and works as expected.
Inspect the browser’s console and network tabs for any errors or warnings.
Use the browser’s developer tools to debug the app and inspect its elements and resources.
Use the logging and monitoring tools to check the app’s performance and health.
2. Standalone Deployment
Blazor is a framework that allows you to create interactive web UIs using C# and HTML. Blazor has two hosting models: Blazor Server and Blazor WebAssembly. In this information, we will focus on the Blazor WebAssembly hosting model, which enables client-side interactivity.
In a standalone deployment model, the Blazor WebAssembly app is created to run exclusively on the Blazor WebAssembly hosting model without server-side rendering and interactivity.
These features are not needed for a standalone Blazor WebAssembly app, because the app’s UI is rendered and updated on the browser using C# and WebAssembly, and the app does not depend on any server-side code or services.
This means the app, its dependencies, and the .NET runtime are downloaded to the browser as static files, and the app is executed directly on the browser UI thread. This model is beneficial when the Blazor app is placed on a static hosting web server or service.
Advantages and use cases of standalone deployment
The standalone deployment model offers several benefits:
No .NET Server-Side Dependency: Once the app is downloaded from the server, it remains functional even if the server goes offline.
Leverages Client Resources: Client resources and capabilities are fully leveraged2. This means that work is offloaded from the server to the client.
Suitable for Static Hosting: Standalone deployment is suitable for static hosting1. Any static file server can serve the Blazor app.
Works in Offline Mode: The Blazor WebAssembly can work in offline mode, which means it doesn’t require a connection to the server.
Serverless Deployment: Serverless deployment is possible, which means you don’t need a server, just something to get the files to the browser.
Steps to Deploy a Blazor WebAssembly app as a standalone app using a static web server
A static web server is a web server that only serves static files, such as HTML, CSS, JavaScript, images, etc. You do not need any server-side logic or database interaction for your app. Any static file server can host your app, such as Azure Static Web Apps, GitHub Pages, Amazon S3, etc.
The steps for deploying a Blazor WebAssembly app as a standalone app using a static web server are:
1. Publish as Standalone:
This step builds your Blazor WebAssembly app and packages it with all the dependencies and the .NET runtime into a single folder. This makes it easier to deploy and run on any platform that supports Blazor WebAssembly.
To publish as standalone, you can use either Visual Studio or the command line.
Visual Studio:
Right-click the project in Solution Explorer.
Select “Publish.”
In the “Publish” dialog, choose “Folder” as the target location.
Select the target runtime (e.g., Windows, Linux, macOS).
Command Line:
Use the dotnet publish command with the -r flag to specify the runtime: dotnet publish -c Release -r <runtime-identifier>
Replace <runtime-identifier> with the appropriate value for your target platform. For example, linux-x64 for Linux 64-bit or win-x86 for Windows 32-bit.
2. Copy Files:
This will copy the contents of the publish folder to the desired location on the target machine. The target machine is the server where you want to host your app. We will use a static web server, such as Azure Static Web Apps, GitHub Pages, Amazon S3, etc.
To copy files, you can use any method that allows you to transfer files from your local machine to your target machine, such as FTP, SCP, or drag and drop. The files that you need to copy are:
The app’s HTML file (index.html)
The app’s configuration file (appsettings.json)
The app’s bootstrapping script (blazor.webassembly.js)
The app’s WebAssembly binary (dotnet.wasm)
The app’s assemblies and dependencies (*.dll)
The app’s static assets (e.g., images, CSS)
3. Host the App:
Here, hosts the app on the target machine using the static web server. The static web server serves the app’s files to the browser, and the browser downloads and executes the app. The app does not need any communication with the server, except for fetching the files.
To host the app, you need to follow the instructions of the specific static web server or service that you use. For example, if you use Azure Static Web Apps, you can follow the instructions [here]. If you use GitHub Pages, you can follow the instructions [here]. If you use Amazon S3, you can follow the instructions [here].
4. Configure the App Base Path (Optional):
This step is optional but required if the app is hosted at a non-root path, such as https://www.contoso.com/CoolApp/. The app base path is the URL part that indicates where the app is located on the server. The app needs to know the app base path to load the files correctly.
To configure the app base path, you need to add a <base> tag inside the <head> element of the index.html file. The <base> tag specifies the base URL for all relative URLs in the document. For example, if the app is hosted at https://www.contoso.com/CoolApp/, you need to add the following tag:
<base href="/CoolApp/" />Replace /CoolApp/ with the actual path of your app.
5. Enable HTTPS (Optional):
This step is also optional but recommended for production environments. HTTPS is a protocol that encrypts the communication between the browser and the server, ensuring the security and privacy of the data. HTTPS also enables some features that are not available on HTTP, such as service workers and geolocation.
To enable HTTPS, you need to configure SSL/TLS on your hosting server or service. SSL/TLS is a technology that creates a secure connection between the browser and the server, using certificates and keys. The certificates and keys can be obtained from a certificate authority (CA), such as Let’s Encrypt, or self-signed.
Hosting Environments
1. Amazon S3
Amazon Simple Storage Service (Amazon S3) is an object storage service that offers industry-leading scalability, data availability, security, and performance. It’s designed to store and retrieve any amount of data at any time, from anywhere.
Hosting the Blazor WebAssembly app on Amazon S33 involves creating a new S3 bucket in Amazon S3 and uploading your published Blazor WebAssembly app to the bucket.
Here’s a step-by-step guide on how to do it:
Create an Amazon S3 Bucket: Before you can host your Blazor WebAssembly app on Amazon S3, you need to create an Amazon S3 bucket on your AWS account.
Publish the Blazor WebAssembly App: Use Visual Studio or the .NET Core CLI to publish your Blazor WebAssembly app. The published app should be placed in a folder on your machine.
Upload the App to the S3 Bucket: Upload the folder containing your published Blazor WebAssembly app to the S3 bucket.
Configure the S3 Bucket for Static Website Hosting: The S3 bucket should be configured for static website hosting.
Access the App: You can now access your Blazor WebAssembly app using the URL provided by Amazon S3.
2. Azure App Service
Azure App Service is a fully managed platform for building, deploying, and scaling web apps. It’s designed to streamline deployment and management, offering scalability, reliability, and integration capabilities tailored for developers.
Hosting the Blazor WebAssembly app on Azure App Service involves creating a new web app in Azure App Service and pointing it to the folder where your published Blazor WebAssembly app resides.
Here’s a step-by-step guide on how to do it:
Create an Azure App Service: Before you can host your Blazor WebAssembly app on Azure App Service, you need to create an Azure App Service on your Azure account.
Publish the Blazor WebAssembly App: Use Visual Studio or the .NET Core CLI to publish your Blazor WebAssembly app. The published app should be placed in a folder on your machine.
Create a New Web App in Azure App Service: Open the Azure portal and create a new web app. Point the web app to the folder where your published Blazor WebAssembly app resides.
Configure the App Service Plan: The App Service plan for your site should be configured to use .NET CLR Version No Managed Code.
Access the App: You can now access your Blazor WebAssembly app using the URL provided by Azure App Service.
3. GitHub Pages
GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub, optionally runs the files through a build process, and publishes a website. It is designed to host your personal, organizational, or project pages directly from a GitHub repository.
Here are some key points about using GitHub Pages for hosting and deploying Blazor WebAssembly:
Free Hosting for Static Websites: GitHub Pages provides free hosting for static websites. This makes it a cost-effective choice for projects with a limited budget.
Integration with GitHub: Since GitHub Pages is tightly integrated with GitHub, it can automatically publish changes to your site whenever you push updates to your repository.
Use of GitHub Actions: You can use GitHub Actions to automate the deployment of your Blazor WebAssembly app to GitHub Pages. GitHub Actions offers a way to automate, customize, and execute your software development workflows right in your repository.
Jekyll Support: GitHub Pages has built-in support for Jekyll, a simple, blog-aware, static site generator. However, this feature is typically not used when hosting Blazor WebAssembly apps.
While GitHub Pages offers many benefits, it may not be suitable for all use cases. For example, GitHub Pages is intended for static websites and does not support server-side code. Also, GitHub Pages sites are subject to certain usage limits1, including a maximum site size of 1 GB.
4. IIS
Internet Information Services (IIS) is an extensible web server created by Microsoft for use with the Windows NT family. IIS supports HTTP, HTTP/2, HTTPS, FTP, FTPS, SMTP, and NNTP. It has been an integral part of the Windows NT family since Windows NT 4.0.
You can host a Blazor WebAssembly app as an IIS sub-app. This involves creating a new website in IIS and pointing it to the folder where your published Blazor WebAssembly app resides.
Here’s a step-by-step guide on how to do it:
Install IIS and .NET Core Hosting Bundle: Before you can host your Blazor WebAssembly app on IIS, you need to install IIS and the .NET Core Hosting Bundle on your machine.
Publish the Blazor WebAssembly App: Use Visual Studio or the .NET Core CLI to publish your Blazor WebAssembly app. The published app should be placed in a folder on your machine.
Create a New Website in IIS: Open IIS and create a new website. Point the website to the folder where your published Blazor WebAssembly app resides.
Configure the Application Pool: The application pool for your site should be configured to use .NET CLR Version No Managed Code.
Access the App: You can now access your Blazor WebAssembly app using the hostname you specified when creating the website in IIS.
However, please note that while you can host a Blazor WebAssembly app on IIS, it’s important to remember that Blazor WebAssembly is a fully client-side framework and will need a web server to host it. When running from Visual Studio, Kestrel serves as the server, and it sets up all the hosting automatically.
However, when building a WebAssembly project, the compiler bundles all your C# code, translates it to WebAssembly, and produces a single folder. This folder can be hosted on any static file hosting platform or web server, similar to the operation of JavaScript SPA frameworks.
Deployment Modes
There are two deployment modes for Blazor WebAssembly apps:
Framework-dependent
Self-contained
Framework-Dependent
In this mode, you deploy portable code that is ready to run in any compatible environment, provided the corresponding .NET Core or .NET Framework is installed.
The size of the published package is small, as the framework (and runtime) is excluded.
With framework-dependent deployments, the appropriate system-installed runtime and framework are used.
Self-Contained:
In this mode, you compile platform-specific code that is ready to run standalone in a specific target environment. .NET Core self-contained deployments will work without any framework being installed on the target system but will only run on systems of the targeted platform.
The size of the published package is much larger, as the complete runtime is included in the package.
Trade-Offs
In the case of Blazor WebAssembly apps deployment modes:
For Framework-Dependent mode:
The advantage is that the size of the published package is small, and you can patch the .NET runtime for all your apps without having to re-compile.
The trade-off or drawback is that you have less control at runtime because you don’t know exactly which version of the .NET runtime will be used when your app runs (as it depends on what’s installed).
For Self-Contained mode:
The advantage is that you have complete control over the runtime used with your app, as you’re distributing it with your app, and there’s no requirement for a shared runtime to be installed.
The trade-off or drawback is that as you’re distributing the runtime as well, the total size of your app will be much larger. To patch the runtime, you need to recompile and redistribute your app.
Tips and Tools for Publishing and Deploying
1. dotnet publish command:
Issue: When you’re ready to publish your Blazor WebAssembly app, you need a way to compile the application, read through its dependencies specified in the project file, and publish the resulting set of files to a directory.
Solution: The dotnet publish command does exactly this. It compiles the application, reads through its dependencies specified in the project file, and publishes the resulting set of files to a directory. This command creates a set of files that you can deploy to a hosting system to run your app.
2. Webcil file format:
Issue: Blazor WebAssembly is designed to run in the browser, which can be a restrictive environment for .NET assemblies. You need a way to package .NET assemblies in a format that’s friendly for web deployment.
Solution: The Webcil file format 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.
3. AOT compilation:
Issue: By default, Blazor WebAssembly apps run on a .NET runtime that’s compiled to WebAssembly. This provides a flexible, dynamically typed execution environment, but it can come with a performance cost. You need a way to improve the runtime performance of your Blazor WebAssembly app.
Solution: Blazor WebAssembly supports ahead-of-time (AOT) compilation, where you can compile your .NET code directly into WebAssembly. AOT compilation results in runtime performance improvements at the expense of a larger app size. This means your app runs faster, but the published output is larger.
Conclusion
In this article, we’ve explored the various methods to host and deploy Blazor WebAssembly applications. We’ve delved into the details of different hosting models and environments, compared the trade-offs of different deployment modes, and provided practical tips and tools for publishing and deploying your apps.
Understanding these concepts is crucial for effectively deploying Blazor WebAssembly applications. Whether you choose to use a framework-dependent or self-contained deployment mode or host your application on IIS, Azure App Service, Amazon S3, or any other platform, the choice ultimately depends on your specific requirements and constraints.