ASP.NET Core Blazor configuration

Note

This topic applies to Blazor WebAssembly. For general guidance on ASP.NET Core app configuration, see Configuration in ASP.NET Core.

Blazor WebAssembly loads configuration from the following app settings files by default:

  • wwwroot/appsettings.json.
  • wwwroot/appsettings.{ENVIRONMENT}.json, where the {ENVIRONMENT} placeholder is the app's runtime environment.

Other configuration providers registered by the app can also provide configuration, but not all providers or provider features are appropriate for Blazor WebAssembly apps:

  • Azure Key Vault configuration provider: The provider isn't supported for managed identity and application ID (client ID) with client secret scenarios. Application ID with a client secret isn't recommended for any ASP.NET Core app, especially Blazor WebAssembly apps because the client secret can't be secured client-side to access the Azure Key Vault service.
  • Azure App configuration provider: The provider isn't appropriate for Blazor WebAssembly apps because Blazor WebAssembly apps don't run on a server in Azure.

Warning

Configuration in a Blazor WebAssembly app is visible to users. Don't store app secrets, credentials, or any other sensitive data in the configuration of a Blazor WebAssembly app.

For more information on configuration providers, see Configuration in ASP.NET Core.

App settings configuration

Configuration in app settings files are loaded by default. In the following example, a UI configuration value is stored in an app settings file and loaded by the Blazor framework automatically. The value is read by a component.

wwwroot/appsettings.json:

{
  "h1FontSize": "50px"
}

Inject an IConfiguration instance into a component to access the configuration data.

Pages/ConfigurationExample.razor:

@page "/configuration-example"
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<h1 style="font-size:@Configuration["h1FontSize"]">
    Configuration example
</h1>

To read other configuration files from the wwwroot folder into configuration, use an HttpClient to obtain the file's content. The following example reads a configuration file (cars.json) into the app's configuration.

wwwroot/cars.json:

{
    "size": "tiny"
}

Add the namespace for Microsoft.Extensions.Configuration to Program.cs:

using Microsoft.Extensions.Configuration;

In Program.Main of Program.cs, modify the existing HttpClient service registration to use the client to read the file:

var http = new HttpClient()
{
    BaseAddress = new Uri(builder.HostEnvironment.BaseAddress)
};

builder.Services.AddScoped(sp => http);

using var response = await http.GetAsync("cars.json");
using var stream = await response.Content.ReadAsStreamAsync();

builder.Configuration.AddJsonStream(stream);

Memory Configuration Source

The following example uses a MemoryConfigurationSource in Program.Main to supply additional configuration.

Add the namespace for Microsoft.Extensions.Configuration.Memory to Program.cs:

using Microsoft.Extensions.Configuration.Memory;

In Program.Main of Program.cs:

var vehicleData = new Dictionary<string, string>()
{
    { "color", "blue" },
    { "type", "car" },
    { "wheels:count", "3" },
    { "wheels:brand", "Blazin" },
    { "wheels:brand:type", "rally" },
    { "wheels:year", "2008" },
};

var memoryConfig = new MemoryConfigurationSource { InitialData = vehicleData };

builder.Configuration.Add(memoryConfig);

Inject an IConfiguration instance into a component to access the configuration data.

Pages/MemoryConfig.razor:

@page "/memory-config"
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<h1>Memory configuration example</h1>

<h2>General specifications</h2>

<ul>
    <li>Color: @Configuration["color"]</li>
    <li>Type: @Configuration["type"]</li>
</ul>

<h2>Wheels</h2>

<ul>
    <li>Count: @Configuration["wheels:count"]</li>
    <li>Brand: @Configuration["wheels:brand"]</li>
    <li>Type: @Configuration["wheels:brand:type"]</li>
    <li>Year: @Configuration["wheels:year"]</li>
</ul>

Obtain a section of the configuration in C# code with IConfiguration.GetSection. The following example obtains the wheels section for the configuration in the preceding example:

@code {
    protected override void OnInitialized()
    {
        var wheelsSection = Configuration.GetSection("wheels");

        ...
    }
}

Authentication configuration

Provide authentication configuration in an app settings file.

wwwroot/appsettings.json:

{
  "Local": {
    "Authority": "{AUTHORITY}",
    "ClientId": "{CLIENT ID}"
  }
}

Load the configuration for an Identity provider with ConfigurationBinder.Bind in Program.Main. The following example loads configuration for an OIDC provider.

Program.cs:

builder.Services.AddOidcAuthentication(options =>
    builder.Configuration.Bind("Local", options.ProviderOptions));

Logging configuration

Add a package reference for Microsoft.Extensions.Logging.Configuration to the app's project file:

<PackageReference Include="Microsoft.Extensions.Logging.Configuration" Version="{VERSION}" />

In the preceding example, the {VERSION} placeholder is the package's version. Package versions are found at NuGet.org.

In the app settings file, provide logging configuration. The logging configuration is loaded in Program.Main.

wwwroot/appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

Add the namespace for Microsoft.Extensions.Logging to Program.cs:

using Microsoft.Extensions.Logging;

In Program.Main of Program.cs:

builder.Logging.AddConfiguration(
    builder.Configuration.GetSection("Logging"));

Host builder configuration

Read host builder configuration from WebAssemblyHostBuilder.Configuration in Program.Main.

In Program.Main of Program.cs:

var hostname = builder.Configuration["HostName"];

Cached configuration

Configuration files are cached for offline use. With Progressive Web Applications (PWAs), you can only update configuration files when creating a new deployment. Editing configuration files between deployments has no effect because:

  • Users have cached versions of the files that they continue to use.
  • The PWA's service-worker.js and service-worker-assets.js files must be rebuilt on compilation, which signal to the app on the user's next online visit that the app has been redeployed.

For more information on how background updates are handled by PWAs, see Build Progressive Web Applications with ASP.NET Core Blazor WebAssembly.