Verwenden von mehreren Umgebungen in ASP.NET Core

Von Rick Anderson und Kirk Larkin

ASP.NET Core konfiguriert das App-Verhalten basierend auf der Laufzeitumgebung mit einer Umgebungsvariablen.

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

Umgebungen

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

1. DOTNET_ENVIRONMENT
2. ASPNETCORE_ENVIRONMENT, wenn die WebApplication.CreateBuilder-Methode aufgerufen wird. WebApplication.CreateBuilder wird von den Standardvorlagen der ASP.NET Core-Web-App aufgerufen. Der DOTNET_ENVIRONMENT-Wert überschreibt ASPNETCORE_ENVIRONMENT, wenn WebApplicationBuilder verwendet wird. Bei anderen Hosts, z. B. ConfigureWebHostDefaults und WebHost.CreateDefaultBuilder, hat ASPNETCORE_ENVIRONMENT höhere Priorität.

IHostEnvironment.EnvironmentName kann auf einen beliebigen Wert festgelegt werden, das Framework stellt allerdings die folgenden Werte bereit:

• Development: Mit der Datei launchSettings.json wird ASPNETCORE_ENVIRONMENT auf dem lokalen Computer auf Development festgelegt.
• Staging
• Production: Der Standardwert, wenn DOTNET_ENVIRONMENT und ASPNETCORE_ENVIRONMENT nicht festgelegt wurden.

Der folgende Code

• ähnelt dem von den ASP.NET Core-Vorlagen generierten Code.
• Aktiviert die Seite mit Ausnahmen für Entwickler, wenn ASPNETCORE_ENVIRONMENT auf Development festgelegt ist. Dies erfolgt automatisch durch die WebApplication.CreateBuilder-Methode.
• Ruft UseExceptionHandler auf, wenn der Wert von ASPNETCORE_ENVIRONMENT etwas anderes als Development ist.
• Stellt eine IWebHostEnvironment-Instanz in der Environment-Eigenschaft von WebApplication zur Verfügung.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Das Hilfsprogramm für Umgebungstags verwendet den Wert von IHostEnvironment.EnvironmentName zum Einschließen oder Ausschließen von Markup im Element:

<environment include="Development">
    <div>Environment is Development</div>
</environment>
<environment exclude="Development">
    <div>Environment is NOT Development</div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>Environment is: Staging, Development or Staging_2</div>
</environment>

Die Infoseite des Beispielcodes enthält das vorangehende Markup und zeigt den Wert von IWebHostEnvironment.EnvironmentName an.

Unter Windows und macOS wird bei Umgebungsvariablen und Werten die Groß-/Kleinschreibung nicht beachtet. Bei Linux-Umgebungsvariablen und -Werten wird die Groß-/Kleinschreibung standardmäßig beachtet.

Erstellen von „EnvironmentsSample“

Der in diesem Artikel verwendete Beispielcode basiert auf einem Razor Pages-Projekt namens EnvironmentsSample.

Mit den folgenden .NET CLI-Befehlen können Sie eine Web-App mit dem Namen EnvironmentsSample erstellen und ausführen:

dotnet new webapp -o EnvironmentsSample
cd EnvironmentsSample
dotnet run --verbosity normal

Wenn die App ausgeführt wird, zeigt sie eine Ausgabe ähnlich dem Folgenden an:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7152
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5105
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\Path\To\EnvironmentsSample

Festlegen der Umgebung in der Befehlszeile

Verwenden Sie das --environment Flag, um die Umgebung festzulegen. Beispiel:

dotnet run --environment Production

Der vorherige Befehl legt die Umgebung auf Production fest und zeigt im Befehlsfenster eine Ausgabe ähnlich dem Folgenden an:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7262
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5005
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Production
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\Path\To\EnvironmentsSample

Entwicklung und die Datei „launchSettings.json“

