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. DOTNET_ENVIRONMENT wird vom ASPNETCORE_ENVIRONMENT-Wert überschrieben.

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"
  

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

Von Rick Anderson und Kirk Larkin

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

Umgebungen

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

1. DOTNET_ENVIRONMENT
2. ASPNETCORE_ENVIRONMENT, bei Aufruf von ConfigureWebHostDefaults. ConfigureWebHostDefaults wird von den Standardvorlagen der ASP.NET Core-Web-App aufgerufen. DOTNET_ENVIRONMENT wird vom ASPNETCORE_ENVIRONMENT-Wert überschrieben.

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

• Ruft UseDeveloperExceptionPage auf, wenn ASPNETCORE_ENVIRONMENT auf Development festgelegt ist.
• Ruft UseExceptionHandler auf, wenn der Wert von ASPNETCORE_ENVIRONMENT auf Staging, Production, oder Staging_2 festgelegt ist.
• fügt IWebHostEnvironment in Startup.Configure ein. Diese Vorgehensweise ist nützlich, wenn die App Startup.Configure nur für einige Umgebungen mit minimalen Codeunterschieden pro Umgebung anpassen muss.
• ähnelt dem von den ASP.NET Core-Vorlagen generierten Code.

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

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

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

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

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>The effective tag is: <environment include="Development"></div>
</environment>
<environment exclude="Development">
    <div>The effective tag is: <environment exclude="Development"></div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>
        The effective tag is:
        <environment include="Staging,Development,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 dem folgenden Code wird eine Web-App mit dem Namen EnvironmentsSample erstellt und ausgeführt:

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

Wenn die App ausgeführt wird, wird eine Ausgabe ähnlich der folgenden angezeigt:

Using launch settings from c:\tmp\EnvironmentsSample\Properties\launchSettings.json
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
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:\tmp\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. Mit den ASP.NET Core-Vorlagen wird beispielsweise die Seite mit Ausnahmen für Entwickler in der Entwicklungsumgebung aktiviert.

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:64645",
      "sslPort": 44366
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Das vorangehende Markup enthält zwei Profile:

• IIS Express: Das Standardprofil, das beim Starten der App in Visual Studio verwendet wird. Da der Schlüssel "commandName" den Wert "IISExpress" besitzt, wird der Webserver IISExpress verwendet. Sie können das Startprofil auf das Projekt oder ein beliebiges anderes Profil festlegen. In der folgenden Abbildung wird etwa durch Auswählen des Projektnamens der Kestrel-Webserver gestartet.

  

• EnvironmentsSample: Der Profilname entspricht dem Projektnamen. Dies ist das Standardprofil beim Starten der App mit dotnet run. Da der Schlüssel "commandName" den Wert "Project" hat, wird 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.

Auf der Registerkarte Debuggen der Visual Studio-Projekteigenschaften wird eine grafische Benutzeroberfläche für die Bearbeitung der Datei launchSettings.json bereitgestellt. 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:64645",
      "sslPort": 44366
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IISX-Production": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      }
    },
    "IISX-Staging": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "KestrelStaging": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging"
      }
    }
  }
}

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

• Über die Visual Studio-Benutzeroberfläche.

• Durch Verwenden des Befehls dotnet run in einer Befehlsshell, bei dem die Option --launch-profile auf den Profilnamen festgelegt ist. Dieser Ansatz unterstützt nur Kestrel-Profile.

  dotnet run --launch-profile "SampleApp"
  

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

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. Apps, die in Azure bereitgestellt werden, sind standardmäßig Production.

Führen Sie die folgenden Schritte durch, um die Umgebung in Azure App Service festzulegen:

1. Wählen Sie die App auf dem Blatt App Services aus.
2. Wählen Sie in der Gruppe Einstellungen das Blatt Konfiguration aus.
3. Wählen Sie auf der Registerkarte AnwendungseinstellungenNeue Anwendungseinstellung 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 Fenster Anwendungseinstellung hinzufügen/bearbeiten zu schließen.
7. Klicken Sie oben auf dem Blatt 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

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

Zum Festlegen der ASPNETCORE_ENVIRONMENT für die aktuelle Sitzung werden folgende Befehle verwendet, wenn die App mit dotnet run gestartet wird:

Eingabeaufforderung

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

PowerShell

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

