ASP.NET Core runtime-omgevingen

ASP.NET Core configureert app-gedrag op basis van de runtime-omgeving, die meestal aangeeft waar de app wordt uitgevoerd.

Apps worden meestal uitgevoerd in de ontwikkelomgeving tijdens lokale ontwikkeling en testen op de computer van een ontwikkelaar met één set geconfigureerde gedragingen. Ze worden daarentegen uitgevoerd in de productieomgeving wanneer ze worden geïmplementeerd op een server met een andere set geconfigureerde gedragingen. Er kan een willekeurig aantal extra omgevingen worden gebruikt, zoals de faseringsomgeving die door het framework wordt geleverd voor het faseren van een app vóór de live-implementatie of andere omgevingen die ontwikkelaars maken.

In dit artikel worden runtime-omgevingen van apps beschreven, hoe u de omgeving gebruikt om het gedrag van apps te beheren en hoe u de omgeving instelt.

Zie BlazorASP.NET Core-omgevingen Blazorvoor richtlijnen voor omgevingen die worden toegevoegd aan of vervangen door de richtlijnen in dit artikel.

Environments

Hoewel de omgeving elke tekenreekswaarde kan zijn, worden de volgende omgevingswaarden geleverd door het framework:

• Development
• Staging
• Production

De productieomgeving is geconfigureerd om de betrouwbaarheid van beveiliging, prestaties en apps te maximaliseren. Algemene instellingen en configuratie van ontwikkelaars die verschillen van de ontwikkelomgeving zijn onder andere:

• Caching inschakelen.
• Resources aan de clientzijde bundelen en minificeren, samen met mogelijk leveren via een CDN.
• Diagnostische foutpagina's uitschakelen en gebruiksvriendelijke foutpagina's inschakelen.
• Productielogboekregistratie en -bewaking inschakelen. Logboekregistratie is bijvoorbeeld ingeschakeld voor Azure Application Insights.

De laatste omgevingsinstelling die door de app wordt gelezen, bepaalt de omgeving van de app. De omgeving van de app kan niet worden gewijzigd terwijl de app wordt uitgevoerd.

Logging

Uitvoer in de opdrachtshell van een actieve app bij het opstarten geeft de omgeving van de app aan. In het volgende voorbeeld wordt de app uitgevoerd in de faseringsomgeving:

info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Staging

Omgevingsvariabelen die de runtime-omgeving bepalen

Om de runtime-omgeving te bepalen, leest ASP.NET Core de volgende omgevingsvariabelen uit:

Als de DOTNET_ENVIRONMENT en ASPNETCORE_ENVIRONMENT omgevingsvariabelen niet zijn ingesteld, is de productieomgeving de standaardomgeving.

In Windows en macOS zijn namen van omgevingsvariabelen niet hoofdlettergevoelig. Linux-omgevingsvariabelen zijn hoofdlettergevoelig.

Uitvoering van code beheren per omgeving

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    if (env.IsProduction() || env.IsStaging() || env.IsEnvironment("Testing"))
    {
        app.UseExceptionHandler("/Error");
    }

    ...
}

In de app IHostEnvironment vindt u algemene informatie over de hostingomgeving van de app en de IHostEnvironment.EnvironmentName eigenschap geeft de huidige omgeving van de app aan.

Gerenderde inhoud beheren

Injecteer IHostEnvironment in een servergeenderd Razor onderdeel en gebruik de extensiemethoden en EnvironmentName eigenschap van de service om de omgeving voor renderinginhoud te bepalen:

@inject IHostEnvironment Env

@if (Env.IsDevelopment())
{
    <div>The environment is Development.</div>
}

@if (!Env.IsDevelopment())
{
    <div>The environment isn't Development.</div>
}

@if (Env.IsStaging() || Env.EnvironmentName == "Testing")
{
    <div>The environment is either Staging or Testing.</div>
}

Zie Blazor Web Apps waarvoor de omgeving de rendering aan clientzijde moet beheren, Prerender ASP.NET Core-onderdelenRazor.

De omgeving instellen in een opdrachtshell wanneer de app wordt uitgevoerd (dotnet run)

