środowiska ASP.NET Core Blazor

W tym artykule wyjaśniono, jak skonfigurować i odczytać środowisko w Blazor aplikacji.

W przypadku lokalnego uruchamiania aplikacji środowisko domyślnie ma wartość Development. Po opublikowaniu aplikacji środowisko domyślnie ma wartość Production.

Zalecamy następujące konwencje:

• Zawsze używaj nazwy środowiska "Development" na potrzeby programowania lokalnego. Dzieje się tak, ponieważ platforma ASP.NET Core oczekuje dokładnie tej nazwy podczas konfigurowania aplikacji i narzędzi dla lokalnych uruchomień programowania aplikacji.

• W przypadku środowisk testowych, przejściowych i produkcyjnych zawsze publikuj i wdrażaj aplikację. Można użyć dowolnego schematu nazewnictwa środowiska, który ma być przeznaczony dla opublikowanych aplikacji, ale zawsze używaj nazw plików ustawień aplikacji z wielkością liter segmentu środowiska, który dokładnie odpowiada nazwie środowiska. W przypadku przemieszczania użyj wartości "Staging" (capital "S") jako nazwy środowiska i nadaj plikowi ustawień aplikacji nazwę zgodną (appsettings.Staging.json). W przypadku środowiska produkcyjnego użyj ciągu "Production" (capital "P") jako nazwy środowiska i nadaj plikowi ustawień aplikacji nazwę zgodną (appsettings.Production.json).

Ustawianie środowiska

Środowisko jest ustawione przy użyciu dowolnego z następujących podejść:

• Blazor Web App: Użyj dowolnego podejścia opisanego w artykule Używanie wielu środowisk w ASP.NET Core dla ogólnych aplikacji ASP.NET Core.
• Blazor Web App lub autonomiczna Blazor WebAssembly: Blazor konfiguracja uruchamiania
• Blazor WebAssemblyAutonomiczny : blazor-environment nagłówek
• Blazor Web Applub autonomicznyBlazor WebAssembly: usługa aplikacja systemu Azure

Na kliencie programu Blazor Web Appśrodowisko jest określane z serwera za pośrednictwem oprogramowania pośredniczącego, które komunikuje środowisko do przeglądarki za pośrednictwem nagłówka o nazwie blazor-environment. Nagłówek ustawia środowisko podczas WebAssemblyHost tworzenia pliku po stronie Program klienta (WebAssemblyHostBuilder.CreateDefault).

W przypadku autonomicznej Blazor WebAssembly aplikacji działającej lokalnie serwer deweloperów dodaje blazor-environment nagłówek .

W przypadku aplikacji działających lokalnie w środowisku deweloperskich aplikacja jest domyślnie ustawiona na Development środowisko. Opublikowanie aplikacji domyślnie środowiska ma wartość Production.

Ustawianie środowiska po stronie klienta za pomocą Blazor konfiguracji uruchamiania

Poniższy przykład rozpoczyna się Blazor w środowisku, Staging jeśli nazwa hosta zawiera localhostwartość . W przeciwnym razie środowisko jest ustawione na wartość domyślną.

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      webAssembly: {
        environment: "Staging"
      }
    });
  } else {
    Blazor.start();
  }
</script>

W poprzednim przykładzie {BLAZOR SCRIPT} symbol zastępczy to ścieżka skryptu Blazor i nazwa pliku. Aby uzyskać informacje o lokalizacji skryptu, zobacz ASP.NET Core project structure (Struktura projektu ASP.NET CoreBlazor).

Uwaga

W przypadku Blazor Web Apptego ustawienia webAssemblyenvironment>właściwości w Blazor.start konfiguracji warto dopasować środowisko po stronie serwera do środowiska ustawionego na environment właściwości . W przeciwnym razie wstępne renderowanie na serwerze będzie działać w innym środowisku niż renderowanie na kliencie, co powoduje dowolne skutki. Aby uzyskać ogólne wskazówki dotyczące ustawiania środowiska dla elementu Blazor Web App, zobacz Używanie wielu środowisk w programie ASP.NET Core.

Autonomiczny zestaw Blazor WebAssembly:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      environment: "Staging"
    });
  } else {
    Blazor.start();
  }
</script>

W poprzednim przykładzie {BLAZOR SCRIPT} symbol zastępczy to ścieżka skryptu Blazor i nazwa pliku. Aby uzyskać informacje o lokalizacji skryptu, zobacz ASP.NET Core project structure (Struktura projektu ASP.NET CoreBlazor).

environment Za pomocą właściwości zastępuje środowisko ustawione przez blazor-environment nagłówek.

Powyższe podejście określa środowisko klienta bez zmieniania blazor-environment wartości nagłówka ani nie zmienia rejestrowania konsoli projektu serwera dla środowiska uruchamiania dla Blazor Web App elementu, który przyjął globalne renderowanie interakcyjne webAssembly.

