Deployment

Publishing turns a project into a set of files something can host. For most .NET applications that sentence is the whole story. For Blazor it is not, because what publish produces depends on the hosting model — and therefore so does what can host it, and what can go wrong.

The decision from the first lesson in this course arrives again here, with different consequences. A Blazor Server application publishes as an ASP.NET Core application: it runs, it holds state, it needs a live connection to every user. A standalone WebAssembly application publishes as static files: nothing runs on the server, and the server's only job is to hand out those files correctly.

Most deployment problems in Blazor are one of a small number of specific things, and almost all of them are in the host rather than in your code. This lesson names them.

# Always Release for a deployment
dotnet publish -c Release -o ./publish

# Blazor Server: the whole folder is the deployment, and it runs
cd publish
./EmployeePortal

# Standalone WebAssembly: only wwwroot is deployed
ls ./publish/wwwroot
# index.html  favicon.ico  css/  _framework/

# The compressed copies the host should be serving
ls ./publish/wwwroot/_framework/*.br | head

• -c Release matters more for WebAssembly than for Server. A Release publish trims unused code from the runtime and your assemblies, and the download is substantially smaller. Publishing Debug output is a common and quiet cause of a slow first load.
• For Blazor Server, everything in the output folder is the deployment. The wwwroot inside it is static content served by the same application.
• For standalone WebAssembly, only wwwroot is deployed. The rest of the publish output is build machinery, and copying all of it to a static host is how people end up with a site that serves a directory listing.
• _framework holds the runtime, your assemblies, and a manifest listing every file with a hash. If anything in the pipeline rewrites or re-compresses those files in a way that changes them, the integrity check fails and the application does not start.
• Recent versions package assemblies as .wasm files rather than .dll, partly because some networks and hosts block .dll downloads outright.
• Trimming removes code it cannot see being used, which includes code reached only through reflection. Something that works in development and throws about a missing member after publishing is a trimming problem before it is anything else.
• Ahead-of-time compilation is available for WebAssembly. It speeds up compute-heavy code and makes the download larger, so it earns its place in a calculation-heavy application and not in a set of CRUD screens.

{
  "mimeTypes": {
    ".wasm": "application/wasm",
    ".dat": "application/octet-stream",
    ".blat": "application/octet-stream"
  },
  "navigationFallback": {
    "rewrite": "/index.html",
    "exclude": ["/_framework/*", "/css/*", "/images/*"]
  },
  "globalHeaders": {
    "cache-control": "no-cache"
  }
}

• A .wasm file served as text/plain is refused by the browser's streaming compiler, and the application fails at startup with a message about a module rather than anything resembling your code. Serving it as application/wasm is a host setting, not something you can fix in the project.
• The navigation fallback exists because your routes are client-side. Ask for /employees/42 directly and the host has no such file, so it must return index.html and let the router work the address out.
• Excluding the framework and asset folders from that fallback matters. Without the exclusion, a genuinely missing file returns an HTML page with a 200, and the error you get back is much stranger than a 404.
• Compression is the largest single win available. Publishing produces Brotli and gzip copies of the framework files; whether they are used depends on the host serving them with the right Content-Encoding. The difference is measured in megabytes, so confirm it in the browser's network tab rather than assuming it.
• Cache the hashed framework files hard and index.html not at all. The framework file names change when their contents change, so they are safe to cache for a long time. index.html is the file that points at them, so caching it means people keep running the version from before your last deploy.
• None of this applies to Blazor Server, where ASP.NET Core serves the static content and already knows these types.

@* Components/App.razor, or wwwroot/index.html for standalone WebAssembly *@
<head>
    <base href="/portal/" />
</head>

// Program.cs on the host, when the application lives under /portal
app.UsePathBase("/portal");
app.UseStaticFiles();
app.UseRouting();

• The base element tells the browser and the router where the application's root is. At the site root it is a single slash; under /portal it must be "/portal/", with the leading and trailing slash both present.
• Get it wrong and the symptoms point away from the cause. The page loads and the framework files return 404. Or navigation works until someone refreshes. Or every relative link resolves one level too high and nothing explains why.
• UsePathBase on the host strips the prefix before routing, so your endpoints and components do not each have to know they are living under one.
• NavigationManager resolves addresses against the base, so an application that might move under a sub-path is safer with relative addresses than with hard-coded absolute ones.
• If one build is deployed to more than one path, the base href has to be set per deployment. That belongs in the release pipeline, not in a file someone edits on the server after the fact.
• Test the sub-path deployment before you need it. It is the deployment difference most likely to be discovered late, because everything works at the root on a development machine.