Gebruik de -e|--environment optie om de omgeving in te stellen:

dotnet run -e Staging

De omgeving instellen met het startinstellingenbestand (launchSettings.json)

De omgeving voor lokale ontwikkeling kan worden ingesteld in het Properties\launchSettings.json bestand van het project. Omgevingswaarden die zijn ingesteld in launchSettings.json overschrijven waarden die zijn ingesteld door de systeemomgeving.

Het bestand launchSettings.json:

• Wordt alleen gebruikt op de lokale ontwikkelcomputer.
• Wordt niet geïmplementeerd wanneer de app wordt gepubliceerd.
• Kan meerdere profielen bevatten, die elk een andere omgeving configureren.

In het volgende voorbeeld wordt de faseringsomgeving voor het https startprofiel ingesteld met behulp van de ASPNETCORE_ENVIRONMENT omgevingsvariabele:

"https": {
  "commandName": "Project",
  "dotnetRunMessages": true,
  "launchBrowser": true,
  "applicationUrl": "https://localhost:7205",
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Staging"
  }
}

In Visual Studio zijn er twee benaderingen voor het instellen van de omgeving via startprofielen:

• Druk op Alt+Enter of selecteer Eigenschappen nadat u met de rechtermuisknop op het project in Solution Explorer hebt geklikt. Selecteer Debug>Algemeen, gevolgd door de koppeling UI voor het openen van debugstartprofielen te selecteren.

• Als het project is geselecteerd in Solution Explorer, selecteert u {PROJECT NAME} Debug Properties in het menu Debug , waarbij de {PROJECT NAME} tijdelijke aanduiding een projectnaam is.

Met de voorgaande benaderingen opent u het dialoogvenster Profielen starten, waar u de instellingen van de omgevingsvariabele in het launchSettings.json bestand kunt bewerken. Wijzigingen die zijn aangebracht in projectprofielen, worden mogelijk pas van kracht nadat de webserver opnieuw is opgestart. Kestrel moet opnieuw worden gestart voordat wijzigingen in de omgeving kunnen worden gedetecteerd.

Profielen kunnen worden geselecteerd in de Gebruikersinterface van Visual Studio naast de knop Start ((*)).

Wanneer een oplossing meerdere projecten bevat, stelt u alleen de omgeving voor het opstartproject in.

U kunt ook de dotnet run opdracht gebruiken met de -lp|--launch-profile optie die is ingesteld op de naam van het profiel. Deze benadering ondersteunt alleen startprofielen op basis van de Project opdracht.

dotnet run -lp "https"

Wanneer u Visual Studio Code gebruikt met de C# Dev Kit voor Visual Studio Code (Aan de slag met C# in VS Code), worden startprofielen opgehaald uit het bestand van launchSettings.json de app.

Als de C# Dev Kit niet wordt gebruikt, stelt u de ASPNETCORE_ENVIRONMENT omgevingsvariabele in de .vscode/launch.json sectie in env , samen met andere omgevingsvariabelen die zijn ingesteld in de sectie:

"env": {
    "ASPNETCORE_ENVIRONMENT": "Staging",
    ...
},

Het .vscode/launch.json bestand wordt alleen gebruikt door Visual Studio Code.

De omgeving instellen met een omgevingsvariabele

Het is vaak handig om een specifieke omgeving in te stellen voor testen met een omgevingsvariabele of platforminstelling. Als de omgeving niet is ingesteld, wordt deze standaard ingesteld in de productieomgeving, waardoor de meeste functies voor foutopsporing worden uitgeschakeld. De methode voor het instellen van de omgeving is afhankelijk van het besturingssysteem.

Azure App Service

Apps die zijn geïmplementeerd in Azure App Service gebruiken standaard de productieomgeving.

Als u de ASPNETCORE_ENVIRONMENT omgevingsvariabele wilt instellen, raadpleegt u de volgende resources in de Azure-documentatie:

• Een App Service-app configureren
• Faseringsomgevingen instellen in Azure App Service

Azure App Service start de app automatisch opnieuw op nadat een app-instelling is toegevoegd, gewijzigd of verwijderd.