Aby zarejestrować środowisko w konsoli programu w autonomicznym projekcie lub .Client projekcie Blazor Web Appprogramu , umieść następujący kod C# w Program pliku po utworzeniu WebAssemblyHostBuilder.CreateDefault WebAssemblyHost polecenia i przed wierszem, który kompiluje i uruchamia projekt (await builder.Build().RunAsync();):Blazor WebAssembly

Console.WriteLine(
    $"Client Hosting Environment: {builder.HostEnvironment.Environment}");

Aby uzyskać więcej informacji na temat uruchamiania platformy Blazor, zobacz Uruchamianie platformy ASP.NET Core Blazor.

Ustawianie środowiska po stronie klienta za pomocą nagłówka

Blazor WebAssembly aplikacje mogą ustawiać środowisko za pomocą nagłówka blazor-environment .

W poniższym przykładzie dla usług IIS nagłówek niestandardowy (blazor-environment) jest dodawany do opublikowanego web.config pliku. Plik web.config znajduje się w folderze bin/Release/{TARGET FRAMEWORK}/publish , w którym {TARGET FRAMEWORK} symbol zastępczy jest strukturą docelową:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>

    ...

    <httpProtocol>
      <customHeaders>
        <add name="blazor-environment" value="Staging" />
      </customHeaders>
    </httpProtocol>
  </system.webServer>
</configuration>

Uwaga

Aby użyć pliku niestandardowego web.config dla usług IIS, który nie jest zastępowany podczas publikowania aplikacji w publish folderze, zobacz Hostowanie i wdrażanie ASP.NET Core Blazor WebAssembly.

Mimo że struktura Blazor wystawia nazwę nagłówka we wszystkich małych literach (blazor-environment), możesz użyć dowolnej wielkości liter. Na przykład obsługiwana jest nazwa nagłówka, która wielkich liter każdego wyrazu (Blazor-Environment).

Ustawianie środowiska dla usługi aplikacja systemu Azure

W przypadku aplikacji autonomicznej Blazor WebAssembly można ręcznie ustawić środowisko za pomocą konfiguracji początkowej lub nagłówkablazor-environment.

W przypadku aplikacji po stronie serwera ustaw środowisko za pomocą ASPNETCORE_ENVIRONMENT ustawienia aplikacji na platformie Azure:

