Configuração do ASP.NET Core Blazor

Este artigo explica como configurar Blazor aplicações, incluindo definições de aplicações, autenticação e configuração de registo.

Esta orientação aplica-se à configuração de projeto do lado do cliente numa aplicação Blazor Web App ou numa aplicação autónoma Blazor WebAssembly.

Comportamento padrão em Blazor Web Apps:

• Para configuração do lado do servidor:
  • Consulte Configuração no ASP.NET Core para obter orientações.
  • Somente a configuração nos arquivos de configurações do aplicativo raiz do projeto é carregada.
  • O restante deste artigo só se aplica à configuração do lado do cliente no projeto .Client.
• Para a configuração do lado do cliente (projeto.Client), a configuração é carregada a partir dos seguintes arquivos de configurações do aplicativo:
  • wwwroot/appsettings.json.
  • wwwroot/appsettings.{ENVIRONMENT}.json, onde o marcador {ENVIRONMENT} é o ambiente de tempo de execução do aplicativo.

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

• wwwroot/appsettings.json.
• wwwroot/appsettings.{ENVIRONMENT}.json, onde o marcador {ENVIRONMENT} é o ambiente de tempo de execução do aplicativo.

Nota

A configuração de logging colocada num ficheiro de definições da aplicação no wwwroot não é carregada automaticamente. Para obter mais informações, consulte a seção Logging configuration mais adiante neste artigo.

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

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 é suportado para identidade gerida e ID da aplicação (ID do cliente) em cenários com 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 Cofre da Chave do Azure.
• provedor de configuração do Aplicativo 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, consulte Configuração no ASP.NET Core.

Aviso

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

Configuração de definições da aplicação

As configurações nos ficheiros de configuração da aplicação são carregadas por padrão. No exemplo a seguir, um valor de configuração da interface do usuário é armazenado em um arquivo de configurações do 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 por meio do código do usuário, incluindo arquivos de configurações para a configuração do aplicativo. Para ler os arquivos de configuração, juntamente com appsettings.json/appsettings.{ENVIRONMENT}.json da pasta wwwroot para a configuração, use um HttpClient.

Aviso

Os arquivos de configuração e definições na raiz da Web (pastawwwroot) são visíveis para os usuários no cliente e os usuários podem adulterar os dados. Não armazene segredos de aplicativos, credenciais ou quaisquer 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 para Microsoft.Extensions.Configuration ao arquivo Program:

using Microsoft.Extensions.Configuration;

Modifique o registro de serviço de 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 para o aplicativo e normalmente é derivado do valor <base> da tag href na página de 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 para Microsoft.Extensions.Configuration.Memory ao arquivo Program:

using Microsoft.Extensions.Configuration.Memory;

No ficheiro 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 em 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 configuração de autenticação pública de num arquivo de definições da aplicação.

wwwroot/appsettings.json:

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

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

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

Aviso

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

Configuração de registro em log

Esta secção aplica-se a aplicações que configuram o registo através de um ficheiro de definições da aplicação na pasta wwwroot.

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

Nota

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

No arquivo de configurações da aplicação, 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 ficheiro Program:

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

Configuração do construtor de hosts

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

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

Configuração em cache

Os arquivos de configuração são armazenados em cache para uso offline. Com Progressive Web Applications (PWAs), 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 têm versões em cache dos arquivos que continuam a usar.
• Os ficheiros service-worker.js e service-worker-assets.js do PWA devem ser reconstruídos durante a compilação, o que indica à aplicação que, na próxima vez que o utilizador estiver online, a aplicação foi reimplantada.

Para obter mais informações sobre como as atualizações em segundo plano são tratadas pelos PWAs, consulte ASP.NET Core Blazor Progressive Web Application (PWA).

Configuração de opções

Opções de configuração requerem a adição de uma referência de pacote para o pacote NuGet Microsoft.Extensions.Options.ConfigurationExtensions.

Nota

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

Exemplo:

OptionsExample.cs:

public class OptionsExample
{
    public string? Option1 { get; set; }
    public string? Option2 { get; set; }
}

Em appsettings.json:

"OptionsExample": {
  "Option1": "Option1 Value",
  "Option2": "Option2 Value"
}

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

O componente Razor a seguir recupera as configurações com a diretiva @inject ou o atributo [Inject].

Options.razor:

@page "/options"
@using Microsoft.Extensions.Options
@inject IOptions<OptionsExample>? OptionsExample1

<h1>Options</h1>

<h2>
    &commat;inject approach
</h2>

<ul>
    <li>@OptionsExample1?.Value.Option1</li>
    <li>@OptionsExample1?.Value.Option2</li>
</ul>

<h2>
    [Inject] approach
</h2>

<ul>
    <li>@OptionsExample2?.Value.Option1</li>
    <li>@OptionsExample2?.Value.Option2</li>
</ul>

@code {
    [Inject]
    public IOptions<OptionsExample>? OptionsExample2 { get; set; }
}

Nem todos os recursos do ASP.NET Core Options são suportados nos componentes Razor. Por exemplo, as configurações de IOptionsSnapshot<TOptions> e IOptionsMonitor<TOptions> são suportadas, mas o recálculo dos valores de opção para essas interfaces não é suportado, exceto se recarregar a aplicação, seja solicitando-a numa nova aba do navegador ou selecionando o botão de recarregar do navegador. Simplesmente chamar StateHasChanged não atualiza as opções de instantâneo ou as opções monitorizadas quando a configuração subjacente é alterada.