Configuração do Blazor ASP.NET Core

Este artigo explica como configurar os aplicativos Blazor, incluindo configurações de aplicativo, autenticação e configuração de log.

Essas diretrizes se aplicam à configuração de projeto do lado do cliente em um Blazor Web App ou em um aplicativo Blazor WebAssembly autônomo.

Comportamentos padrão em Blazor Web Apps:

• Para configuração no lado do servidor:
  • Confira Configuração no ASP.NET Core para obter orientação.
  • Somente a configuração nos arquivos de configurações do aplicativo raiz do projeto é carregada.
  • O restante deste artigo se aplica apenas à configuração do lado do cliente no projeto .Client.
• Para configuração do lado do cliente (projeto .Client), a configuração é carregada dos seguintes arquivos de configurações de aplicativo:
  • wwwroot/appsettings.json.
  • wwwroot/appsettings.{ENVIRONMENT}.json, em que o espaço reservado {ENVIRONMENT} é o ambiente de runtime do aplicativo.

Em aplicativos Blazor WebAssembly autônomos, a configuração é carregada dos seguintes arquivos de configurações de aplicativo:

• wwwroot/appsettings.json.
• wwwroot/appsettings.{ENVIRONMENT}.json, em que o espaço reservado {ENVIRONMENT} é o ambiente de runtime do aplicativo.

Observação

A configuração de registro em log colocada em um arquivo de configurações de aplicativo no wwwroot não é carregada por padrão. Para obter informações, consulte a seção Configuração de log presente mais adiante neste artigo.

Em alguns cenários, como nos serviços do Azure, é importante usar um segmento de nome de arquivo do ambiente que corresponda exatamente ao nome do ambiente. Por exemplo, use o nome de arquivo appsettings.Staging.json com uma "S" em maiúscula para o ambiente Staging. Para obter as convenções recomendadas, consulte os comentários de abertura dos ambientesBlazor do ASP.NET Core.

Outros provedores de configuração registrados pelo aplicativo também podem fornecer configuração, mas nem todos os provedores ou recursos do provedor são apropriados:

• Provedor de configuração do Azure Key Vault: o provedor não é compatível com identity gerenciada e ID do aplicativo (ID do cliente) com cenários de segredo do cliente. A ID do aplicativo com um segredo do cliente não é recomendada para nenhum aplicativo ASP.NET Core, especialmente aplicativos do lado do cliente porque o segredo do cliente não pode ser protegido do lado do cliente para acessar o serviço Azure Key Vault.
• Provedor de configuração de Aplicativos do Azure: o provedor não é apropriado para um aplicativo do lado do cliente porque o aplicativo não é executado em um servidor no Azure.

Para obter mais informações sobre provedores de configuração, confira Configuração no ASP.NET Core.

Aviso

Os arquivos de configuração e definição na raiz da Web (pasta wwwroot) são visíveis para os usuários no cliente, e os usuários podem adulterar os dados. Não armazene segredos, credenciais ou outros dados confidenciais em nenhum arquivo raiz da Web.

Definição de configurações de aplicativo

A configuração nos arquivos de configurações de aplicativo é carregada por padrão. No exemplo a seguir, um valor de configuração da interface do usuário é armazenado em um arquivo de configurações de aplicativo e carregado pela estrutura Blazor automaticamente. O valor é lido por um componente.

wwwroot/appsettings.json:

{
    "h1FontSize": "50px"
}

Injete uma instância IConfiguration em um componente para acessar os dados de configuração.

ConfigExample.razor:

@page "/config-example"
@inject IConfiguration Configuration

<PageTitle>Configuration</PageTitle>

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

As restrições de segurança do cliente impedem o acesso direto aos arquivos pelo código do usuário, incluindo arquivos de configurações da configuração do aplicativo. Para ler arquivos de configuração além appsettings.json/appsettings.{ENVIRONMENT}.json da wwwroot pasta na configuração, use um HttpClient.

Aviso

Os arquivos de configuração e definição na raiz da Web (pasta wwwroot) são visíveis para os usuários no cliente, e os usuários podem adulterar os dados. Não armazene segredos, credenciais ou outros dados confidenciais em nenhum arquivo raiz da Web.

O exemplo a seguir lê um arquivo de configuração (cars.json) na configuração do aplicativo.

wwwroot/cars.json:

{
    "size": "tiny"
}