In der Entwicklungsumgebung können Features aktiviert werden, die in der Produktion nicht verfügbar gemacht werden sollten. Mithilfe der ASP.NET Core-Projektvorlagen wird beispielsweise die Seite mit Ausnahmen für Entwickler in der Entwicklungsumgebung aktiviert. Aufgrund der Leistungseinbußen erfolgt die Gültigkeitsprüfung und Abhängigkeitsüberprüfung nur in der Entwicklung.

Die Umgebung für die Entwicklung lokaler Computer kann in der Datei Properties\launchSettings.json des Projekts festgelegt werden. Mit in der Datei launchSettings.json festgelegten Umgebungsvariablen werden in der Systemumgebung festgelegte Werte überschrieben.

Die Datei launchSettings.json enthält Folgendes:

• wird nur auf dem lokalen Entwicklungscomputer verwendet.
• wird nicht bereitgestellt.
• enthält Profileinstellungen.

Der folgende JSON-Code zeigt die Datei launchSettings.json für ein ASP.NET Core-Webprojekt mit dem Namen EnvironmentsSample, das mit Visual Studio oder dotnet new erstellt wurde:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:59481",
      "sslPort": 44308
    }
  },
  "profiles": {
    "EnvironmentsSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Der vorstehende JSON-Code enthält zwei Profile:

• EnvironmentsSample: Der Profilname entspricht dem Projektnamen. Als erstes aufgeführtes Profil wird dieses Profil standardmäßig verwendet. Da der Schlüssel "commandName" den Wert "Project" hat, wird der Kestrel-Webserver gestartet.

• IIS Express: Der Schlüssel "commandName" hat den Wert "IISExpress", also ist IISExpress der Webserver.

Sie können das Startprofil auf das Projekt oder ein beliebiges anderes Profil in launchSettings.json festlegen. In der folgenden Abbildung wird etwa durch Auswählen des Projektnamens der Kestrel-Webserver gestartet.

Mit dem Wert von commandName wird der zu startende Webserver angegeben. commandName kann einer der folgenden sein:

• IISExpress : Es wird IIS Express gestartet.
• IIS : Es wird kein Webserver gestartet. Die Verfügbarkeit von IIS wird erwartet.
• Project: Startet Kestrel.

Die Registerkarte Debuggen/Allgemein in den Visual Studio 2022-Projekteigenschaften bietet den Link Öffnen der Benutzeroberfläche von Debugstartprofilen. Über diesen Link wird das Dialogfeld Startprofile geöffnet, in dem Sie die Einstellungen für die Umgebungsvariablen in der Datei launchSettings.json bearbeiten können. Sie können das Dialogfeld Startprofile auch über das Menü Debuggen öffnen, indem Sie <Projektname>: Debugeigenschaften auswählen. 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.

Die folgende launchSettings.json-Datei enthält mehrere Profile:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:59481",
      "sslPort": 44308
    }
  },
  "profiles": {
    "EnvironmentsSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "EnvironmentsSample-Staging": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
      }
    },
    "EnvironmentsSample-Production": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Profile können auf folgende Weise ausgewählt werden:

• Über die Visual Studio-Benutzeroberfläche.

• Verwenden Sie den CLI-Befehl dotnet run mit der Option --launch-profile, die auf den Namen des Profils festgelegt ist. Dieser Ansatz unterstützt nur Kestrel-Profile.

  dotnet run --launch-profile "EnvironmentsSample"
  

Warnung

In der Datei launchSettings.json sollten keine geheimen Schlüssel gespeichert werden. Mit dem Secret Manager-Tool können geheime Schlüssel für die lokale Umgebung gespeichert werden.

Wenn Sie Visual Studio Code verwenden, können Umgebungsvariablen in der Datei .vscode/launch.json festgelegt werden. Im folgenden Beispiel werden mehrere Umgebungsvariablen für Hostkonfigurationswerte festgelegt:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": ".NET Core Launch (web)",
            "type": "coreclr",
            // Configuration ommitted for brevity.
            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development",
                "ASPNETCORE_URLS": "https://localhost:5001",
                "ASPNETCORE_DETAILEDERRORS": "1",
                "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
            },
            // Configuration ommitted for brevity.

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