Omgevingsvariabele instellen voor een proces

Gebruik de volgende opdrachten om de ASPNETCORE_ENVIRONMENT omgevingsvariabele in te stellen voor de huidige sessie (opdrachtprompt) wanneer de app wordt gestart met dotnet run. Nadat de omgevingsvariabele is ingesteld, wordt de app gestart zonder een startprofiel met behulp van de --no-launch-profile optie.

1. Stel in de opdrachtshell de omgevingsvariabele in met behulp van de juiste methode voor uw besturingssysteem.

2. Voer de dotnet run opdracht uit zonder een startprofiel te gebruiken:

   dotnet run --no-launch-profile
   

Wanneer u PowerShell gebruikt, kunnen de voorgaande stappen worden gecombineerd in de volgende twee opdrachten. In het volgende voorbeeld wordt de stagingomgeving geconfigureerd:

$Env:ASPNETCORE_ENVIRONMENT = "Staging"
dotnet run --no-launch-profile

Omgevingsvariabele globaal instellen

Gebruik de juiste richtlijnen voor uw besturingssysteem om de ASPNETCORE_ENVIRONMENT omgevingsvariabele in te stellen.

Wanneer de ASPNETCORE_ENVIRONMENT omgevingsvariabele globaal is ingesteld, wordt deze van kracht voor de opdracht in een dotnet run opdrachtshell die wordt geopend nadat de waarde is ingesteld. Omgevingswaarden die zijn ingesteld door startprofielen in het launchSettings.json bestand overschrijven waarden die zijn ingesteld voor de systeemomgeving.

De omgeving instellen voor apps die zijn geïmplementeerd in IIS

Zie het web.config-bestand om de omgevingsvariabele met het web.config bestand in te stellen.

Als u de omgevingsvariabele voor implementatie wilt instellen op IIS, neemt u de <EnvironmentName> eigenschap op in het publicatieprofiel (.pubxml) of projectbestand. In het volgende voorbeeld wordt de omgeving in web.config ingesteld op de stagingomgeving als het project wordt gepubliceerd.

<PropertyGroup>
  <EnvironmentName>Staging</EnvironmentName>
</PropertyGroup>

Als u de ASPNETCORE_ENVIRONMENT omgevingsvariabele wilt instellen voor een applicatie die draait in een geïsoleerde Application Pool (ondersteund op IIS 10.0 of hoger), zie "Omgevingsvariabelen" <environmentVariables>. Wanneer de ASPNETCORE_ENVIRONMENT omgevingsvariabele is ingesteld voor een groep van toepassingen, overschrijft de waarde ervan een instelling op systeemniveau.

Wanneer u een app host in IIS en de ASPNETCORE_ENVIRONMENT omgevingsvariabele toevoegt of wijzigt, gebruikt u een van de volgende methoden om de nieuwe waarde van kracht te laten worden voor het uitvoeren van apps:

• Voer de opdracht net stop was /y uit gevolgd door net start w3svc in een opdrachtshell.
• Start de server opnieuw op.

Docker

Stel de omgeving van de app in met behulp van een van de benaderingen in deze sectie.

Een Dockerfile gebruiken

Stel de ASPNETCORE_ENVIRONMENT omgevingsvariabele in het Dockerfile in met behulp van de ENV instructie:

ENV ASPNETCORE_ENVIRONMENT=Staging

Docker Compose gebruiken

Definieer ASPNETCORE_ENVIRONMENT omgevingsvariabelen in het docker-compose.yml bestand voor apps met meerdere services die worden beheerd met Docker Compose:

version: "3.9"
services:
  web:
    build: .
    ports:
      - "8000:5000"
    environment:
      - ASPNETCORE_ENVIRONMENT=Staging
      - API_KEY=...

Een omgeving die tijdens runtime is ingesteld met Docker Compose overschrijft een omgeving die is ingesteld door het Dockerfile.

Gebruik de docker run-opdracht

Wanneer u de Docker-container uitvoert met de docker run opdracht, stelt u de ASPNETCORE_ENVIRONMENT omgevingsvariabele in met de -e|--env optie:

docker run -e ASPNETCORE_ENVIRONMENT=Staging aspnet_core_image