Adicione o namespace do Microsoft.Extensions.Configuration ao arquivo Program:

using Microsoft.Extensions.Configuration;

Modifique o registro de serviço HttpClient existente para usar o cliente para ler o arquivo:

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

O exemplo anterior define o endereço base com builder.HostEnvironment.BaseAddress (IWebAssemblyHostEnvironment.BaseAddress), que obtém o endereço base do aplicativo e normalmente é derivado do valor href da marca <base> na página do host.

Fonte de configuração de memória

O exemplo a seguir usa um MemoryConfigurationSource no arquivo Program para fornecer configuração adicional.

Adicione o namespace do Microsoft.Extensions.Configuration.Memory ao arquivo Program:

using Microsoft.Extensions.Configuration.Memory;

No arquivo Program:

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

Injete uma instância IConfiguration em um componente para acessar os dados de configuração.

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>

Obtenha uma seção da configuração no código C# com IConfiguration.GetSection. O exemplo a seguir obtém a seção wheels para a configuração no exemplo anterior:

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

        ...
    }
}

Configuração de autenticação

Forneça a configuração de autenticação pública em um arquivo de configurações do aplicativo.

wwwroot/appsettings.json:

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

Carregue a configuração de um provedor Identity com ConfigurationBinder.Bind no arquivo Program. O exemplo a seguir carrega a configuração de um provedor OIDC:

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

Aviso

Os arquivos de configuração e definição na raiz da Web (pasta wwwroot) são visíveis para os usuários no cliente, e os usuários podem adulterar os dados. Não armazene segredos, credenciais ou outros dados confidenciais em nenhum arquivo raiz da Web.

Configuração de log

Esta seção se aplica aos aplicativos que configuram o registro de log por um arquivo de configurações de aplicativo na pasta wwwroot.

Adicione o pacote Microsoft.Extensions.Logging.Configuration ao aplicativo.

Observação

Para obter diretrizes sobre como adicionar pacotes a aplicativos .NET, consulte os artigos em Instalar e gerenciar pacotes no Fluxo de trabalho de consumo de pacotes (documentação do NuGet). Confirme as versões corretas de pacote em NuGet.org.

No arquivo de configurações do aplicativo, forneça a configuração de log. A configuração de log é carregada no arquivo Program.

wwwroot/appsettings.json:

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

No arquivo Program:

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

Configuração do construtor de host

Leia a configuração do construtor do host de WebAssemblyHostBuilder.Configuration no arquivo Program:

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

Configuração armazenada em cache

Os arquivos de configuração são armazenados em cache para uso offline. Com PWAs (Aplicativos Web Progressivos), você só pode atualizar arquivos de configuração ao criar uma nova implantação. A edição de arquivos de configuração entre implantações não tem efeito porque:

• Os usuários armazenaram em cache as versões dos arquivos que continuam a usar.
• Os arquivos service-worker.js e service-worker-assets.js do PWA devem ser recriados na compilação, o que, na próxima visita online do usuário, sinaliza para o aplicativo que o aplicativo foi reimplantado.

Para obter mais informações sobre como as atualizações em segundo plano são tratadas por PWAs, confira PWA (Aplicativo Web Progressivo) do ASP.NET Core Blazor.

Configuração de opções

A Configuração de opções requer a adição de uma referência de pacote no Microsoft.Extensions.Options.ConfigurationExtensions pacote NuGet.

Observação

Para obter diretrizes sobre como adicionar pacotes a aplicativos .NET, consulte os artigos em Instalar e gerenciar pacotes no Fluxo de trabalho de consumo de pacotes (documentação do NuGet). Confirme as versões corretas de pacote em NuGet.org.

Exemplo:

builder.Services.Configure<MyOptions>(
    builder.Configuration.GetSection("MyOptions"));

Nem todos os recursos de opções do ASP.NET Core têm suporte em componentes Razor. Por exemplo, há suporte para as configurações IOptionsSnapshot<TOptions> e IOptionsMonitor<TOptions>, mas não há suporte para recalcular valores de opção para essas interfaces fora do recarregamento do aplicativo ao solicitar o aplicativo em uma nova guia do navegador ou ao selecionar o botão recarregar do navegador. Simplesmente chamar StateHasChanged não atualiza o instantâneo ou os valores de opção monitorados quando a configuração subjacente é alterada.