No example usage for setting blazor-environment header in a standalone Blazor wasm app not using IIS

[nicholasyin]

Description

The documentation only gives example of configuring IIS via web.config file. What if I'm developing under Linux/MacOS and can only use dotnet CLI/VSCode to launch and debug?

Page URL

https://learn.microsoft.com/en-us/aspnet/core/blazor/fundamentals/environments?view=aspnetcore-9.0#set-the-client-side-environment-via-blazor-startup-configuration

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/blazor/fundamentals/environments.md

Document ID

8a5b47e7-b29c-b049-30e8-5b405a5086b6

Article author

@guardrex

Related Issues

[github-actions]

🏂🎁 Happy Holidays! ❄️⛄

Stand-by! ... A green dinosaur 🦖 will be along shortly to assist.

[guardrex]

Hello @nicholasyin ... Try using the launchSettings.json file in the Properties folder. Set it via the environment variable. For example in the https profile when running with HTTPS:

"environmentVariables": {
  "ASPNETCORE_ENVIRONMENT": "Staging"
}

If you're running with the http profile for HTTP (insecure), then set it in that section of the file.

Leave this issue open.

[guardrex]

I think this line ...

For a standalone Blazor WebAssembly app running locally, the development server adds the blazor-environment header.

... is what will need an update. What's happening ... I think 🤔 ... is that the development server (basically Kestrel via Blazor startup) is reading the environment variable from launch settings configuration and setting the header. This is only when running the app locally. For hosting scenarios, I think you must set the header on your own using the file server (if you're trying to use something different than the published default of Production for the environment).

I'll talk to Steve offline about this tomorrow and come back with the answer, then I'll see about updating this aspect of the article.

UPDATE (12/18): The last part of my remark on using either Blazor.start config or setting the header for file server situations is correct. I'm waiting now for confirmation that the development server is taking the environment from the launchSettings.json file with the precedence of ...

Blazor.start config (environment key) > blazor-environment header > ASPNETCORE_ENVIRONMENT (launchSettings.json file)

[nicholasyin]

Hello @nicholasyin ... Try using the launchSettings.json file in the Properties folder. Set it via the environment variable. For example in the https profile when running with HTTPS:

"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Staging"
}
If you're running with the http profile for HTTP (insecure), then set it in that section of the file.

Leave this issue open.

What if I want to set for testing/production environment? Can I also set in launchSettings.json and it will be read during startup?

[guardrex]

Yes, but keep in mind that this approach that we're discussing with the launchSettings.json file is for the development server running locally. It won't work when publishing the app to a file server host somewhere in a production deployment.

For a published app, the only two current ways to set the environment are via Blazor.start (environment key) and the blazor-environment response header set on the blazor.boot.json file (or, of course, you can set the response header on any file from the deployment ... the important file to have it is the blazor.boot.json file because that's the one that Blazor is going to read the header from).

The issue that I cross-linked on the PR is where the team is looking at improving the features ...

dotnet/aspnetcore#59456

They have that scheduled for consideration for .NET 10 (November, 2025) ... but only for consideration ... they might cut it and push it back to .NET 11 (November, 2026). That happens quite a bit with features under consideration.