Konfiguracja ASP.NET Core Blazor

W tym artykule wyjaśniono, jak skonfigurować Blazor aplikacje, w tym ustawienia aplikacji, uwierzytelnianie i konfigurację rejestrowania.

Te wskazówki dotyczą konfiguracji projektu po stronie klienta w Blazor aplikacji internetowej lub aplikacji autonomicznej Blazor WebAssembly .

W usłudze Blazor Web Apps:

• W przypadku konfiguracji po stronie serwera:
  • Aby uzyskać wskazówki, zobacz Artykuł Configuration in ASP.NET Core (Konfiguracja w programie ASP.NET Core ).
  • Domyślnie są ładowane tylko konfiguracje w plikach ustawień aplikacji głównej projektu.
  • Pozostała część tego artykułu dotyczy tylko konfiguracji po stronie klienta w projekcie .Client .
• W przypadku konfiguracji po stronie klienta (.Client projekt) konfiguracja jest domyślnie ładowana z następujących plików ustawień aplikacji:
  • wwwroot/appsettings.json.
  • wwwroot/appsettings.{ENVIRONMENT}.json, gdzie {ENVIRONMENT} symbol zastępczy jest środowiskiem uruchomieniowym aplikacji.

W aplikacjach autonomicznych Blazor WebAssembly konfiguracja jest domyślnie ładowana z następujących plików ustawień aplikacji:

• wwwroot/appsettings.json.
• wwwroot/appsettings.{ENVIRONMENT}.json, gdzie {ENVIRONMENT} symbol zastępczy jest środowiskiem uruchomieniowym aplikacji.

Uwaga

Konfiguracja rejestrowania umieszczona w pliku wwwroot ustawień aplikacji nie jest domyślnie ładowana. Aby uzyskać więcej informacji, zobacz sekcję Konfiguracja rejestrowania w dalszej części tego artykułu.

W niektórych scenariuszach, takich jak w przypadku usług platformy Azure, ważne jest użycie segmentu nazwy pliku środowiska, który dokładnie odpowiada nazwie środowiska. Na przykład użyj nazwy appsettings.Staging.json pliku ze znakiem "S" dla Staging środowiska. Aby zapoznać się z zalecanymi konwencjami, zobacz uwagi otwierające środowiska ASP.NET CoreBlazor.

Inni dostawcy konfiguracji zarejestrowani przez aplikację mogą również zapewnić konfigurację, ale nie wszyscy dostawcy lub funkcje dostawcy są odpowiednie:

• Dostawca konfiguracji usługi Azure Key Vault: dostawca nie jest obsługiwany dla tożsamości zarządzanej i identyfikatora aplikacji (identyfikatora klienta) ze scenariuszami wpisów tajnych klienta. Identyfikator aplikacji z wpisem tajnym klienta nie jest zalecany w przypadku żadnej aplikacji ASP.NET Core, zwłaszcza aplikacji po stronie klienta, ponieważ nie można zabezpieczyć wpisu tajnego klienta w celu uzyskania dostępu do usługi Azure Key Vault.
• aplikacja systemu Azure dostawcy konfiguracji: dostawca nie jest odpowiedni dla aplikacji po stronie klienta, ponieważ nie są one uruchamiane na serwerze na platformie Azure.

Aby uzyskać więcej informacji na temat dostawców konfiguracji, zobacz Configuration in ASP.NET Core (Konfiguracja w programie ASP.NET Core).

Ostrzeżenie

Pliki konfiguracji i ustawień w folderze głównym sieci Web (wwwroot folder) są widoczne dla użytkowników na kliencie, a użytkownicy mogą manipulować danymi. Nie przechowuj wpisów tajnych aplikacji, poświadczeń ani żadnych innych poufnych danych w żadnym pliku głównym sieci Web.

Konfiguracja ustawień aplikacji

Konfiguracja w plikach ustawień aplikacji jest domyślnie ładowana. W poniższym przykładzie wartość konfiguracji interfejsu użytkownika jest przechowywana w pliku ustawień aplikacji i ładowana automatycznie przez platformę Blazor . Wartość jest odczytywana przez składnik.

wwwroot/appsettings.json:

{
    "h1FontSize": "50px"
}

IConfiguration Wstrzykiwanie wystąpienia do składnika w celu uzyskania dostępu do danych konfiguracji.

ConfigExample.razor:

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

<PageTitle>Configuration</PageTitle>

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

Ograniczenia zabezpieczeń klienta uniemożliwiają bezpośredni dostęp do plików za pośrednictwem kodu użytkownika, w tym pliki ustawień konfiguracji aplikacji. Aby odczytywać pliki konfiguracji oprócz z folderu do appsettings.json/appsettings.{ENVIRONMENT}.json konfiguracji, użyj elementu HttpClient.wwwroot

Ostrzeżenie

Pliki konfiguracji i ustawień w folderze głównym sieci Web (wwwroot folder) są widoczne dla użytkowników na kliencie, a użytkownicy mogą manipulować danymi. Nie przechowuj wpisów tajnych aplikacji, poświadczeń ani żadnych innych poufnych danych w żadnym pliku głównym sieci Web.

