AspNetCore.Docs/aspnetcore/blazor/fundamentals/configuration.md

title	author	description	monikerRange	ms.author	ms.custom	ms.date	no-loc	uid
ASP.NET Core Blazor configuration	guardrex	Learn about configuration of Blazor apps, including app settings, authentication, and logging configuration.	>= aspnetcore-3.1	riande	mvc	11/09/2021	Home Privacy Kestrel appsettings.json ASP.NET Core Identity cookie Cookie Blazor Blazor Server Blazor WebAssembly Identity Let's Encrypt Razor SignalR	blazor/fundamentals/configuration

ASP.NET Core Blazor configuration

::: moniker range=">= aspnetcore-6.0"

[!NOTE] This topic applies to Blazor WebAssembly. For general guidance on ASP.NET Core app configuration, see xref:fundamentals/configuration/index.

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 and settings files in a Blazor WebAssembly app are visible to users. Don't store app secrets, credentials, or any other sensitive data in the configuration or files of a Blazor WebAssembly app.

For more information on configuration providers, see xref:fundamentals/configuration/index.

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 xref:Microsoft.Extensions.Configuration.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>

Client security restrictions prevent direct access to files, including settings files for app configuration. To read configuration files in addition to appsettings.json/appsettings.{ENVIRONMENT}.json from the wwwroot folder into configuration, use an xref:System.Net.Http.HttpClient.

[!WARNING] Configuration and settings files in a Blazor WebAssembly app are visible to users. Don't store app secrets, credentials, or any other sensitive data in the configuration or files of a Blazor WebAssembly app.

The following example reads a configuration file (cars.json) into the app's configuration.

wwwroot/cars.json:

{
    "size": "tiny"
}

Add the namespace for xref:Microsoft.Extensions.Configuration?displayProperty=fullName to Program.cs:

using Microsoft.Extensions.Configuration;

In Program.cs, modify the existing xref:System.Net.Http.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 xref:Microsoft.Extensions.Configuration.Memory.MemoryConfigurationSource in Program.cs to supply additional configuration.

Add the namespace for xref:Microsoft.Extensions.Configuration.Memory?displayProperty=fullName to Program.cs:

using Microsoft.Extensions.Configuration.Memory;

In 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 xref:Microsoft.Extensions.Configuration.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 xref:Microsoft.Extensions.Configuration.IConfiguration.GetSection%2A?displayProperty=nameWithType. 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 xref:Microsoft.Extensions.Configuration.ConfigurationBinder.Bind%2A?displayProperty=nameWithType in Program.cs. The following example loads configuration for an OIDC provider.

Program.cs:

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

Logging configuration

Add the Microsoft.Extensions.Logging.Configuration package to the app.

[!INCLUDE]

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

wwwroot/appsettings.json:

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

Add the namespace for xref:Microsoft.Extensions.Logging?displayProperty=fullName to Program.cs:

using Microsoft.Extensions.Logging;

In Program.cs:

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

Host builder configuration

Read host builder configuration from xref:Microsoft.AspNetCore.Components.WebAssembly.Hosting.WebAssemblyHostBuilder.Configuration?displayProperty=nameWithType in Program.cs.

In 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 xref:blazor/progressive-web-app#background-updates.

::: moniker-end

::: moniker range=">= aspnetcore-5.0 < aspnetcore-6.0"

[!NOTE] This topic applies to Blazor WebAssembly. For general guidance on ASP.NET Core app configuration, see xref:fundamentals/configuration/index.

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 and settings files in a Blazor WebAssembly app are visible to users. Don't store app secrets, credentials, or any other sensitive data in the configuration or files of a Blazor WebAssembly app.

For more information on configuration providers, see xref:fundamentals/configuration/index.

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 xref:Microsoft.Extensions.Configuration.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>

Client security restrictions prevent direct access to files, including settings files for app configuration. To read configuration files in addition to appsettings.json/appsettings.{ENVIRONMENT}.json from the wwwroot folder into configuration, use an xref:System.Net.Http.HttpClient.

[!WARNING] Configuration and settings files in a Blazor WebAssembly app are visible to users. Don't store app secrets, credentials, or any other sensitive data in the configuration or files of a Blazor WebAssembly app.

