ASP.NET Core prostředí Blazor

Tento článek vysvětluje, jak nakonfigurovat a přečíst prostředí v aplikaci Blazor.

Při místním spuštění aplikace se prostředí automaticky nastaví na Development. Po publikování aplikace se prostředí ve výchozím nastavení nastaví na Production.

Doporučujeme následující konvence:

• Pro místní vývoj vždy používejte název prostředíDevelopment. Důvodem je to, že architektura ASP.NET Core očekává přesně tento název při konfiguraci aplikace a nástrojů pro místní vývoj aplikací.

• Pro testování, přípravu a produkční prostředí vždy publikujte a nasaďte aplikaci. Můžete použít jakékoli schéma pojmenování prostředí pro publikované aplikace, ale vždy použijte názvy souborů nastavení aplikace s velkými a malými písmeny segmentu prostředí, které přesně odpovídají názvu prostředí. Pro přípravu použijte jako název prostředí "Staging" (velké písmeno "S") a pojmenujte soubor s nastavením aplikace tak, aby odpovídal (appsettings.Staging.json). Pro produkci použijte jako název prostředí "Production" (velké písmeno "P") a soubor s nastavením aplikace pojmenujte tak, aby odpovídal (appsettings.Production.json).

Nastavení prostředí

Prostředí se nastavuje pomocí některého z následujících přístupů:

• Blazor Web App: Pro obecné aplikace ASP.NET Core použijte některý z přístupů popsaných v Použití více prostředí v ASP.NET Core.
• Blazor Web App nebo samostatné Blazor WebAssembly: konfigurace spuštěníBlazor
• Samostatný Blazor WebAssembly: Blazor-Environment záhlaví
• Blazor Web App nebo samostatné Blazor WebAssembly: Azure App Service

Na klientovi pro Blazor Web Appje prostředí určeno ze serveru prostřednictvím middlewaru, který toto prostředí komunikuje s prohlížečem prostřednictvím hlavičky pojmenované Blazor-Environment. Hlavička nastaví prostředí při vytvoření WebAssemblyHost v souboru Program na klientské straně (WebAssemblyHostBuilder.CreateDefault).

Pro samostatnou Blazor WebAssembly aplikaci spuštěnou místně přidá vývojový server hlavičku Blazor-Environment s názvem prostředí získaným z hostitelského prostředí. Hostitelské prostředí nastaví prostředí z proměnné prostředí ASPNETCORE_ENVIRONMENT vytvořené souborem Properties/launchSettings.json projektu. Výchozí hodnota proměnné prostředí v projektu vytvořeném ze šablony projektu Blazor WebAssembly je Development. Další informace najdete v sekci Nastavení prostředí na straně klienta prostřednictvím hlavičky.

Pro aplikaci běžící místně ve vývojovém prostředí se ve výchozím nastavení použije prostředí Development. Při publikování aplikace se prostředí automaticky nastaví na Production.

Nastavení prostředí na straně klienta pomocí spouštěcí konfigurace Blazor

Následující příklad spustí Blazor v Staging prostředí, pokud název hostitele obsahuje localhost. V opačném případě je prostředí nastaveno na výchozí hodnotu.

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>

V předchozím příkladu symbol {BLAZOR SCRIPT} představuje cestu ke skriptu a název souboru označený zástupcem Blazor. Viz umístění skriptu v ASP.NET Core Blazor struktuře projektu.

Poznámka

U Blazor Web App, které nastavily vlastnost webAssembly>environment v konfiguraci Blazor.start, je vhodné přizpůsobit prostředí na straně serveru prostředí nastavenému na vlastnosti environment. Jinak bude předběžné vykreslování na serveru fungovat v jiném prostředí než vykreslování na klientovi, což vede k libovolným efektům. Obecné pokyny k nastavení prostředí pro Blazor Web Appnajdete v tématu Použití více prostředí v ASP.NET Core.

Samostatný Blazor WebAssembly:

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

V předchozím příkladu představuje zástupný symbol {BLAZOR SCRIPT} cestu ke skriptu a zástupný symbol Blazor název souboru. Umístění skriptu naleznete v tématu ASP.NET Core Blazor struktury projektu.

Použití vlastnosti environment přepíše prostředí nastavené hlavičkou Blazor-Environment.

Předchozí přístup nastaví prostředí klienta beze změny hodnoty hlavičky Blazor-Environment ani nezmění protokolování konzoly projektu serveru pro spouštěcí prostředí pro Blazor Web App, která přijala globální vykreslování Interactive WebAssembly.