1. Upewnij się, że wielkość liter segmentów środowiska w nazwach plików ustawień aplikacji jest zgodna z wielkością liter nazwy środowiska. Na przykład zgodna nazwa pliku ustawień aplikacji dla Staging środowiska to appsettings.Staging.json. Jeśli nazwa pliku to appsettings.staging.json (małe literys" ), plik nie znajduje się, a ustawienia w pliku nie są używane w Staging środowisku.

2. W przypadku wdrożenia programu Visual Studio upewnij się, że aplikacja została wdrożona w odpowiednim miejscu wdrożenia. W przypadku aplikacji o nazwie BlazorAzureAppSampleaplikacja jest wdrażana w Staging miejscu wdrożenia.

3. W witrynie Azure Portal dla miejsca wdrożenia środowiska ustaw środowisko przy użyciu ASPNETCORE_ENVIRONMENT ustawienia aplikacji. W przypadku aplikacji o nazwie BlazorAzureAppSample, przejściowe miejsce usługi App Service nosi nazwę BlazorAzureAppSample/Staging. Staging W przypadku konfiguracji miejsca utwórz ustawienie aplikacji dla ASPNETCORE_ENVIRONMENT elementu z wartością Staging. Ustawienie Miejsca wdrożenia jest włączone dla tego ustawienia.

Po zażądaniu w przeglądarce BlazorAzureAppSample/Staging aplikacja ładuje się w Staging środowisku pod adresem https://blazorazureappsample-staging.azurewebsites.net.

Po załadowaniu aplikacji w przeglądarce kolekcja nagłówków odpowiedzi wskazuje blazor.boot.json , że wartość nagłówka blazor-environment to Staging.

Ustawienia aplikacji z appsettings.{ENVIRONMENT}.json pliku są ładowane przez aplikację, gdzie {ENVIRONMENT} symbol zastępczy jest środowiskiem aplikacji. W poprzednim przykładzie są ładowane ustawienia z appsettings.Staging.json pliku.

Odczytywanie środowiska w Blazor WebAssembly aplikacji

Uzyskaj środowisko aplikacji w składniku, wstrzykiwając i odczytując IWebAssemblyHostEnvironment Environment właściwość.

ReadEnvironment.razor:

@page "/read-environment"
@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IWebAssemblyHostEnvironment Env

<h1>Environment example</h1>

<p>Environment: @Env.Environment</p>

Odczytywanie po stronie klienta środowiska w obiekcie Blazor Web App

Zakładając, że prerendering nie jest wyłączony dla składnika lub aplikacji, składnik w .Client projekcie jest wstępnie zainstalowany na serwerze. Ponieważ serwer nie ma zarejestrowanej IWebAssemblyHostEnvironment usługi, nie można wstrzyknąć usługi i użyć metod rozszerzeń i właściwości środowiska hosta implementacji usługi podczas prerenderingu serwera. Wstrzykiwanie usługi do interakcyjnego składnika WebAssembly lub Interactive Auto powoduje następujący błąd środowiska uruchomieniowego:

There is no registered service of type 'Microsoft.AspNetCore.Components.WebAssembly.Hosting.IWebAssemblyHostEnvironment'.

Aby rozwiązać ten problem, utwórz niestandardową implementację usługi dla IWebAssemblyHostEnvironment programu na serwerze. Dodaj następującą klasę do projektu serwera.

ServerHostEnvironment.cs:

using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using Microsoft.AspNetCore.Components;

public class ServerHostEnvironment(IWebHostEnvironment env, NavigationManager nav) : 
    IWebAssemblyHostEnvironment
{
    public string Environment => env.EnvironmentName;
    public string BaseAddress => nav.BaseUri;
}

W pliku projektu Program serwera zarejestruj usługę:

builder.Services.TryAddScoped<IWebAssemblyHostEnvironment, ServerHostEnvironment>();

W tym momencie usługę IWebAssemblyHostEnvironment można wstrzyknąć do interaktywnego składnika WebAssembly lub interactive Auto i używać go, jak pokazano w sekcji Odczyt środowiska w Blazor WebAssembly aplikacji .

Powyższy przykład może wykazać, że istnieje inne środowisko serwera niż środowisko klienta, które nie jest zalecane i może prowadzić do dowolnych wyników. W przypadku ustawiania środowiska w programie Blazor Web Appnajlepiej dopasować środowisko serwera i .Client środowiska projektu. Rozważmy następujący scenariusz w aplikacji testowej:

• Zaimplementuj właściwość środowiska po stronie klienta (webassembly) przy Staging użyciu środowiska za pomocą polecenia Blazor.start. Zobacz sekcję Ustawianie środowiska po stronie klienta za pomocą konfiguracji uruchamiania, aby zapoznać się z przykładem.
• Nie zmieniaj pliku po stronie Properties/launchSettings.json serwera. Pozostaw sekcję environmentVariables ze zmienną środowiskową ustawioną ASPNETCORE_ENVIRONMENT na Development.

Wartość zmiany właściwości w interfejsie użytkownika jest widoczna IWebAssemblyHostEnvironment.Environment .

W przypadku wystąpienia prerenderingu na serwerze składnik jest renderowany w Development środowisku:

Environment: Development

Gdy składnik jest rerendered zaledwie sekundę lub dwa później, po Blazor pobraniu pakietu, a środowisko uruchomieniowe zestawu WebAssembly platformy .NET uaktywnia się, wartości zmieniają się, aby odzwierciedlić, że klient działa w Staging środowisku na kliencie:

Environment: Staging

W poprzednim przykładzie pokazano, dlaczego zalecamy ustawienie środowiska serwera w celu dopasowania środowiska klienta do wdrożeń programistycznych, testowych i produkcyjnych.

Aby uzyskać więcej informacji, zobacz sekcję Usługi po stronie klienta nie mogą zostać rozwiązane podczas prerenderingu artykułu Tryby renderowania, który pojawia się w Blazor dalszej części dokumentacji.

Odczytywanie środowiska po stronie klienta podczas uruchamiania

Podczas uruchamiania obiekt WebAssemblyHostBuilder uwidacznia IWebAssemblyHostEnvironment właściwość HostEnvironment , która umożliwia logikę specyficzną dla środowiska w kodzie konstruktora hosta.

W pliku Program:

if (builder.HostEnvironment.Environment == "Custom")
{
    ...
};

Następujące metody rozszerzenia wygody udostępniane za pośrednictwem WebAssemblyHostEnvironmentExtensions zezwolenia na sprawdzanie bieżącego środowiska dla Developmentnazw środowisk , , ProductionStagingi niestandardowych:

• IsDevelopment
• IsProduction
• IsStaging
• IsEnvironment

W pliku Program:

if (builder.HostEnvironment.IsStaging())
{
    ...
};

if (builder.HostEnvironment.IsEnvironment("Custom"))
{
    ...
};

Właściwość IWebAssemblyHostEnvironment.BaseAddress może być używana podczas uruchamiania NavigationManager , gdy usługa nie jest dostępna.

Dodatkowe zasoby

• uruchamianie ASP.NET Core Blazor
• Używanie wielu środowisk na platformie ASP.NET Core
• Blazorprzykładowe repozytorium GitHub () (dotnet/blazor-samplesjak pobrać)