ASP.NET Core-Laufzeitumgebungen

ASP.NET Core konfiguriert das App-Verhalten basierend auf der Laufzeitumgebung, was in der Regel widerspiegelt, wo die App ausgeführt wird.

Apps werden in der Regel während der lokalen Entwicklung in der Entwicklungsumgebung ausgeführt und auf dem Computer eines Entwicklers mit einem Satz konfigurierter Verhaltensweisen getestet. Im Gegensatz dazu werden sie in der Produktionsumgebung ausgeführt, wenn sie auf einem Server mit einem anderen Satz konfigurierter Verhaltensweisen bereitgestellt werden. Eine beliebige Anzahl zusätzlicher Umgebungen kann verwendet werden, z. B. die Stagingumgebung , die vom Framework zum Staging einer App vor der Livebereitstellung oder anderen Umgebungen bereitgestellt wird, die Entwickler erstellen.

In diesem Artikel werden App-Laufzeitumgebungen, die Verwendung der Umgebung zum Steuern des App-Verhaltens und das Festlegen der Umgebung beschrieben.

Anleitungen für Blazor-Umgebungen, die die Anleitungen in diesem Artikel ergänzen oder ersetzen, finden Sie unter ASP.NET Core-Blazor-Umgebungen.

Environments

Obwohl die Umgebung ein beliebiger Zeichenfolgenwert sein kann, werden die folgenden Umgebungswerte vom Framework bereitgestellt:

• Development
• Staging
• Production

Die Produktionsumgebung ist so konfiguriert, dass sicherheit, Leistung und App-Zuverlässigkeit maximiert werden. Allgemeine Entwicklereinstellungen und -konfigurationen, die sich von der Entwicklungsumgebung unterscheiden, umfassen:

• Aktivieren der Zwischenspeicherung.
• Bündeln und Minimieren von clientseitigen Ressourcen sowie potenziell deren Bereitstellung aus einem CDN.
• Deaktivieren von Diagnosefehlerseiten und Aktivieren von benutzerfreundlichen Fehlerseiten.
• Aktivieren der Produktionsprotokollierung und -überwachung. Beispielsweise ist die Protokollierung für Azure Application Insights aktiviert.

Die letzte Umgebungseinstellung, die von der App gelesen wird, bestimmt die Umgebung der App. Die Umgebung der App kann nicht geändert werden, während die App ausgeführt wird.

Protokollierung

Die Ausgabe in der Befehlsshell einer ausgeführten App beim Start gibt die Umgebung der App an. Im folgenden Beispiel wird die App in der Stagingumgebung ausgeführt:

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

Umgebungsvariablen, die die Laufzeitumgebung bestimmen

ASP.NET Core liest zur Bestimmung der Laufzeitumgebung aus den folgenden Umgebungsvariablen:

Wenn die DOTNET_ENVIRONMENT Variablen und ASPNETCORE_ENVIRONMENT Umgebungsvariablen nicht festgelegt sind, ist die Produktionsumgebung die Standardumgebung.

Unter Windows und macOS wird die Groß-/Kleinschreibung von Umgebungsvariablen nicht beachtet. Linux-Umgebungsvariablen sind groß- und kleinschreibungssensitiv.

Steuern der Codeausführung nach Umgebung

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

    ...
}

Innerhalb der App IHostEnvironment werden allgemeine Informationen zur Hostingumgebung der App bereitgestellt, und die IHostEnvironment.EnvironmentName Eigenschaft gibt die aktuelle Umgebung der App an.

Gerenderte Inhalte steuern

Injizieren Sie IHostEnvironment in eine vom Server gerenderte Razor-Komponente und verwenden Sie die Erweiterungsmethoden und die EnvironmentName-Eigenschaft des Dienstes, um die Umgebung für das Rendern von Inhalten zu bestimmen.

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

Für Blazor Web Apps, die eine Umgebung zur Steuerung des clientseitigen Renderings erfordern, siehe Prerender ASP.NET Core Razor components.