The following example reads a configuration file (cars.json) into the app's configuration.

wwwroot/cars.json:

{
    "size": "tiny"
}

Add the namespace for xref:Microsoft.Extensions.Configuration?displayProperty=fullName to Program.cs:

using Microsoft.Extensions.Configuration;

In Program.cs, modify the existing xref:System.Net.Http.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 xref:Microsoft.Extensions.Configuration.Memory.MemoryConfigurationSource in Program.cs to supply additional configuration.

Add the namespace for xref:Microsoft.Extensions.Configuration.Memory?displayProperty=fullName to Program.cs:

using Microsoft.Extensions.Configuration.Memory;

In 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 xref:Microsoft.Extensions.Configuration.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 xref:Microsoft.Extensions.Configuration.IConfiguration.GetSection%2A?displayProperty=nameWithType. 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 xref:Microsoft.Extensions.Configuration.ConfigurationBinder.Bind%2A?displayProperty=nameWithType in Program.cs. The following example loads configuration for an OIDC provider.

Program.cs:

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

Logging configuration

Add the Microsoft.Extensions.Logging.Configuration package to the app.

[!INCLUDE]

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

wwwroot/appsettings.json:

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

Add the namespace for xref:Microsoft.Extensions.Logging?displayProperty=fullName to Program.cs:

using Microsoft.Extensions.Logging;

In Program.cs:

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

Host builder configuration

Read host builder configuration from xref:Microsoft.AspNetCore.Components.WebAssembly.Hosting.WebAssemblyHostBuilder.Configuration?displayProperty=nameWithType in Program.cs.

In 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 xref:blazor/progressive-web-app#background-updates.

::: moniker-end

::: moniker range="< aspnetcore-5.0"

[!NOTE] This topic applies to Blazor WebAssembly. For general guidance on ASP.NET Core app configuration, see xref:fundamentals/configuration/index.

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 and settings files in a Blazor WebAssembly app are visible to users. Don't store app secrets, credentials, or any other sensitive data in the configuration or files of a Blazor WebAssembly app.

For more information on configuration providers, see xref:fundamentals/configuration/index.

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 xref:Microsoft.Extensions.Configuration.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>

Client security restrictions prevent direct access to files, including settings files for app configuration. To read configuration files in addition to appsettings.json/appsettings.{ENVIRONMENT}.json from the wwwroot folder into configuration, use an xref:System.Net.Http.HttpClient.

[!WARNING] Configuration and settings files in a Blazor WebAssembly app are visible to users. Don't store app secrets, credentials, or any other sensitive data in the configuration or files of a Blazor WebAssembly app.

The following example reads a configuration file (cars.json) into the app's configuration.

wwwroot/cars.json:

{
    "size": "tiny"
}

Add the namespace for xref:Microsoft.Extensions.Configuration?displayProperty=fullName to Program.cs:

using Microsoft.Extensions.Configuration;

In Program.cs, modify the existing xref:System.Net.Http.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 xref:Microsoft.Extensions.Configuration.Memory.MemoryConfigurationSource in Program.cs to supply additional configuration.

Add the namespace for xref:Microsoft.Extensions.Configuration.Memory?displayProperty=fullName to Program.cs:

using Microsoft.Extensions.Configuration.Memory;

In 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 xref:Microsoft.Extensions.Configuration.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 xref:Microsoft.Extensions.Configuration.IConfiguration.GetSection%2A?displayProperty=nameWithType. 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 xref:Microsoft.Extensions.Configuration.ConfigurationBinder.Bind%2A?displayProperty=nameWithType in Program.cs. The following example loads configuration for an OIDC provider.

Program.cs:

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

Logging configuration

Add the Microsoft.Extensions.Logging.Configuration package to the app.

[!INCLUDE]

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

wwwroot/appsettings.json:

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

Add the namespace for xref:Microsoft.Extensions.Logging?displayProperty=fullName to Program.cs:

using Microsoft.Extensions.Logging;

In Program.cs:

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

Host builder configuration

Read host builder configuration from xref:Microsoft.AspNetCore.Components.WebAssembly.Hosting.WebAssemblyHostBuilder.Configuration?displayProperty=nameWithType in Program.cs.

In 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 xref:blazor/progressive-web-app#background-updates.

::: moniker-end