Een omgeving die tijdens runtime is ingesteld, overschrijft docker run een omgeving die is ingesteld door het Dockerfile.

Docker-omgevingsbestand

Stel de ASPNETCORE_ENVIRONMENT omgevingsvariabele in met behulp van een Docker-omgevingsbestand (.env).

env_variables.env:

ASPNETCORE_ENVIRONMENT=Staging

Laad het bestand met de --env-file optie bij het uitvoeren van de docker run opdracht:

docker run --env-file ./env_variables.env aspnet_core_image

Een omgeving die tijdens runtime is ingesteld, overschrijft docker run een omgeving die is ingesteld door het Dockerfile.

De omgeving instellen in de opstartcode van de app

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    EnvironmentName = Environments.Staging
}); 

Configuratie laden op basis van omgeving

Zie Configuratie in ASP.NET Core als u de configuratie per omgeving wilt laden.

Toegang tot de omgeving vanuit een Startup klasse

Het gebruik van een Startup klasse (Startup.cs) met Configure en ConfigureServices methoden was vereist voordat .NET 6 werd uitgebracht en blijft ondersteund.

Injecteer IWebHostEnvironment in de Startup constructor om de uitvoering van code te beheren. Deze aanpak is handig wanneer de app opstartcode moet configureren voor slechts enkele omgevingen met minimale codeverschillen per omgeving.

In het volgende voorbeeld wordt de omgeving opgeslagen in het _env veld en wordt de uitvoering van code beheerd op basis van de omgeving van de app:

public class Startup
{
    private readonly IWebHostEnvironment _env;

    public Startup(IWebHostEnvironment env)
    {
        _env = env;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else if (_env.IsStaging())
        {
            ...
        }
        else
        {
            ...
        }
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else
        {
            ...
        }

        ...
    }
}

Omgevingsspecifieke Startup klasse

Een app kan meerdere Startup klassen definiëren voor verschillende omgevingen met de naamconventieklasse Startup{EnvironmentName} , waarbij de tijdelijke aanduiding de {ENVIRONMENT NAME} naam van de omgeving is.

De klasse waarvan het achtervoegsel de naam overeenkomt met de huidige omgeving, krijgt prioriteit. Als er geen overeenkomende Startup{EnvironmentName} klasse wordt gevonden, wordt de Startup klasse gebruikt.

Als u omgevingsklassen Startup wilt implementeren, maakt u zo veel Startup{EnvironmentName} klassen als nodig is en een terugvalklasse Startup :

public class StartupDevelopment
{
    ...
}

public class StartupProduction
{
    ...
}

public class Startup
{
    ...
}

Wanneer de hostbouwer wordt gemaakt, roept u HostingAbstractionsWebHostBuilderExtensions.UseStartupaan, waarmee een assemblynaam wordt geaccepteerd om de juiste Startup klasse te laden:

public static IHostBuilder CreateHostBuilder(string[] args)
{
    var assemblyName = typeof(Startup).GetTypeInfo().Assembly.FullName;

    return Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup(assemblyName);
        });
}

Omgevingsspecifieke Startup klassemethoden

De Configure en ConfigureServices methoden ondersteunen omgevingsspecifieke versies van het formulier Configure{ENVIRONMENT NAME} en Configure{ENVIRONMENT NAME}Services, waarbij de tijdelijke aanduiding de naam van de {ENVIRONMENT NAME} omgeving is. Als een overeenkomende omgevingsnaam niet wordt gevonden voor de benoemde methoden, wordt de ConfigureServices of Configure methode respectievelijk gebruikt.

public void ConfigureDevelopmentServices(IServiceCollection services)
{
    ...
}

public void ConfigureStagingServices(IServiceCollection services)
{
    ...
}

public void ConfigureProductionServices(IServiceCollection services)
{
    ...
}

public void ConfigureServices(IServiceCollection services)
{
    ...
}

Aanvullende bronnen

• Voorbeeldcode bekijken of downloaden (hoe download je)
• app opstarten in ASP.NET Core
• Configuratie in ASP.NET Core
• ASP.NET Core Blazor-omgevingen