Festlegen der Umgebung in einer Befehlsshell, wenn die App ausgeführt wird (dotnet run)

Verwenden Sie die -e|--environment Option zum Festlegen der Umgebung:

dotnet run -e Staging

Festlegen der Umgebung mit der Starteinstellungsdatei (launchSettings.json)

Die Umgebung für die lokale Entwicklung kann in der Properties\launchSettings.json Datei des Projekts festgelegt werden. Umgebungswerte, die in launchSettings.json festgelegt werden, setzen die von der Systemumgebung festgelegten Werte außer Kraft.

Die Datei launchSettings.json enthält Folgendes:

• wird nur auf dem lokalen Entwicklungscomputer verwendet.
• Wird nicht bereitgestellt, wenn die App veröffentlicht wird.
• Kann mehrere Profile enthalten, die jeweils eine andere Umgebung konfigurieren.

Im folgenden Beispiel wird die Stagingumgebung für das https Startprofil mithilfe der ASPNETCORE_ENVIRONMENT Umgebungsvariable festgelegt:

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

In Visual Studio gibt es zwei Ansätze zum Festlegen der Umgebung über Startprofile:

• Drücken SieALT-EINGABETASTE+, oder wählen Sie "Eigenschaften" aus, nachdem Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt geklickt haben. Wählen Sie "Allgemein debuggen>" und dann den Ui-Link "Debugstartprofile öffnen" aus.

• Wählen Sie im Projektmappen-Explorer{PROJECT NAME} Debug-Eigenschaften aus dem Menü „Debuggen“ aus, wobei der {PROJECT NAME} Platzhaltername ein Projektname ist.

Die vorherigen Ansätze öffnen das Dialogfeld " Profile starten ", in dem Sie die Umgebungsvariableneinstellungen in der launchSettings.json Datei bearbeiten können. An Projektprofilen vorgenommene Änderungen werden möglicherweise erst nach einem Neustart des Webservers wirksam. Kestrel muss neu gestartet werden, bevor es an der Umgebung vorgenommene Änderungen erkennen kann.

Profile können in der Visual Studio-Benutzeroberfläche neben der Schaltfläche "Start" (►) ausgewählt werden.

Wenn eine Projektmappe mehrere Projekte enthält, legen Sie nur die Umgebung für das Startprojekt fest.

Alternativ können Sie den dotnet run-Befehl mit der -lp|--launch-profile-Option verwenden, die auf den Namen des Profils eingestellt ist. Dieser Ansatz unterstützt nur Startprofile basierend auf dem Project Befehl.

dotnet run -lp "https"

Wenn Sie Visual Studio Code mit dem C#Dev Kit für Visual Studio Code (Erste Schritte mit C# in VS Code) verwenden, werden Startprofile aus der App-Datei launchSettings.json abgerufen.

Wenn das C# Dev Kit nicht verwendet wird, legen Sie die ASPNETCORE_ENVIRONMENT Umgebungsvariable im .vscode/launch.jsonenv Abschnitt zusammen mit anderen Umgebungsvariablen im Abschnitt fest:

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

Die Datei .vscode/launch.json wird nur von Visual Studio Code verwendet.

Festlegen der Umgebung mit einer Umgebungsvariable

Häufig ist es sinnvoll, mit einer Umgebungsvariablen oder Plattformeinstellung eine bestimmte Umgebung für Tests festzulegen. Wenn die Umgebung nicht festgelegt ist, wird standardmäßig die Produktionsumgebung verwendet, wodurch die meisten Debugfeatures deaktiviert werden. Welche Methode zum Festlegen der Umgebung verwendet wird, hängt vom Betriebssystem ab.

Azure App Service

Apps, die in Azure App Service bereitgestellt werden, übernehmen standardmäßig die Produktionsumgebung.