Produktion

Die Produktionsumgebung sollte so konfiguriert werden, dass eine maximale Sicherheit, Leistung und Stabilität der App erreicht werden. Allgemeine Einstellungen, die sich von der Entwicklung unterscheiden, sind zum Beispiel:

• Zwischenspeichern.
• Clientseitige Ressourcen werden gebündelt, verkleinert und potenziell von einem CDN bedient.
• Seiten zur Fehlerdiagnose sind deaktiviert.
• Angezeigte Fehlerseiten sind aktiviert.
• Die Produktionsprotokollierung und -überwachung sind aktiviert. Beispiel: Application Insights.

Festlegen der Umgebung durch Festlegen einer Umgebungsvariablen

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

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

Auf der Infoseite des Beispielcodes wird der Wert von IWebHostEnvironment.EnvironmentName angezeigt.

Azure App Service

Production ist der Standardwert, wenn DOTNET_ENVIRONMENT und ASPNETCORE_ENVIRONMENT nicht festgelegt wurden. In Azure bereitgestellte Apps sind standardmäßig Production.

So legen Sie die Umgebung in einer Azure App Service-App mithilfe des Portals fest

1. Wählen Sie die App auf der Seite App Services aus.
2. Wählen Sie in der Gruppe Einstellungen die Option Umgebungsvariablen aus.
3. Wählen Sie auf der Registerkarte App-Einstellungen + Hinzufügen aus.
4. Geben Sie im Fenster Anwendungseinstellung hinzufügen/bearbeitenASPNETCORE_ENVIRONMENT als Namen an. Geben Sie als Wert die Umgebung ein (beispielsweise Staging).
5. Aktivieren Sie das Kontrollkästchen Bereitstellungssloteinstellung, wenn Sie möchten, dass die Umgebungseinstellung im aktuellen Slot bleibt, wenn Bereitstellungsslots getauscht werden. Weitere Informationen finden Sie unter Einrichten von Stagingumgebungen in Azure App Service in der Azure-Dokumentation.
6. Wählen Sie OK aus, um das Dialogfeld Anwendungseinstellung hinzufügen/bearbeiten zu schließen.
7. Klicken Sie oben auf der Seite Konfiguration auf Speichern.

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

Windows: Festlegen der Umgebungsvariablen für einen Prozess

Umgebungsvariablen in der Datei launchSettings.json überschreiben in der Systemumgebung festgelegte Werte.

Um ASPNETCORE_ENVIRONMENT für die aktuelle Sitzung festzulegen, wenn die App mit dotnet run gestartet wird, geben Sie an einer Eingabeaufforderung oder in PowerShell die folgenden Befehle ein:

set ASPNETCORE_ENVIRONMENT=Staging
dotnet run --no-launch-profile

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

Windows: Globales Festlegen von Umgebungsvariablen

Die vorstehenden Befehle legen ASPNETCORE_ENVIRONMENT nur für Prozesse fest, die in diesem Befehlsfenster gestartet werden.

Wenn Sie den Wert in Windows global festlegen möchten, nutzen Sie eine der folgenden Möglichkeiten:

• Öffnen Sie Systemsteuerung>System>Erweiterte Systemeinstellungen, und fügen Sie den Wert ASPNETCORE_ENVIRONMENT hinzu, oder bearbeiten Sie ihn:

  

  

