Delen via

ASP.NET Core-omgevingen Blazor

Opmerking

Dit is niet de nieuwste versie van dit artikel. Zie de .NET 9-versie van dit artikelvoor de huidige release.

Waarschuwing

Deze versie van ASP.NET Core wordt niet meer ondersteund. Zie de .NET- en .NET Core-ondersteuningsbeleidvoor meer informatie. Zie de .NET 9-versie van dit artikelvoor de huidige release.

Belangrijk

Deze informatie heeft betrekking op een pre-releaseproduct dat aanzienlijk kan worden gewijzigd voordat het commercieel wordt uitgebracht. Microsoft geeft geen garanties, uitdrukkelijk of impliciet, met betrekking tot de informatie die hier wordt verstrekt.

Zie de .NET 9-versie van dit artikelvoor de huidige release.

In dit artikel wordt uitgelegd hoe u de omgeving in een Blazor app configureert en leest.

Wanneer u een app lokaal uitvoert, wordt de omgeving standaard ingesteld op Development. Wanneer de app wordt gepubliceerd, wordt de omgeving standaard ingesteld op Production.

We raden de volgende conventies aan:

  • Gebruik altijd deDevelopment ''-omgevingsnaam voor lokale ontwikkeling. Dit komt doordat het ASP.NET Core-framework precies die naam verwacht bij het configureren van de app en hulpprogramma's voor uitvoeringen van lokale ontwikkeling van een app.

  • Voor test-, faserings- en productieomgevingen publiceert en implementeert u de app altijd. U kunt elk naamgevingsschema voor de omgeving gebruiken dat u wilt gebruiken voor gepubliceerde apps, maar altijd bestandsnamen voor app-instellingen gebruiken met hoofdletters van het omgevingssegment die exact overeenkomen met de naam van de omgeving. Gebruik voor de testomgeving "Staging" (met hoofdletter "S") als de omgevingsnaam en zorg ervoor dat de naam van het app-instellingenbestand overeenkomt (appsettings.Staging.json). Voor productie gebruikt u 'Production' (hoofdletter 'P) als de omgevingsnaam en noemt u het bestand met app-instellingen dat overeenkomt met (appsettings.Production.json).

De omgeving instellen

De omgeving wordt ingesteld op een van de volgende manieren:

Voor een Blazor Web App op de client, wordt de omgeving door de server bepaald via een HTML-opmerking waarmee ontwikkelaars niet communiceren.

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

Voor een zelfstandige Blazor WebAssembly app stelt u de omgeving in met de <WasmApplicationEnvironmentName> eigenschap in het projectbestand van de app (.csproj). In het volgende voorbeeld wordt de Staging omgeving ingesteld:

<WasmApplicationEnvironmentName>Staging</WasmApplicationEnvironmentName>

De standaardomgevingen zijn Development voor het bouwen en Production publiceren.

Bij de client van een Blazor Web App, wordt de omgeving vanaf de server bepaald via een middleware die de omgeving naar de browser communiceert via een header met de naam Blazor-Environment. De header stelt de omgeving in wanneer de WebAssemblyHost wordt gemaakt in het clientzijdebestand Program (WebAssemblyHostBuilder.CreateDefault).

Voor een zelfstandige Blazor WebAssembly app die lokaal wordt uitgevoerd, voegt de ontwikkelserver de Blazor-Environment header toe met de omgevingsnaam die is verkregen uit de hostingomgeving. De hostingomgeving stelt de omgeving in op basis van de ASPNETCORE_ENVIRONMENT omgevingsvariabele die is ingesteld door het bestand van Properties/launchSettings.json het project. De standaardwaarde van de omgevingsvariabele in een project dat is gemaakt op basis van de Blazor WebAssembly projectsjabloon is Development. Zie de sectie De omgeving aan de clientzijde instellen via de koptekst voor meer informatie.

Op de client van een gehoste Blazor WebAssembly app wordt de omgeving van de server bepaald via een middleware die de omgeving via een header met de naam Blazor-Environmentcommuniceert naar de browser. De header stelt de omgeving in wanneer WebAssemblyHost wordt gecreëerd aan de clientzijde in het Program bestand (WebAssemblyHostBuilder.CreateDefault).

Voor een zelfstandige Blazor WebAssembly app die lokaal wordt uitgevoerd, voegt de ontwikkelserver de Blazor-Environment header toe met de omgevingsnaam die is verkregen uit de hostingomgeving. De hostingomgeving stelt de omgeving in op basis van de ASPNETCORE_ENVIRONMENT omgevingsvariabele die is ingesteld door het bestand van Properties/launchSettings.json het project. De standaardwaarde van de omgevingsvariabele in een project dat is gemaakt op basis van de Blazor WebAssembly projectsjabloon is Development. Zie de sectie De omgeving aan de clientzijde instellen via de koptekst voor meer informatie.

Voor apps die lokaal worden uitgevoerd in ontwikkeling, wordt de app standaard ingesteld op de Development omgeving. Als u de app publiceert, wordt de omgeving standaard ingesteld op Production.

Zie Meerdere omgevingen gebruiken in ASP.NET Core voor algemene richtlijnen voor het configureren van ASP.NET Core-apps. Zie voor serverside app-configuratie met statische bestanden in andere omgevingen dan de Development omgeving tijdens ontwikkeling en testen (bijvoorbeeld Staging), zie ASP.NET Core Blazor Statische bestanden.

De omgeving aan de clientzijde instellen via Blazor opstartconfiguratie

Het volgende voorbeeld start Blazor in de Staging omgeving als de hostnaam localhost bevat. Anders wordt de omgeving ingesteld op de standaardwaarde.

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>

In het voorgaande voorbeeld zijn de tijdelijke aanduidingen {BLAZOR SCRIPT} en Blazor respectievelijk het scriptpad en de bestandsnaam. Zie ASP.NET Core Blazor projectstructuurvoor de locatie van het script.

Opmerking

Als u de webAssembly>environment-eigenschap in Blazor.start configuratie instelt, is het verstandig om de serverside-omgeving af te stemmen op de omgeving die op de environment-eigenschap is ingesteld. Anders werkt prerendering op de server onder een andere omgeving dan rendering op de client, wat resulteert in willekeurige effecten. Zie Meerdere omgevingen gebruiken in ASP.NET Core voor algemene richtlijnen voor het instellen van de omgeving voor een Blazor Web Appomgeving.

Zelfstandige Blazor WebAssembly:

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

In het voorgaande voorbeeld zijn de tijdelijke aanduidingen {BLAZOR SCRIPT} en Blazor respectievelijk het scriptpad en de bestandsnaam. Zie ASP.NET Core Blazor projectstructuurvoor de locatie van het script.

Als u de environment eigenschap gebruikt, wordt de omgeving die door de Blazor-Environment header is ingesteld, overschreven.

Met de voorgaande benadering wordt de omgeving van de client ingesteld zonder de waarde van de Blazor-Environment header te wijzigen, noch wijzigt het de consolelogboekregistratie van de opstartomgeving van het serverproject voor een omgeving Blazor Web App die wereldwijde Interactive WebAssembly-rendering heeft aangenomen.

Als u de omgeving wilt registreren bij de console in een zelfstandige Blazor WebAssembly app of het .Client project van een Blazor Web App, plaatst u de volgende C#-code in het Program bestand nadat de WebAssemblyHost omgeving is gemaakt met WebAssemblyHostBuilder.CreateDefault en vóór de regel waarmee het project wordt gebouwd en uitgevoerd (await builder.Build().RunAsync();):

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

Voor meer informatie over Blazor startup, zie ASP.NET Core Blazor startup.

De omgeving aan de clientzijde instellen via header

Blazor WebAssembly apps kunnen de omgeving instellen met de Blazor-Environment header. De antwoordheader moet specifiek worden ingesteld op het _framework/blazor.boot.json bestand, maar er is geen kwaad om de header in te stellen op bestandsserverantwoorden voor andere Blazor bestandsaanvragen of de hele Blazor implementatie.

Hoewel het Blazor framework de headernaam in kebab case met gemengde hoofd- en kleine letters (Blazor-Environment) uitgeeft, kunt u gerust alleen kleine letters of alleen hoofdletters in kebab case (blazor-environment, BLAZOR-ENVIRONMENT) gebruiken.

Voor lokale ontwikkelingssessies met de ingebouwde ontwikkelserver van Blazor kunt u de waarde van de Blazor-Environment-header beheren door de waarde van de ASPNETCORE_ENVIRONMENT-omgevingsvariabele in te stellen in het Properties/launchSettings.json-bestand van het project. Wanneer de app lokaal wordt uitgevoerd met de ontwikkelserver, is Blazor.start de volgorde van prioriteit bij het bepalen van de app-omgeving configuratie (environment sleutel)>Blazor-Environment responseheader (blazor.boot.json bestand) >ASPNETCORE_ENVIRONMENT omgevingsvariabele (launchSettings.json). U kunt de ASPNETCORE_ENVIRONMENT omgevingsvariabele (launchSettings.json) niet gebruiken voor een geïmplementeerde Blazor WebAssembly app. De techniek werkt alleen met de ontwikkelserver op lokale uitvoeringen van de app.

IIS

In het volgende voorbeeld voor IIS wordt de aangepaste header (Blazor-Environment) toegevoegd aan het gepubliceerde web.config bestand. Het web.config bestand bevindt zich in de bin/Release/{TARGET FRAMEWORK}/publish map, waar de {TARGET FRAMEWORK} placeholder het doelframework is.

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

Opmerking

Als u een aangepast web.config bestand wilt gebruiken voor IIS dat niet wordt overschreven wanneer de app naar de publish map wordt gepubliceerd, raadpleegt u Host en implementeert u ASP.NET Core Blazor WebAssembly met IIS.

Nginx

Gebruik voor Nginx-servers de add_header instructie van ngx_http_headers_module.

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

Zie de volgende bronnen voor meer informatie:

Apache

Gebruik voor Apache-servers de Header instructie uit de mod_headers module:

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

Zie de volgende bronnen voor meer informatie:

De omgeving instellen voor Azure App Service

Voor een zelfstandige Blazor WebAssembly app kunt u de omgeving handmatig instellen via de configuratie starten of de Blazor-Environment header.

Voor een app aan de serverzijde stelt u de omgeving in via een ASPNETCORE_ENVIRONMENT app-instelling in Azure:

  1. Controleer of de hoofdlettergebruik van omgevingssegmenten in bestandsnamen van app-instellingen precies overeenkomt met het hoofdlettergebruik van hun omgevingsnamen. De overeenkomende naam van het app-instellingenbestand voor de Staging omgeving is appsettings.Staging.jsonbijvoorbeeld . Als de bestandsnaam appsettings.staging.json is (kleine letter 's'), wordt het bestand niet gevonden en worden de instellingen uit het bestand niet gebruikt in de Staging-omgeving.

  2. Voor Visual Studio-implementatie controleert u of de app is geïmplementeerd op de juiste implementatiesite. Voor een app met de naam BlazorAzureAppSamplewordt de app geïmplementeerd in de Staging implementatiesite.

  3. Stel in de Azure Portal voor het implementatieslot van de omgeving de omgeving in met de ASPNETCORE_ENVIRONMENT app-instelling. Voor een app met de naam BlazorAzureAppSample is de staging App Service-slot genaamd BlazorAzureAppSample/Staging. Maak voor de configuratie van de Staging slot een app-instelling aan voor ASPNETCORE_ENVIRONMENT met de waarde Staging. Instelling voor implementatieslots is ingeschakeld voor deze instelling.

Wanneer dit wordt aangevraagd in een browser, wordt de BlazorAzureAppSample/Staging app geladen in de Staging omgeving op https://blazorazureappsample-staging.azurewebsites.net.

Wanneer de app in de browser wordt geladen, geeft de antwoordheaderverzameling blazor.boot.json aan dat de waarde van de header Blazor-Environment is Staging.

App-instellingen uit het appsettings.{ENVIRONMENT}.json bestand worden geladen door de app, waarbij de tijdelijke aanduiding de {ENVIRONMENT} omgeving van de app is. In het voorgaande voorbeeld worden instellingen uit het appsettings.Staging.json bestand geladen.

De omgeving in een Blazor WebAssembly app lezen

Verkrijg de omgeving van de app in een component door IWebAssemblyHostEnvironment te injecteren en de eigenschap Environment te lezen.

ReadEnvironment.razor:

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

<h1>Environment example</h1>

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

Lees de omgeving client-side in een Blazor Web App

Ervan uitgaande dat prerendering niet is uitgeschakeld voor een component of de app, wordt een component in het .Client project voorgerenderd op de server. Omdat de server geen geregistreerde IWebAssemblyHostEnvironment service heeft, is het niet mogelijk om de service te injecteren en de hostomgevingsuitbreidingsmethoden en eigenschappen van de service-implementatie te gebruiken tijdens het voorbereiden van de server. Het injecteren van de service in een Interactive WebAssembly- of Interactive Auto-onderdeel resulteert in de volgende runtimefout:

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

Maak hiervoor een aangepaste service-implementatie voor IWebAssemblyHostEnvironment op de server. Voeg de volgende klasse toe aan het serverproject.

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

Registreer de service in het Program bestand van het serverproject.

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

Op dit moment kan de IWebAssemblyHostEnvironment-service worden ingevoegd in een interactief WebAssembly- of interactief auto-onderdeel en worden gebruikt zoals weergegeven in de sectie omgeving lezen in een Blazor WebAssembly-app.

In het voorgaande voorbeeld kunt u laten zien dat het mogelijk is om een andere serveromgeving te hebben dan de clientomgeving. Dit wordt niet aanbevolen en kan leiden tot willekeurige resultaten. Wanneer u de omgeving instelt in een Blazor Web App, is het het beste om deze af te stemmen op de server- en .Client-projectomgevingen. Houd rekening met het volgende scenario in een test-app:

  • Implementeer de omgevingseigenschap aan de clientzijde (webassembly) met de Staging omgeving via Blazor.start. Zie de sectie De client-omgeving instellen via opstartconfiguratie voor een voorbeeld.
  • Wijzig het bestand aan de serverzijde Properties/launchSettings.json niet. Laat de environmentVariables sectie staan met de ASPNETCORE_ENVIRONMENT omgevingsvariabele ingesteld op Development.

U ziet de waarde van de IWebAssemblyHostEnvironment.Environment eigenschapswijziging in de gebruikersinterface.

Wanneer het prerendering plaatsvindt op de server, wordt het onderdeel weergegeven in de Development omgeving:

Environment: Development

Wanneer het onderdeel slechts een seconde of twee later wordt geactiveerd nadat de Blazor bundel is gedownload en de .NET WebAssembly-runtime wordt geactiveerd, worden de waarden gewijzigd om aan te geven dat de client werkt in de Staging omgeving op de client:

Environment: Staging

In het voorgaande voorbeeld ziet u waarom u het beste de serveromgeving instelt op overeenstemming met de clientomgeving voor ontwikkelings-, test- en productie-implementaties.

Zie voor meer informatie de sectie Client-side services kunnen niet worden opgelost tijdens prerendering van het artikel Render-modi, dat verderop in de Blazor documentatie verschijnt.

De omgeving aan de clientzijde lezen tijdens het opstarten

Tijdens het WebAssemblyHostBuilder opstarten wordt de IWebAssemblyHostEnvironment functie beschikbaar gemaakt via de HostEnvironment eigenschap, waarmee omgevingsspecifieke logica in host builder-code wordt ingeschakeld.

In het bestand Program:

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

De volgende gemaksuitbreidingsmethoden staan controle van de huidige omgeving voor Development, Production, Staging en aangepaste omgevingsnamen toe via WebAssemblyHostEnvironmentExtensions.

In het bestand Program:

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

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

De eigenschap kan tijdens opstarten worden gebruikt wanneer de dienst niet beschikbaar is.

Aanvullende bronnen