Informationen zum Festlegen der ASPNETCORE_ENVIRONMENT Umgebungsvariablen finden Sie in der Azure-Dokumentation in den folgenden Ressourcen:

• Konfigurieren einer App Service-App
• Einrichten von Stagingumgebungen in Azure App Service

Azure App Service startet die App automatisch neu, nachdem eine App-Einstellung hinzugefügt, geändert oder gelöscht wurde.

Festlegen der Umgebungsvariable für einen Prozess

Verwenden Sie die folgenden Befehle, um die ASPNETCORE_ENVIRONMENT Umgebungsvariable für die aktuelle Sitzung (Befehlsshell) festzulegen, wenn die App mit der Verwendung dotnet rungestartet wird. Nachdem die Umgebungsvariable festgelegt wurde, wird die App ohne Startprofil mit der --no-launch-profile Option gestartet.

1. Legen Sie in der Befehlsshell die Umgebungsvariable mithilfe des geeigneten Ansatzes für Ihr Betriebssystem fest.

2. Führen Sie den dotnet run Befehl aus, ohne ein Startprofil zu verwenden:

   dotnet run --no-launch-profile
   

Bei Verwendung von PowerShell können die vorherigen Schritte in den folgenden beiden Befehlen kombiniert werden. Im folgenden Beispiel wird die Staging-Umgebung festgelegt:

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

Globales Festlegen der Umgebungsvariable

Verwenden Sie die entsprechenden Anleitungen für Ihr Betriebssystem, um die ASPNETCORE_ENVIRONMENT Umgebungsvariable festzulegen.

Wenn die ASPNETCORE_ENVIRONMENT Umgebungsvariable global festgelegt wird, wird sie für den dotnet run Befehl in jeder Befehlsshell wirksam, die nach dem Festlegen des Werts geöffnet wird. Umgebungswerte, die durch Startprofile in der launchSettings.json Datei festgelegt wurden, setzen Werte für die Systemumgebung außer Kraft.

Festlegen der Umgebung für apps, die in IIS bereitgestellt werden

Um die ASPNETCORE_ENVIRONMENT Umgebungsvariable mit der web.config Datei festzulegen, siehe web.config Datei.

Um die Umgebungsvariable für die Bereitstellung auf IIS festzulegen, schließen Sie die <EnvironmentName> Eigenschaft in die Veröffentlichungsprofildatei (PUBXML) oder Projektdatei ein. Im folgenden Beispiel wird die Umgebung in web.config auf die Stagingumgebung festgelegt, wenn das Projekt veröffentlicht wird.

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

Informationen zum Festlegen der ASPNETCORE_ENVIRONMENT Umgebungsvariable für eine App, die in einem isolierten Anwendungspool ausgeführt wird (unterstützt auf IIS 10.0 oder höher), finden Sie unter Umgebungsvariablen<>. Wenn die ASPNETCORE_ENVIRONMENT Umgebungsvariable für einen Anwendungspool festgelegt wird, überschreibt der Wert eine Einstellung auf Systemebene.

Wenn Sie eine App in IIS hosten und die ASPNETCORE_ENVIRONMENT Umgebungsvariable hinzufügen oder ändern, verwenden Sie eine der folgenden Ansätze, um den neuen Wert für die Ausführung von Apps wirksam zu machen:

• Führen Sie net stop was /y gefolgt von net start w3svc in einer Befehlsshell aus.
• Starten Sie den Server neu.

Docker

Legen Sie die Umgebung der App mithilfe eines der Ansätze in diesem Abschnitt fest.

Verwenden einer Dockerfile-Datei

Legen Sie die ASPNETCORE_ENVIRONMENT Umgebungsvariable in der Dockerfile-Datei mithilfe der ENV Anweisung fest:

ENV ASPNETCORE_ENVIRONMENT=Staging

Verwenden von Docker Compose

Definieren Sie für Multi-Service-Apps, die mit Docker Compose verwaltet werden, Umgebungsvariablen in der docker-compose.yml Datei:

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