• Führen Sie die Eingabeaufforderung als Administrator aus, und verwenden Sie den Befehl setx. Alternativ können Sie auch die PowerShell-Eingabeaufforderung als Administrator ausführen und [Environment]::SetEnvironmentVariable nutzen:

  • setx ASPNETCORE_ENVIRONMENT Staging /M
    

    Der Schalter /M legt die Umgebungsvariable auf Systemebene fest. Ohne den Parameter /M wird die Umgebungsvariable für das Nutzerkonto festgelegt.

  • [Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Staging", "Machine")
    

    Die Option Machine legt die Umgebungsvariable auf Systemebene fest. Verwenden Sie stattdessen den Optionswert User, wird die Umgebungsvariable für das Nutzerkonto festgelegt.

Sobald die Umgebungsvariable ASPNETCORE_ENVIRONMENT global festgelegt wird, gilt sie in jedem geöffneten Befehlsfenster für dotnet run. Umgebungsvariablen in der Datei launchSettings.json überschreiben in der Systemumgebung festgelegte Werte.

Windows: Verwenden von „web.config“

Wie Sie die Umgebungsvariable ASPNETCORE_ENVIRONMENT mithilfe von web.config festlegen, erfahren Sie im Abschnitt Festlegen von Umgebungsvariablen der Datei web.config.

Windows: IIS-Bereitstellungen

Beziehen Sie die <EnvironmentName>-Eigenschaft in das Veröffentlichungsprofil (PUBXML) oder die Projektdatei ein. Dieser Ansatz legt die Umgebung in web.config fest, wenn das Projekt veröffentlicht wird:

<PropertyGroup>
  <EnvironmentName>Development</EnvironmentName>
</PropertyGroup>

Wenn Sie für eine App, die in einem isolierten Anwendungspool ausgeführt wird, die Umgebungsvariable ASPNETCORE_ENVIRONMENT festlegen möchten (unterstützt in IIS 10.0 oder höher), lesen Sie den Abschnitt AppCmd.exe command (Befehl „AppCmd.exe“) im Artikel zu Umgebungsvariablen<environmentVariables>. Wurde die Umgebungsvariable ASPNETCORE_ENVIRONMENT für einen Anwendungspool festgelegt, überschreibt der Wert die Einstellung auf Systemebene.

Wenn Sie eine APP in den IIS hosten und die Umgebungsvariable ASPNETCORE_ENVIRONMENT hinzufügen oder ändern, sorgen Sie auf eine der folgenden Arten und Weisen dafür, dass der neue Wert in den Apps hinterlegt ist:

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

macOS

Das Festlegen der aktuellen Umgebung für macOS kann inline während der Ausführung der App erfolgen:

ASPNETCORE_ENVIRONMENT=Staging dotnet run

Legen Sie die Umgebung alternativ mit export vor der Ausführung der App fest:

export ASPNETCORE_ENVIRONMENT=Staging

Umgebungsvariablen auf Computerebene werden in der BASHRC- oder BASH_PROFILE-Datei festgelegt. Bearbeiten Sie die Datei mit einem beliebigen Text-Editor. Fügen Sie die folgende Anweisung hinzu:

export ASPNETCORE_ENVIRONMENT=Staging

Linux

Verwenden Sie bei Linux-Distributionen für sitzungsbasierte Variableneinstellungen den Befehl export in der Eingabeaufforderung und die Datei bash_profile für Umgebungseinstellungen auf Computerebene.

Festlegen der Umgebung im Code

Um die Umgebung im Code festzulegen, verwenden Sie WebApplicationOptions.EnvironmentName beim Erstellen von WebApplicationBuilder, wie im folgenden Beispiel gezeigt:

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

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Konfiguration nach Umgebung

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

Konfigurieren von Diensten und Middleware nach Umgebung

Verwenden Sie WebApplicationBuilder.Environment oder WebApplication.Environment, um abhängig von der aktuellen Umgebung Dienste oder Middleware bedingungsgemäß hinzuzufügen. Die Projektvorlage enthält ein Beispiel für Code, der Middleware nur dann hinzufügt, wenn die aktuelle Umgebung nicht „Development“ ist:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Der hervorgehobene Code prüft die aktuelle Umgebung beim Aufbau der Anforderungspipeline. Um die aktuelle Umgebung beim Konfigurieren von Diensten zu überprüfen, verwenden Sie builder.Environment statt app.Environment.

Zusätzliche 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