Pokud chcete zaznamenat prostředí do konzole v rámci samostatného projektu Blazor WebAssembly nebo v projektu .Client v rámci Blazor Web App, umístěte následující kód v jazyce C# do souboru Program po vytvoření WebAssemblyHost s pomocí WebAssemblyHostBuilder.CreateDefault a před řádek, který projekt sestaví a spustí (await builder.Build().RunAsync();).

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

Další informace o spuštění Blazor naleznete v tématu ASP.NET Core Blazor startup.

Nastavení prostředí na straně klienta prostřednictvím hlavičky

Blazor WebAssembly aplikace můžou prostředí nastavit pomocí hlavičky Blazor-Environment. Konkrétně musí být hlavička odpovědi nastavena na souboru _framework/blazor.boot.json, ale nijak neuškodí nastavit hlavičku na odpovědi od souborového serveru i pro jiné požadavky na soubory Blazor nebo pro celé nasazení Blazor.

I když rámec Blazor vydává název hlavičky v kebab case se smíšenou velikostí písmen (Blazor-Environment), můžete použít kebab case se všemi malými nebo všemi velkými písmeny (blazor-environment, BLAZOR-ENVIRONMENT).

U místních vývojových běhů s integrovaným vývojovým serverem Blazormůžete řídit hodnotu hlavičky Blazor-Environment nastavením hodnoty proměnné prostředí ASPNETCORE_ENVIRONMENT v souboru Properties/launchSettings.json projektu. Při místním spuštění s vývojovým serverem je pořadí priorit pro určení prostředí aplikace následující: Blazor.start konfigurace (environment klíč),>Blazor-Environment hlavička odpovědi (blazor.boot.json soubor), >ASPNETCORE_ENVIRONMENT proměnná prostředí (launchSettings.json). Nemůžete použít přístup proměnné prostředí ASPNETCORE_ENVIRONMENT (launchSettings.json) pro nasazenou Blazor WebAssembly aplikaci. Technika funguje jenom s vývojovým serverem na místních spuštěních aplikace.

IIS

V následujícím příkladu služby IIS se vlastní hlavička (Blazor-Environment) přidá do publikovaného souboru web.config. Soubor web.config se nachází ve složce bin/Release/{TARGET FRAMEWORK}/publish, kde zástupný symbol {TARGET FRAMEWORK} je cílová architektura:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    ...
    <httpProtocol>
      <customHeaders>
        <add name="Blazor-Environment" value="Staging" />
      </customHeaders>
    </httpProtocol>
  </system.webServer>
</configuration>

Poznámka

Pokud chcete použít vlastní soubor web.config pro službu IIS, který se při publikování aplikace do složky publish nepřepíše, viz kapitola Hostování a nasazení ASP.NET Core Blazor WebAssembly.

Nginx

Pro servery Nginx použijte direktivu add_header z ngx_http_headers_module:

http {
    server {
        ...
        location / {
            ...
            add_header Blazor-Environment "Staging";
        }
    }
}

Další informace najdete v následujících zdrojích informací:

• dokumentace k Nginx
• Blazor WebAssembly pokyny pro hostování Nginx

Apač

Pro servery Apache použijte direktivu Header z modulu mod_headers:

<VirtualHost *:80>
    ...
    Header set Blazor-Environment "Staging"
    ...
</VirtualHost>

Další informace:

• dokumentaci k Apache (vyhledejte nejnovější verzimod_headers")
• Blazor WebAssembly pokyny k hostování Apache

Nastavení prostředí pro Azure App Service

Pro samostatnou aplikaci Blazor WebAssembly můžete prostředí nastavit ručně zavedením konfigurace nebo Blazor-Environment hlavičky.

Pro aplikaci na straně serveru nastavte prostředí prostřednictvím nastavení aplikace ASPNETCORE_ENVIRONMENT v Azure:

1. Potvrďte, že velikost písmen segmentů prostředí v názvech souborů nastavení aplikace přesně odpovídá velikosti písmen jejich názvů prostředí. Například odpovídající název souboru nastavení aplikace pro Staging prostředí je appsettings.Staging.json. Pokud je název souboru appsettings.staging.json (malá písmenas), soubor se nenachází a nastavení v souboru se v prostředí Staging nepoužívá.

2. V případě nasazení sady Visual Studio ověřte, že je aplikace nasazená do správného slotu nasazení. Pro aplikaci s názvem BlazorAzureAppSamplese aplikace nasadí do slotu nasazení Staging.

3. V portálu Azure nastavte slot nasazení prostředí s nastavením aplikace ASPNETCORE_ENVIRONMENT. Pro aplikaci s názvem BlazorAzureAppSamplese přípravný slot služby App Service jmenuje BlazorAzureAppSample/Staging. Pro konfiguraci slotu Staging vytvořte nastavení aplikace pro ASPNETCORE_ENVIRONMENT s hodnotou Staging. Nastavení slotu nasazení je pro tuto funkci povoleno.

Když je požadována v prohlížeči, aplikace BlazorAzureAppSample/Staging se načte v prostředí Staging v https://blazorazureappsample-staging.azurewebsites.net.

Když se aplikace načte v prohlížeči, kolekce hlaviček odpovědí pro blazor.boot.json indikuje, že hodnota hlavičky Blazor-Environment je Staging.

Nastavení aplikace ze souboru appsettings.{ENVIRONMENT}.json se načte aplikací, kde zástupný symbol {ENVIRONMENT} je prostředí aplikace. V předchozím příkladu se načtou nastavení ze souboru appsettings.Staging.json.

Čtěte prostředí v aplikaci Blazor WebAssembly

Získejte prostředí aplikace v komponentě vložením IWebAssemblyHostEnvironment a přečtením vlastnosti Environment.

ReadEnvironment.razor:

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

<h1>Environment example</h1>

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

Číst prostředí na straně klienta v Blazor Web App

Za předpokladu, že pro komponentu nebo aplikaci není zakázáno předvykreslení, je komponenta v projektu .Client předvykreslena na serveru. Vzhledem k tomu, že server nemá zaregistrovanou službu IWebAssemblyHostEnvironment, není možné službu vkládat a používat metody a vlastnosti rozšíření hostitelského prostředí implementace služby během předrenderingu serveru. Vložením služby do interaktivní WebAssembly nebo interaktivní automatizační komponenty dojde k následující běhové chybě:

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

Pokud to chcete vyřešit, vytvořte vlastní implementaci služby pro IWebAssemblyHostEnvironment na serveru. Do projektu serveru přidejte následující třídu.

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

V souboru Program projektu serveru zaregistrujte službu:

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

V tuto chvíli je možné službu IWebAssemblyHostEnvironment vložit do interaktivní nebo interaktivní automatické komponenty WebAssembly a použít ji, jak je znázorněno v části Čtení prostředí v aplikaci Blazor WebAssembly.

Předchozí příklad může ukázat, že je možné mít jiné serverové prostředí než klientské prostředí, které se nedoporučuje a může vést k libovolným výsledkům. Při nastavování prostředí v Blazor Web Appje nejlepší sladit serverové prostředí a projektové prostředí .Client. V testovací aplikaci zvažte následující scénář:

• Implementujte vlastnost prostředí na straně klienta (webassembly) s prostředím Staging prostřednictvím Blazor.start. Příklad najdete v části Nastavení klientského prostředí prostřednictvím konfiguračního souboru při spuštění.
• Neměňte soubor Properties/launchSettings.json na straně serveru. V části environmentVariables ponechte proměnnou prostředí ASPNETCORE_ENVIRONMENT nastavenou na Development.

Hodnotu vlastnosti IWebAssemblyHostEnvironment.Environment lze vidět v uživatelském rozhraní.

Při předběžném vykreslování na serveru se komponenta vykreslí v prostředí Development.

Environment: Development

Pokud je komponenta znovu vykreslena jen o sekundu či dvě později, po stažení balíčku Blazor a aktivaci modulu runtime .NET WebAssembly, hodnoty se změní, aby odrážely, že klient operuje v prostředí Staging na klientovi.

Environment: Staging

Předchozí příklad ukazuje, proč doporučujeme nastavit serverové prostředí tak, aby odpovídalo klientskému prostředí pro vývoj, testování a produkční nasazení.

Další informace najdete v části Služby na straně klienta, které se nepodaří vyřešit během předdefinování části režimů vykreslování článku, který se zobrazí dále v dokumentaci k Blazor.

Načítání klientského prostředí při spuštění

Během spuštění WebAssemblyHostBuilder zpřístupňuje IWebAssemblyHostEnvironment prostřednictvím vlastnosti HostEnvironment, která umožňuje logiku specifickou pro prostředí v kódu tvůrce hostitelů.

V souboru Program:

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

Následující pomocné metody rozšíření poskytované prostřednictvím WebAssemblyHostEnvironmentExtensions umožňují kontrolovat aktuální prostředí na Development, Production, Staginga vlastní názvy prostředí:

• IsDevelopment
• IsProduction
• IsStaging
• IsEnvironment

V souboru Program:

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

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

Vlastnost IWebAssemblyHostEnvironment.BaseAddress lze použít při spuštění, pokud není služba NavigationManager k dispozici.

Další zdroje informací

• ASP.NET Core Blazor spouštěcí
• Použití více prostředí v ASP.NET Core
• Blazor ukázky úložiště GitHub (dotnet/blazor-samples) (jak stáhnout)