Eine zur Laufzeit durch Docker Compose festgelegte Umgebung setzt eine Umgebung außer Kraft, die von der Dockerfile festgelegt wird.

Verwenden des docker run Befehls

Wenn Sie den Docker-Container mit dem docker run Befehl ausführen, legen Sie die ASPNETCORE_ENVIRONMENT Umgebungsvariable mit der -e|--env Option fest:

docker run -e ASPNETCORE_ENVIRONMENT=Staging aspnet_core_image

Eine zur Laufzeit gesetzte Umgebung mit docker run überschreibt eine vom Dockerfile festgelegte Umgebung.

Docker-Umgebungsdatei

Legen Sie die ASPNETCORE_ENVIRONMENT Umgebungsvariable mithilfe einer Docker-Umgebungsdatei (.env) fest.

env_variables.env:

ASPNETCORE_ENVIRONMENT=Staging

Laden Sie die Datei mit der --env-file Option, wenn Sie den docker run Befehl ausführen:

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

Eine zur Laufzeit gesetzte Umgebung mit docker run überschreibt eine vom Dockerfile festgelegte Umgebung.

Festlegen der Umgebung im Startcode der App

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

Laden der Konfiguration je nach Umgebung

Informationen zum Laden der Konfiguration nach Umgebung finden Sie unter Konfiguration in ASP.NET Core.

Zugreifen auf die Umgebung aus einer Startup Klasse

Die Verwendung einer Startup Klasse (Startup.cs) mit Configure und ConfigureServices Methoden war vor der Veröffentlichung von .NET 6 erforderlich und wird weiterhin unterstützt.

Fügen Sie IWebHostEnvironment in den Startup-Konstruktor ein, um die Codeausführung zu steuern. Dieser Ansatz ist hilfreich, wenn die App für den Startcode konfiguriert werden muss und dies nur in wenigen Umgebungen mit minimalen Codeabweichungen pro Umgebung erforderlich ist.

Im folgenden Beispiel wird die Umgebung im _env Feld gespeichert und steuert die Codeausführung basierend auf der App-Umgebung:

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
        {
            ...
        }

        ...
    }
}

Umgebungsspezifische Startup Klasse

Eine App kann mehrere Startup Klassen für verschiedene Umgebungen mit der Benennungskonventionsklasse Startup{EnvironmentName} definieren, wobei der Platzhalter der {ENVIRONMENT NAME} Umgebungsname ist.

Die Klasse, deren Namenssuffix mit der aktuellen Umgebung übereinstimmt, wird priorisiert. Ist keine übereinstimmende Startup{EnvironmentName}-Klasse vorhanden, wird die Klasse Startup verwendet.

Um umgebungsbasierte Startup Klassen zu implementieren, erstellen Sie beliebig viele Startup{EnvironmentName} Klassen und eine Fallbackklasse Startup :

public class StartupDevelopment
{
    ...
}

public class StartupProduction
{
    ...
}

public class Startup
{
    ...
}

Wo der Host-Generator erstellt wird, rufen Sie auf HostingAbstractionsWebHostBuilderExtensions.UseStartup, der einen Assemblynamen akzeptiert, um die richtige Startup Klasse zu laden:

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

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

Umgebungsspezifische Startup Klassenmethoden

Die Methoden Configure und ConfigureServices unterstützen umgebungsspezifische Versionen des Formulars Configure{ENVIRONMENT NAME} und Configure{ENVIRONMENT NAME}Services, wobei der Platzhalter {ENVIRONMENT NAME} der Name der Umgebung ist. Wenn kein übereinstimmender Umgebungsname für die benannten Methoden gefunden wird, wird die ConfigureServices-Methode bzw. die Configure-Methode verwendet.

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

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

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

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

Weitere Ressourcen

• Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)
• Anwendungsstart in ASP.NET Core
• Konfiguration in ASP.NET Core
• Blazor-Umgebungen in ASP.NET Core