Der vorangehende Befehl legt ASPNETCORE_ENVIRONMENT nur für Prozesse fest, die von diesem Befehlsfenster aus 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:

  Eingabeaufforderung

  setx ASPNETCORE_ENVIRONMENT Staging /M
  

  Mit dem Parameter /M wird angegeben, dass die Umgebungsvariable auf Systemebene festgelegt wird. Ohne den Parameter /M wird die Umgebungsvariable für das Nutzerkonto festgelegt.

  PowerShell

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

  Mit dem Optionswert Machine wird angegeben, dass die Umgebungsvariable auf Systemebene festgelegt wird. 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.

web.config

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

Projektdatei oder Veröffentlichungsprofil

Für 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>

Pro IIS-Anwendungspool

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

Rufen Sie beim Erstellen des Hosts UseEnvironment auf. Weitere Informationen finden Sie unter Generischer .NET-Host in ASP.NET Core.

Konfiguration nach Umgebung

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

Umgebungsbasierte Startklasse und Methoden

Einfügen von IWebHostEnvironment in die Startklasse

Fügen Sie IWebHostEnvironment in den Startup-Konstruktor ein. Diese Vorgehensweise ist nützlich, wenn die App Startup nur für einige Umgebungen mit minimalen Codeunterschieden pro Umgebung konfigurieren muss.

Im folgenden Beispiel:

• Die Umgebung wird im Feld _env gespeichert.
• _env wird in ConfigureServices und Configure verwendet, um die Startkonfiguration basierend auf der Umgebung der App anzuwenden.

public class Startup
{
    public Startup(IConfiguration configuration, IWebHostEnvironment env)
    {
        Configuration = configuration;
        _env = env;
    }

    public IConfiguration Configuration { get; }
    private readonly IWebHostEnvironment _env;

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            Console.WriteLine(_env.EnvironmentName);
        }
        else if (_env.IsStaging())
        {
            Console.WriteLine(_env.EnvironmentName);
        }
        else
        {
            Console.WriteLine("Not dev or staging");
        }

        services.AddRazorPages();
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

Konventionen der Startup-Klasse

Nach dem Start einer ASP.NET Core-App lädt die Startklasse die App. Die App kann je nach Umgebung mehrere Startup-Klassen definieren. Die entsprechende Startup-Klasse wird zur Laufzeit ausgewählt. Die Klasse, deren Namenssuffix mit der aktuellen Umgebung übereinstimmt, wird priorisiert. Ist keine übereinstimmende Startup{EnvironmentName}-Klasse vorhanden, wird die Klasse Startup verwendet. Diese Vorgehensweise ist nützlich, wenn die App „Startup“ für mehrere Umgebungen mit vielen Codeunterschieden pro Umgebung konfigurieren muss. Für typische Apps ist diese Vorgehensweise nicht erforderlich.

Wenn Sie umgebungsbasierte Startup-Klassen implementieren möchten, erstellen Sie eine Startup{EnvironmentName}-Klasse und eine Fallback-Klasse vom Typ Startup:

public class StartupDevelopment
{
    public StartupDevelopment(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app)
    {
        app.UseDeveloperExceptionPage();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public class StartupProduction
{
    public StartupProduction(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app)
    {

        app.UseExceptionHandler("/Error");
        app.UseHsts();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

Verwenden Sie die Überladung UseStartup(IWebHostBuilder, String), die einen Assemblynamen akzeptiert:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

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

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

Konventionen der Methode „Start“

Configure und ConfigureServices unterstützen umgebungsspezifische Versionen der Form Configure<EnvironmentName> und Configure<EnvironmentName>Services. Wenn keine passende Configure<EnvironmentName>Services- oder Configure<EnvironmentName>-Methode gefunden wird, wird die ConfigureServices- bzw. Configure-Methode verwendet. Diese Vorgehensweise eignet sich für Apps, bei denen Startoptionen für mehrere Umgebungen mit vielen Codeunterschieden pro Umgebung konfiguriert werden müssen:

public class Startup
{
    private void StartupConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages();
    }

    public void ConfigureDevelopmentServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureStagingServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureProductionServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        MyTrace.TraceMessage();

        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }

    public void ConfigureStaging(IApplicationBuilder app, IWebHostEnvironment env)
    {
        MyTrace.TraceMessage();

        app.UseExceptionHandler("/Error");
        app.UseHsts();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public static class MyTrace
{
    public static void TraceMessage([CallerMemberName] string memberName = "")
    {
        Console.WriteLine($"Method: {memberName}");
    }
}

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