Skip to content

Latest commit

 

History

History
293 lines (179 loc) · 11 KB

configuration.md

File metadata and controls

293 lines (179 loc) · 11 KB
Raw
title author description monikerRange ms.author ms.custom ms.date uid
ASP.NET Core Blazor configuration
guardrex
Learn about Blazor app configuration, including app settings, authentication, and logging configuration.
>= aspnetcore-3.1
riande
mvc
11/08/2022
blazor/fundamentals/configuration

ASP.NET Core Blazor configuration

[!INCLUDE]

This article explains how to configure Blazor apps, including app settings, authentication, and logging configuration.

[!INCLUDE]

For ASP.NET Core app server-side configuration, see xref:fundamentals/configuration/index.

On the client, configuration is loaded 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.

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.

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

  • 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 client-side 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 client-side apps because they don't run on a server in Azure.

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

Warning

Configuration and settings files 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 the app's configuration or files.

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:

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

:::code language="json" source="~/../blazor-samples/7.0/BlazorSample_WebAssembly/wwwroot/appsettings.json" highlight="2":::

:::moniker-end

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

:::code language="json" source="~/../blazor-samples/6.0/BlazorSample_WebAssembly/wwwroot/appsettings.json" highlight="2":::

:::moniker-end

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

:::code language="json" source="~/../blazor-samples/5.0/BlazorSample_WebAssembly/wwwroot/appsettings.json" highlight="2":::

:::moniker-end

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

:::code language="json" source="~/../blazor-samples/3.1/BlazorSample_WebAssembly/wwwroot/appsettings.json" highlight="2":::

:::moniker-end

Inject an xref:Microsoft.Extensions.Configuration.IConfiguration instance into a component to access the configuration data.

ConfigExample.razor:

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

:::code language="razor" source="~/../blazor-samples/7.0/BlazorSample_WebAssembly/Pages/configuration/ConfigExample.razor":::

:::moniker-end

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

:::code language="razor" source="~/../blazor-samples/6.0/BlazorSample_WebAssembly/Pages/configuration/ConfigExample.razor":::

:::moniker-end

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

:::code language="razor" source="~/../blazor-samples/5.0/BlazorSample_WebAssembly/Pages/configuration/ConfigExample.razor":::

:::moniker-end

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

:::code language="razor" source="~/../blazor-samples/3.1/BlazorSample_WebAssembly/Pages/configuration/ConfigExample.razor":::

:::moniker-end

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 xref:System.Net.Http.HttpClient.

Warning

Configuration and settings files 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 the app's configuration or files.

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 the Program file:

using Microsoft.Extensions.Configuration;

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 the Program file to supply additional configuration.

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

using Microsoft.Extensions.Configuration.Memory;

In the Program file:

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

:::code language="csharp" source="~/../blazor-samples/7.0/BlazorSample_WebAssembly/Program.cs" id="snippet1":::

:::moniker-end

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

:::code language="csharp" source="~/../blazor-samples/6.0/BlazorSample_WebAssembly/Program.cs" id="snippet1":::

:::moniker-end

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

:::code language="csharp" source="~/../blazor-samples/5.0/BlazorSample_WebAssembly/Program.cs" id="snippet1":::

:::moniker-end

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

:::code language="csharp" source="~/../blazor-samples/3.1/BlazorSample_WebAssembly/Program.cs" id="snippet1":::

:::moniker-end

Inject an xref:Microsoft.Extensions.Configuration.IConfiguration instance into a component to access the configuration data.

MemoryConfig.razor:

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

:::code language="razor" source="~/../blazor-samples/7.0/BlazorSample_WebAssembly/Pages/configuration/MemoryConfig.razor":::

:::moniker-end

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

:::code language="razor" source="~/../blazor-samples/6.0/BlazorSample_WebAssembly/Pages/configuration/MemoryConfig.razor":::

:::moniker-end

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

:::code language="razor" source="~/../blazor-samples/5.0/BlazorSample_WebAssembly/Pages/configuration/MemoryConfig.razor":::

:::moniker-end

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

:::code language="razor" source="~/../blazor-samples/3.1/BlazorSample_WebAssembly/Pages/configuration/MemoryConfig.razor":::

:::moniker-end

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 the Program file. The following example loads configuration for an OIDC provider:

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

Logging configuration

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.

[!INCLUDE]

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"));

Host builder configuration

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

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.

Options configuration

Options configuration requires adding a package reference for the Microsoft.Extensions.Options.ConfigurationExtensions NuGet package.

[!INCLUDE]

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, xref:Microsoft.Extensions.Options.IOptionsSnapshot%601 and xref:Microsoft.Extensions.Options.IOptionsMonitor%601 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.