Training
Module
Externalize the configuration of an ASP.NET app by using an Azure key vault - Training
Learn how to use ConfigurationBuilder to dynamically configure an ASP.NET web app to retrieve secrets from an Azure key vault.
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Note
This isn't the latest version of this article. For the current release, see the .NET 9 version of this article.
Warning
This version of ASP.NET Core is no longer supported. For more information, see the .NET and .NET Core Support Policy. For the current release, see the .NET 9 version of this article.
Important
This information relates to a pre-release product that may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
For the current release, see the .NET 9 version of this article.
This article explains how to configure Blazor apps, including app settings, authentication, and logging configuration.
This guidance applies to client-side project configuration in a Blazor Web App or a standalone Blazor WebAssembly app.
Default behavior in Blazor Web Apps:
.Client
project..Client
project), configuration is loaded from the following app settings files:
wwwroot/appsettings.json
.wwwroot/appsettings.{ENVIRONMENT}.json
, where the {ENVIRONMENT}
placeholder is the app's runtime environment.In standalone Blazor WebAssembly apps, configuration is loaded from the following app settings files:
wwwroot/appsettings.json
.wwwroot/appsettings.{ENVIRONMENT}.json
, where the {ENVIRONMENT}
placeholder is the app's runtime environment.This guidance applies to the Client
project of a hosted Blazor WebAssembly solution or a Blazor WebAssembly app.
For server-side ASP.NET Core app configuration in the Server
project of a hosted Blazor WebAssembly solution, see Configuration in ASP.NET Core.
On the client, configuration is loaded from the following app settings files:
wwwroot/appsettings.json
.wwwroot/appsettings.{ENVIRONMENT}.json
, where the {ENVIRONMENT}
placeholder is the app's runtime environment.Note
Logging configuration placed into an app settings file in wwwroot
isn't loaded by default. For more information, see the Logging configuration section later in this article.
In some scenarios, such as with Azure services, it's important to use an environment file name segment that exactly matches the environment name. For example, use the file name appsettings.Staging.json
with a capital "S" for the Staging
environment. For recommended conventions, see the opening remarks of ASP.NET Core Blazor environments.
Other configuration providers registered by the app can also provide configuration, but not all providers or provider features are appropriate:
For more information on configuration providers, see Configuration in ASP.NET Core.
Warning
Configuration and settings files in the web root (wwwroot
folder) are visible to users on the client, and users can tamper with the data. Don't store app secrets, credentials, or any other sensitive data in any web root file.
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.
ConfigExample.razor
:
@page "/config-example"
@inject IConfiguration Configuration
<PageTitle>Configuration</PageTitle>
<h1 style="font-size:@Configuration["h1FontSize"]">
Configuration example (50px)
</h1>
@page "/config-example"
@inject IConfiguration Configuration
<PageTitle>Configuration</PageTitle>
<h1 style="font-size:@Configuration["h1FontSize"]">
Configuration example (50px)
</h1>
@page "/config-example"
@inject IConfiguration Configuration
<h1 style="font-size:@Configuration["h1FontSize"]">
Configuration example
</h1>
@page "/config-example"
@inject IConfiguration Configuration
<h1 style="font-size:@Configuration["h1FontSize"]">
Configuration example
</h1>
@page "/config-example"
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration
<h1 style="font-size:@Configuration["h1FontSize"]">
Configuration example
</h1>
@page "/config-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 via user code, 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 HttpClient.
Warning
Configuration and settings files in the web root (wwwroot
folder) are visible to users on the client, and users can tamper with the data. Don't store app secrets, credentials, or any other sensitive data in any web root file.
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 the Program
file:
using Microsoft.Extensions.Configuration;
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);
The preceding example sets the base address with builder.HostEnvironment.BaseAddress
(IWebAssemblyHostEnvironment.BaseAddress), which gets the base address for the app and is typically derived from the <base>
tag's href
value in the host page.
The following example uses a MemoryConfigurationSource in the Program
file to supply additional configuration.
Add the namespace for Microsoft.Extensions.Configuration.Memory to the Program
file:
using Microsoft.Extensions.Configuration.Memory;
In the Program
file:
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.
MemoryConfig.razor
:
@page "/memory-config"
@inject IConfiguration Configuration
<PageTitle>Memory Configuration</PageTitle>
<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>
@page "/memory-config"
@inject IConfiguration Configuration
<PageTitle>Memory Configuration</PageTitle>
<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>
@page "/memory-config"
@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>
@page "/memory-config"
@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>
@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>
@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");
...
}
}
Provide public 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 the Program
file. The following example loads configuration for an OIDC provider:
builder.Services.AddOidcAuthentication(options =>
builder.Configuration.Bind("Local", options.ProviderOptions));
Warning
Configuration and settings files in the web root (wwwroot
folder) are visible to users on the client, and users can tamper with the data. Don't store app secrets, credentials, or any other sensitive data in any web root file.
This section applies to apps that configure logging via an app settings file in the wwwroot
folder.
Add the Microsoft.Extensions.Logging.Configuration
package to the app.
Note
For guidance on adding packages to .NET apps, see the articles under Install and manage packages at Package consumption workflow (NuGet documentation). Confirm correct package versions at NuGet.org.
In the app settings file, provide logging configuration. The logging configuration is loaded in the Program
file.
wwwroot/appsettings.json
:
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
}
}
In the Program
file:
builder.Logging.AddConfiguration(
builder.Configuration.GetSection("Logging"));
Read host builder configuration from WebAssemblyHostBuilder.Configuration in the Program
file:
var hostname = builder.Configuration["HostName"];
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:
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 ASP.NET Core Blazor Progressive Web Application (PWA).
Options configuration requires adding a package reference for the Microsoft.Extensions.Options.ConfigurationExtensions
NuGet package.
Note
For guidance on adding packages to .NET apps, see the articles under Install and manage packages at Package consumption workflow (NuGet documentation). Confirm correct package versions at NuGet.org.
Example:
builder.Services.Configure<MyOptions>(
builder.Configuration.GetSection("MyOptions"));
Not all of the ASP.NET Core Options features are supported in Razor components. For example, IOptionsSnapshot<TOptions> and IOptionsMonitor<TOptions> configuration is supported, but recomputing option values for these interfaces isn't supported outside of reloading the app by either requesting the app in a new browser tab or selecting the browser's reload button. Merely calling StateHasChanged
doesn't update snapshot or monitored option values when the underlying configuration changes.
ASP.NET Core feedback
ASP.NET Core is an open source project. Select a link to provide feedback:
Training
Module
Externalize the configuration of an ASP.NET app by using an Azure key vault - Training
Learn how to use ConfigurationBuilder to dynamically configure an ASP.NET web app to retrieve secrets from an Azure key vault.