diff --git a/aspnetcore/blazor/fundamentals/configuration.md b/aspnetcore/blazor/fundamentals/configuration.md index e9892cafb00d..d4216a29ff3e 100644 --- a/aspnetcore/blazor/fundamentals/configuration.md +++ b/aspnetcore/blazor/fundamentals/configuration.md @@ -12,8 +12,6 @@ uid: blazor/fundamentals/configuration This article explains configuration of Blazor apps, including app settings, authentication, and logging configuration. -:::moniker range=">= aspnetcore-6.0" - > [!IMPORTANT] > This topic applies to Blazor WebAssembly. For general guidance on ASP.NET Core app configuration, see . @@ -254,509 +252,3 @@ builder.Services.Configure( ``` Not all of the ASP.NET Core Options features are supported in Razor components. For example, and 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`](xref:blazor/components/lifecycle#state-changes-statehaschanged) doesn't update snapshot or monitored option values when the underlying configuration changes. - -:::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 . - -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](xref:fundamentals/environments). - -> [!NOTE] -> Logging configuration placed into an app settings file in `wwwroot` of a Blazor WebAssembly app isn't loaded by default. For for information, see the [Logging configuration](#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 for Blazor WebAssembly apps: - -* [Azure Key Vault configuration provider](xref:security/key-vault-configuration): 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](/azure/azure-app-configuration/quickstart-aspnet-core-app): 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 . - -## 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`: - -```json -{ - "h1FontSize": "50px" -} -``` - -Inject an instance into a component to access the configuration data. - -`Pages/ConfigurationExample.razor`: - -```razor -@page "/configuration-example" -@using Microsoft.Extensions.Configuration -@inject IConfiguration Configuration - -

- Configuration example -

-``` - -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 . - -> [!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`: - -```json -{ - "size": "tiny" -} -``` - -Add the namespace for to `Program.cs`: - -```csharp -using Microsoft.Extensions.Configuration; -``` - -In `Program.cs`, modify the existing service registration to use the client to read the file: - -```csharp -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 in `Program.cs` to supply additional configuration. - -Add the namespace for to `Program.cs`: - -```csharp -using Microsoft.Extensions.Configuration.Memory; -``` - -In `Program.cs`: - -```csharp -var vehicleData = new Dictionary() -{ - { "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 instance into a component to access the configuration data. - -`Pages/MemoryConfig.razor`: - -```razor -@page "/memory-config" -@using Microsoft.Extensions.Configuration -@inject IConfiguration Configuration - -

Memory configuration example

- -

General specifications

- -
    -
  • Color: @Configuration["color"]
  • -
  • Type: @Configuration["type"]
  • -
- -

Wheels

- -
    -
  • Count: @Configuration["wheels:count"]
  • -
  • Brand: @Configuration["wheels:brand"]
  • -
  • Type: @Configuration["wheels:brand:type"]
  • -
  • Year: @Configuration["wheels:year"]
  • -
-``` - -Obtain a section of the configuration in C# code with . The following example obtains the `wheels` section for the configuration in the preceding example: - -```razor -@code { - protected override void OnInitialized() - { - var wheelsSection = Configuration.GetSection("wheels"); - - ... - } -} -``` - -## Authentication configuration - -Provide authentication configuration in an app settings file. - -`wwwroot/appsettings.json`: - -```json -{ - "Local": { - "Authority": "{AUTHORITY}", - "ClientId": "{CLIENT ID}" - } -} -``` - -Load the configuration for an Identity provider with in `Program.cs`. The following example loads configuration for an [OIDC provider](xref:blazor/security/webassembly/standalone-with-authentication-library). - -`Program.cs`: - -```csharp -builder.Services.AddOidcAuthentication(options => - builder.Configuration.Bind("Local", options.ProviderOptions)); -``` - -## Logging configuration - -*This section applies to Blazor WebAssembly apps that configure logging via an app settings file in the `wwwroot` folder.* - -Add the [`Microsoft.Extensions.Logging.Configuration`](https://www.nuget.org/packages/Microsoft.Extensions.Logging.Configuration) package to the app. - -[!INCLUDE[](~/includes/package-reference.md)] - -In the app settings file, provide logging configuration. The logging configuration is loaded in `Program.cs`. - -`wwwroot/appsettings.json`: - -```json -{ - "Logging": { - "LogLevel": { - "Default": "Information", - "Microsoft": "Warning", - "Microsoft.Hosting.Lifetime": "Information" - } - } -} -``` - -Add the namespace for to `Program.cs`: - -```csharp -using Microsoft.Extensions.Logging; -``` - -In `Program.cs`: - -```csharp -builder.Logging.AddConfiguration( - builder.Configuration.GetSection("Logging")); -``` - -## Host builder configuration - -Read host builder configuration from in `Program.cs`. - -In `Program.cs`: - -```csharp -var hostname = builder.Configuration["HostName"]; -``` - -## Cached configuration - -Configuration files are cached for offline use. With [Progressive Web Applications (PWAs)](xref:blazor/progressive-web-app), 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 . - -## Options configuration - -[Options configuration](xref:fundamentals/configuration/options) for Blazor WebAssembly apps requires adding a package reference for the [`Microsoft.Extensions.Options.ConfigurationExtensions`](https://www.nuget.org/packages/Microsoft.Extensions.Options.ConfigurationExtensions) NuGet package. - -[!INCLUDE[](~/includes/package-reference.md)] - -Example: - -```csharp -builder.Services.Configure( - builder.Configuration.GetSection("MyOptions")); -``` - -Not all of the ASP.NET Core Options features are supported in Razor components. For example, and 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`](xref:blazor/components/lifecycle#state-changes-statehaschanged) doesn't update snapshot or monitored option values when the underlying configuration changes. - -:::moniker-end - -:::moniker range="< aspnetcore-5.0" - -> [!NOTE] -> This topic applies to Blazor WebAssembly. For general guidance on ASP.NET Core app configuration, see . - -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](xref:fundamentals/environments). - -> [!NOTE] -> Logging configuration placed into an app settings file in `wwwroot` of a Blazor WebAssembly app isn't loaded by default. For for information, see the [Logging configuration](#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 for Blazor WebAssembly apps: - -* [Azure Key Vault configuration provider](xref:security/key-vault-configuration): 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](/azure/azure-app-configuration/quickstart-aspnet-core-app): 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 . - -## 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`: - -```json -{ - "h1FontSize": "50px" -} -``` - -Inject an instance into a component to access the configuration data. - -`Pages/ConfigurationExample.razor`: - -```razor -@page "/configuration-example" -@using Microsoft.Extensions.Configuration -@inject IConfiguration Configuration - -

- Configuration example -

-``` - -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 . - -> [!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`: - -```json -{ - "size": "tiny" -} -``` - -Add the namespace for to `Program.cs`: - -```csharp -using Microsoft.Extensions.Configuration; -``` - -In `Program.cs`, modify the existing service registration to use the client to read the file: - -```csharp -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 in `Program.cs` to supply additional configuration. - -Add the namespace for to `Program.cs`: - -```csharp -using Microsoft.Extensions.Configuration.Memory; -``` - -In `Program.cs`: - -```csharp -var vehicleData = new Dictionary() -{ - { "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 instance into a component to access the configuration data. - -`Pages/MemoryConfig.razor`: - -```razor -@page "/memory-config" -@using Microsoft.Extensions.Configuration -@inject IConfiguration Configuration - -

Memory configuration example

- -

General specifications

- -
    -
  • Color: @Configuration["color"]
  • -
  • Type: @Configuration["type"]
  • -
- -

Wheels

- -
    -
  • Count: @Configuration["wheels:count"]
  • -
  • Brand: @Configuration["wheels:brand"]
  • -
  • Type: @Configuration["wheels:brand:type"]
  • -
  • Year: @Configuration["wheels:year"]
  • -
-``` - -Obtain a section of the configuration in C# code with . The following example obtains the `wheels` section for the configuration in the preceding example: - -```razor -@code { - protected override void OnInitialized() - { - var wheelsSection = Configuration.GetSection("wheels"); - - ... - } -} -``` - -## Authentication configuration - -Provide authentication configuration in an app settings file. - -`wwwroot/appsettings.json`: - -```json -{ - "Local": { - "Authority": "{AUTHORITY}", - "ClientId": "{CLIENT ID}" - } -} -``` - -Load the configuration for an Identity provider with in `Program.cs`. The following example loads configuration for an [OIDC provider](xref:blazor/security/webassembly/standalone-with-authentication-library). - -`Program.cs`: - -```csharp -builder.Services.AddOidcAuthentication(options => - builder.Configuration.Bind("Local", options.ProviderOptions)); -``` - -## Logging configuration - -*This section applies to Blazor WebAssembly apps that configure logging via an app settings file in the `wwwroot` folder.* - -Add the [`Microsoft.Extensions.Logging.Configuration`](https://www.nuget.org/packages/Microsoft.Extensions.Logging.Configuration) package to the app. - -[!INCLUDE[](~/includes/package-reference.md)] - -In the app settings file, provide logging configuration. The logging configuration is loaded in `Program.cs`. - -`wwwroot/appsettings.json`: - -```json -{ - "Logging": { - "LogLevel": { - "Default": "Information", - "Microsoft": "Warning", - "Microsoft.Hosting.Lifetime": "Information" - } - } -} -``` - -Add the namespace for to `Program.cs`: - -```csharp -using Microsoft.Extensions.Logging; -``` - -In `Program.cs`: - -```csharp -builder.Logging.AddConfiguration( - builder.Configuration.GetSection("Logging")); -``` - -## Host builder configuration - -Read host builder configuration from in `Program.cs`. - -In `Program.cs`: - -```csharp -var hostname = builder.Configuration["HostName"]; -``` - -## Cached configuration - -Configuration files are cached for offline use. With [Progressive Web Applications (PWAs)](xref:blazor/progressive-web-app), 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 . - -## Options configuration - -[Options configuration](xref:fundamentals/configuration/options) for Blazor WebAssembly apps requires adding a package reference for the [`Microsoft.Extensions.Options.ConfigurationExtensions`](https://www.nuget.org/packages/Microsoft.Extensions.Options.ConfigurationExtensions) NuGet package. - -[!INCLUDE[](~/includes/package-reference.md)] - -Example: - -```csharp -builder.Services.Configure( - builder.Configuration.GetSection("MyOptions")); -``` - -Not all of the ASP.NET Core Options features are supported in Razor components. For example, and 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`](xref:blazor/components/lifecycle#state-changes-statehaschanged) doesn't update snapshot or monitored option values when the underlying configuration changes. - -:::moniker-end