ś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 dla opublikowanych aplikacji, ale zawsze używaj nazw plików ustawień aplikacji z segmentem środowiska, którego wielkość liter dokładnie odpowiada nazwie środowiska. W przypadku środowiska testowego użyj wartości "Staging" (capital "S") jako nazwy środowiska i nazwij plik ustawień aplikacji zgodnie (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 lub Blazor Server: Użyj dowolnej z metod opisanych w środowiskach uruchomieniowych ASP.NET Core dla ogólnych aplikacji ASP.NET Core.
• Dowolna Blazor aplikacja: Blazor uruchamianie konfiguracji
• Blazor WebAssembly: Autonomiczna <WasmApplicationEnvironmentName> cecha

Na kliencie programu Blazor Web Appśrodowisko jest określane z serwera za pośrednictwem komentarza HTML, z którego deweloperzy nie korzystają:

<!--Blazor-WebAssembly:{"environmentName":"Development", ...}-->

W przypadku aplikacji autonomicznej Blazor WebAssembly ustaw środowisko za pomocą <WasmApplicationEnvironmentName> właściwości MSBuild w pliku projektu aplikacji (.csproj). Poniższy przykład ustawia Staging środowisko:

<WasmApplicationEnvironmentName>Staging</WasmApplicationEnvironmentName>

Domyślne środowiska są Development przeznaczone do kompilacji i Production publikowania.

Istnieje kilka metod ustawiania środowiska w aplikacji autonomicznej Blazor WebAssembly podczas operacji kompilacji/publikowania oraz jedno podejście do uruchamiania lub uruchamiania aplikacji na kliencie:

• Ustaw wartość właściwości, gdy dotnet build lub dotnet publish jest wykonywane. Poniższy przykład ustawia środowisko na Staging, gdy aplikacja jest publikowana.

  dotnet publish -p:WasmApplicationEnvironmentName=Staging
  

• Ustaw właściwość podczas kompilacji lub publikowania na podstawie konfiguracji aplikacji w programie Visual Studio. Następujące grupy właściwości mogą być używane w pliku projektu aplikacji lub w dowolnym pliku konfiguracji publikowania (.pubxml). Dodaj dodatkowe grupy właściwości dla innych używanych konfiguracji kompilacji.

  <PropertyGroup Condition="'$(Configuration)' == 'Debug'">
    <WasmApplicationEnvironmentName>Development</WasmApplicationEnvironmentName>
  </PropertyGroup>
  
  <PropertyGroup Condition="'$(Configuration)' == 'Release'">
    <WasmApplicationEnvironmentName>Production</WasmApplicationEnvironmentName>
  </PropertyGroup>
  

• Konfiguracja środowiska może być ustawiona na podstawie użycia profilu publikowania. W poniższym przykładzie pierwszy warunek ustawia środowisko na Development, gdy nie jest używany profil publikowania (dotyczy to zarówno operacji kompilacji, jak i publikowania bez profilu), natomiast drugi warunek ustawia środowisko na Production, gdy używany jest jakikolwiek profil publikowania.

  <PropertyGroup Condition="'$(PublishProfile)' == ''">
    <WasmApplicationEnvironmentName>Development</WasmApplicationEnvironmentName>
  </PropertyGroup>
  
  <PropertyGroup Condition="'$(PublishProfile)' != ''">
    <WasmApplicationEnvironmentName>Production</WasmApplicationEnvironmentName>
  </PropertyGroup>
  

• Utwórz niestandardowy webowy punkt końcowy interfejsu API po stronie serwera. Aplikacja autonomiczna Blazor WebAssembly żąda swojego środowiska z internetowego interfejsu API podczas uruchamiania aplikacji lub na żądanie podczas jej działania. Wartość powinna zostać przekazana do WebAssemblyStartOptions lub withApplicationEnvironment.

  Uwaga

  Linki dokumentacyjne do źródła referencyjnego .NET zwykle ładują domyślną gałąź repozytorium, która odzwierciedla obecne prace rozwojowe nad nadchodzącą wersją .NET. Aby wybrać tag dla określonej wersji, użyj listy rozwijanej Przełącz gałęzie lub tagi. Aby uzyskać więcej informacji, zobacz Jak wybrać tag wersji kodu źródłowego ASP.NET Core (dotnet/AspNetCore.Docs #26205).

W przypadku aplikacji działających lokalnie w środowisku deweloperskim, aplikacja domyślnie korzysta ze środowiska Development. Opublikowanie aplikacji ustawia środowisko domyślnie na Production.

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

Poniższy przykład rozpoczyna Blazor w środowisku Staging, jeśli nazwa hosta zawiera localhost. 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 symbol zastępczy {BLAZOR SCRIPT} to ścieżka i nazwa pliku skryptu Blazor. Aby uzyskać informacje o lokalizacji skryptu, zobacz Blazor.

Uwaga

W przypadku Blazor Web Apps, które ustawiają właściwość webAssembly>environment w konfiguracji Blazor.start, warto dopasować środowisko po stronie serwera do środowiska ustawionego na właściwości environment. W przeciwnym razie wstępne renderowanie na serwerze działa w innym środowisku niż renderowanie na kliencie, co powoduje dowolne skutki. Ogólne wskazówki dotyczące ustawiania środowiska dla programu Blazor Web Appmożna znaleźć w temacie ASP.NET Core runtime environments (Środowiska uruchomieniowe ASP.NET Core).

Samodzielny 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 symbol zastępczy {BLAZOR SCRIPT} to ścieżka i nazwa pliku skryptu Blazor. Aby uzyskać informacje o lokalizacji skryptu, zobacz Blazor.

Aby zarejestrować środowisko w konsoli w aplikacji autonomicznej Blazor WebAssembly lub w projekcie .Client związanym z Blazor Web App, umieść następujący kod języka C# w pliku Program po utworzeniu WebAssemblyHost przez WebAssemblyHostBuilder.CreateDefault i przed wierszem, który kompiluje i uruchamia projekt (await builder.Build().RunAsync();):

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.

Odczytywanie otoczenia w aplikacji Blazor WebAssembly

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

ReadEnvironment.razor:

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

<h1>Environment example</h1>

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

Odczytywanie środowiska po stronie klienta w Blazor Web App

Zakładając, że prerenderowanie nie jest wyłączone dla składnika lub aplikacji, składnik w projekcie .Client jest prerenderowany na serwerze. Ponieważ serwer nie ma w swoim rejestrze zarejestrowanej usługi IWebAssemblyHostEnvironment, nie można wstrzyknąć tej usługi ani skorzystać z metod rozszerzeń i właściwości środowiska hosta związanych z implementacją tej 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 na serwerze. Aby uzyskać więcej informacji i przykładową implementację, zobacz sekcję Implementacja usługi niestandardowej na serwerze artykułu Prerendering , który pojawia się w Blazor dalszej części dokumentacji.

Odczytywanie środowiska po stronie klienta podczas uruchamiania

Podczas uruchamiania, WebAssemblyHostBuilder udostępnia właściwość IWebAssemblyHostEnvironment, co umożliwia wykorzystanie logiki specyficznej dla środowiska w kodzie budowniczego hosta.

W pliku Program:

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

Następujące wygodne metody rozszerzenia udostępniane przez WebAssemblyHostEnvironmentExtensions umożliwiają sprawdzanie bieżącego środowiska dla Development, Production, Staging oraz niestandardowych nazw środowisk:

• 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, gdy usługa NavigationManager nie jest dostępna.

Dodatkowe zasoby

• uruchamianie ASP.NET Core Blazor
• środowiska uruchomieniowe ASP.NET Core
• Blazor przykłady repozytoriów GitHub (dotnet/blazor-samples) (jak pobrać)