Poniższy przykład odczytuje plik konfiguracji (cars.json) do konfiguracji aplikacji.

wwwroot/cars.json:

{
    "size": "tiny"
}

Dodaj przestrzeń nazw do Microsoft.Extensions.ConfigurationProgram pliku:

using Microsoft.Extensions.Configuration;

Zmodyfikuj istniejącą HttpClient rejestrację usługi, aby użyć klienta do odczytania pliku:

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

W poprzednim przykładzie ustawiono adres podstawowy (IWebAssemblyHostEnvironment.BaseAddress), który pobiera adres builder.HostEnvironment.BaseAddress podstawowy dla aplikacji i jest zwykle pobierany z <base> wartości tagu href na stronie hosta.

Źródło konfiguracji pamięci

W poniższym przykładzie Program użyto MemoryConfigurationSource elementu w pliku , aby podać dodatkową konfigurację.

Dodaj przestrzeń nazw do Microsoft.Extensions.Configuration.MemoryProgram pliku:

using Microsoft.Extensions.Configuration.Memory;

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

IConfiguration Wstrzykiwanie wystąpienia do składnika w celu uzyskania dostępu do danych konfiguracji.

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>

Uzyskaj sekcję konfiguracji w kodzie języka C# za pomocą polecenia IConfiguration.GetSection. Poniższy przykład uzyskuje sekcję wheels konfiguracji w poprzednim przykładzie:

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

        ...
    }
}

Konfiguracja uwierzytelniania

Podaj konfigurację uwierzytelniania publicznego w pliku ustawień aplikacji.

wwwroot/appsettings.json:

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

Załaduj konfigurację Identity dostawcy za pomocą ConfigurationBinder.Bind polecenia Program w pliku . W poniższym przykładzie ładuje konfigurację dostawcy OIDC:

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

Ostrzeżenie

Pliki konfiguracji i ustawień w folderze głównym sieci Web (wwwroot folder) są widoczne dla użytkowników na kliencie, a użytkownicy mogą manipulować danymi. Nie przechowuj wpisów tajnych aplikacji, poświadczeń ani żadnych innych poufnych danych w żadnym pliku głównym sieci Web.

Konfiguracja rejestrowania

Ta sekcja dotyczy aplikacji, które konfigurują rejestrowanie za pośrednictwem pliku ustawień aplikacji w folderze wwwroot .

Microsoft.Extensions.Logging.Configuration Dodaj pakiet do aplikacji.

Uwaga

Aby uzyskać instrukcje dodawania pakietów do aplikacji .NET, zobacz artykuły w sekcji Instalowanie pakietów i zarządzanie nimi w temacie Przepływ pracy użycia pakietów (dokumentacja programu NuGet). Sprawdź prawidłowe wersje pakietów pod adresem NuGet.org.

W pliku ustawień aplikacji podaj konfigurację rejestrowania. Konfiguracja rejestrowania jest ładowana do Program pliku.

wwwroot/appsettings.json:

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

W pliku Program:

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

Konfiguracja konstruktora hostów

Odczyt konfiguracji konstruktora hostów Program z WebAssemblyHostBuilder.Configuration pliku:

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

Konfiguracja buforowana

Pliki konfiguracji są buforowane do użytku w trybie offline. Dzięki progresywnym aplikacjom internetowym (PWA) można aktualizować pliki konfiguracji tylko podczas tworzenia nowego wdrożenia. Edytowanie plików konfiguracji między wdrożeniami nie ma wpływu, ponieważ:

• Użytkownicy buforowali wersje plików, z których nadal korzystają.
• Pliki i service-worker-assets.js pliki programu PWA service-worker.js muszą zostać ponownie skompilowane na kompilacji, co sygnalizuje aplikację podczas następnej wizyty w trybie online użytkownika, że aplikacja została ponownie wdrożona.

Aby uzyskać więcej informacji na temat sposobu obsługi aktualizacji w tle przez aplikacje PWA, zobacz ASP.NET Core Blazor Progressive Web Application (PWA).

Konfiguracja opcji

Konfiguracja opcji wymaga dodania odwołania Microsoft.Extensions.Options.ConfigurationExtensions do pakietu NuGet.

Uwaga

Aby uzyskać instrukcje dodawania pakietów do aplikacji .NET, zobacz artykuły w sekcji Instalowanie pakietów i zarządzanie nimi w temacie Przepływ pracy użycia pakietów (dokumentacja programu NuGet). Sprawdź prawidłowe wersje pakietów pod adresem NuGet.org.

Przykład:

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

Nie wszystkie funkcje ASP.NET Core Options są obsługiwane w Razor składnikach. Na przykład IOptionsSnapshot<TOptions> i IOptionsMonitor<TOptions> konfiguracja jest obsługiwana, ale ponowne obliczanie wartości opcji dla tych interfejsów nie jest obsługiwane poza ponownym ładowaniem aplikacji przez żądanie aplikacji na nowej karcie przeglądarki lub wybranie przycisku ponownego ładowania przeglądarki. Tylko wywołanie StateHasChanged nie aktualizuje migawek ani monitorowanych wartości opcji, gdy podstawowa konfiguracja ulegnie zmianie.