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.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

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: &lt;environment include="Development"&gt;</div>
</environment>
<environment exclude="Development">
    <div>The effective tag is: &lt;environment exclude="Development"&gt;</div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>
        The effective tag is:
        &lt;environment include="Staging,Development,Staging_2"&gt;
    </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

  • 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.

    Starten von IIS Express im Menü

  • 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" besitzt, 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 : Es wird Kestrel gestartet.

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.

Projekteigenschaften zum Festlegen von Umgebungsvariablen

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. Bei dieser Vorgehensweise werden nur Kestrel-Profile unterstützt.

    dotnet run --launch-profile "SampleApp"
    

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:

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

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 Anwendungseinstellungen Neue Anwendungseinstellung aus.
  4. Geben Sie im Fenster Anwendungseinstellung hinzufügen/bearbeiten ASPNETCORE_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:

    Erweiterte Systemeigenschaften

    ASP.NET Core-Umgebungsvariable

  • 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

Eine Anleitung zum Festlegen der Umgebungsvariable ASPNETCORE_ENVIRONMENT mit web.config finden Sie im Abschnitt Festlegen von Umgebungsvariablen der im Artikel zu ASP.NET Core-Modul.

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. Siehe 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. 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

Von Rick Anderson

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

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

Umgebungen

ASP.NET Core liest die Umgebungsvariable ASPNETCORE_ENVIRONMENT beim Start der App und speichert diesen Wert unter IHostingEnvironment.EnvironmentName. ASPNETCORE_ENVIRONMENT kann auf einen beliebigen Wert festgelegt werden, das Framework stellt allerdings nur drei Werte bereit:

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

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

    app.UseStaticFiles();
    app.UseMvc();
}

Der vorangehende Code:

  • Ruft UseDeveloperExceptionPage auf, wenn ASPNETCORE_ENVIRONMENT auf Development festgelegt ist.

  • Ruft UseExceptionHandler auf, wenn der Wert von ASPNETCORE_ENVIRONMENT auf einen der folgenden Werte festgelegt ist:

    • Staging
    • Production
    • Staging_2

Das Umgebungstaghilfsprogramm verwendet den Wert von IHostingEnvironment.EnvironmentName zum Einschließen oder Ausschließen von Markup im Element:

<environment include="Development">
    <div>The effective tag is: &lt;environment include="Development"&gt;</div>
</environment>
<environment exclude="Development">
    <div>The effective tag is: &lt;environment exclude="Development"&gt;</div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>
        The effective tag is:
        &lt;environment include="Staging,Development,Staging_2"&gt;
    </div>
</environment>

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.

Entwicklung

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 folgende JSON zeigt drei Profile aus der Datei launchSettings.json an:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:54339/",
      "sslPort": 0
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_My_Environment": "1",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_ENVIRONMENT": "Staging"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging"
      },
      "applicationUrl": "http://localhost:54340/"
    },
    "Kestrel Staging": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_My_Environment": "1",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_ENVIRONMENT": "Staging"
      },
      "applicationUrl": "http://localhost:51997/"
    }
  }
}

Hinweis

Die Eigenschaft applicationUrl in launchSettings.json kann eine Liste von Server-URLs angeben. Verwenden Sie ein Semikolon zwischen den URLs in der Liste:

"EnvironmentsSample": {
   "commandName": "Project",
   "launchBrowser": true,
   "applicationUrl": "https://localhost:5001;http://localhost:5000",
   "environmentVariables": {
     "ASPNETCORE_ENVIRONMENT": "Development"
   }
}

Wenn die Anwendung mit dotnet run gestartet wird, wird das erste Profil mit "commandName": "Project" verwendet. Der Wert von commandName gibt den zu startenden Webserver an. commandName kann einer der folgenden sein:

  • IISExpress
  • IIS
  • Project (über das Kestrel gestartet wird)

Beim Start einer App mit dotnet run tritt Folgendes ein:

  • Die Datei launchSettings.json wird, sofern verfügbar, gelesen. Durch environmentVariables-Einstellungen in der Datei launchSettings.json werden Umgebungsvariablen überschrieben.
  • Die Hostingumgebung wird angezeigt.

Die folgende Ausgabe zeigt eine App, die mit dotnet run gestartet wurde:

PS C:\Websites\EnvironmentsSample> dotnet run
Using launch settings from C:\Websites\EnvironmentsSample\Properties\launchSettings.json...
Hosting environment: Staging
Content root path: C:\Websites\EnvironmentsSample
Now listening on: http://localhost:54340
Application started. Press Ctrl+C to shut down.

Auf der Registerkarte Debuggen der Visual Studio-Projekteigenschaften wird eine grafische Benutzeroberfläche für die Bearbeitung der Datei launchSettings.json bereitgestellt:

Projekteigenschaften zum Festlegen von Umgebungsvariablen

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.

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 wird die Umgebung auf Development festgelegt:

{
   "version": "0.2.0",
   "configurations": [
        {
            "name": ".NET Core Launch (web)",

            ... additional VS Code configuration settings ...

            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development"
            }
        }
    ]
}

Die Datei .vscode/launch.json im Projekt wird nicht gelesen, wenn die App mit dotnet run genauso wie Properties/launchSettings.json gestartet wird. Wenn Sie eine App in der Entwicklung starten, die keine launchSettings.json-Datei enthält, legen Sie die Umgebung mit einer Umgebungsvariablen oder einem Befehlszeilenargument auf den dotnet run-Befehl fest.

Produktion

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

  • Zwischenspeicherung.
  • 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 ist 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.

Umgebungsvariable oder Plattformeinstellung

Azure App Service

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 Anwendungseinstellungen Neue Anwendungseinstellung aus.
  4. Geben Sie im Fenster Anwendungseinstellung hinzufügen/bearbeiten ASPNETCORE_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 (Umgebungsvariable) im Azure-Portal hinzugefügt, geändert oder gelöscht wurde.

Windows

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=Development

PowerShell

$Env:ASPNETCORE_ENVIRONMENT = "Development"

Diese Befehle sind nur für das aktuelle Fenster wirksam. Wenn das Fenster geschlossen wird, wird die Einstellung ASPNETCORE_ENVIRONMENT auf die Standardeinstellung oder den Computerwert zurückgesetzt.

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:

    Erweiterte Systemeigenschaften

    ASP.NET Core-Umgebungsvariable

  • 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 Development /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", "Development", "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.

web.config

Eine Anleitung zum Festlegen der Umgebungsvariable ASPNETCORE_ENVIRONMENT mit web.config finden Sie im Abschnitt Festlegen von Umgebungsvariablen der im Artikel zu ASP.NET Core-Modul.

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.

Wichtig

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=Development dotnet run

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

export ASPNETCORE_ENVIRONMENT=Development

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=Development

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. Siehe ASP.NET Core-Webhost.

Konfiguration nach Umgebung

Zum Laden von „Konfiguration nach Umgebung“ empfehlen wir:

Umgebungsbasierte Startklasse und Methoden

Einfügen von IHostingEnvironment in Startup.Configure

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

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Development environment code
    }
    else
    {
        // Code for all other environments
    }
}

Einfügen von IHostingEnvironment in die Startklasse

Fügen Sie IHostingEnvironment in den Startup-Konstruktor ein, und weisen Sie den Dienst einem Feld zu, das in der gesamten Startup-Klasse verwendet werden soll. 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
{
    private readonly IHostingEnvironment _env;

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

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            // Development environment code
        }
        else if (_env.IsStaging())
        {
            // Staging environment code
        }
        else
        {
            // Code for all other environments
        }
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            // Development environment code
        }
        else
        {
            // Code for all other environments
        }
    }
}

Konventionen der Startup-Klasse

Nach dem Start einer ASP.NET Core-App lädt die Startklasse die App. Die App kann je nach Umgebung unterschiedliche Startup-Klassen definieren (z. B. StartupDevelopment). 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.

Wenn Sie umgebungsbasierte Startup-Klassen implementieren möchten, erstellen Sie für jedes verwendete Element eine Startup{EnvironmentName}-Klasse und eine Fallback-Klasse des Typs Startup:

// Startup class to use in the Development environment
public class StartupDevelopment
{
    public void ConfigureServices(IServiceCollection services)
    {
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
    }
}

// Startup class to use in the Production environment
public class StartupProduction
{
    public void ConfigureServices(IServiceCollection services)
    {
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
    }
}

// Fallback Startup class
// Selected if the environment doesn't match a Startup{EnvironmentName} class
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
    }
}

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

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

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

    return WebHost.CreateDefaultBuilder(args)
        .UseStartup(assemblyName);
}

Konventionen der Methode „Start“

Configure und ConfigureServices unterstützen umgebungsspezifische Versionen der Form Configure<EnvironmentName> und Configure<EnvironmentName>Services. Diese Vorgehensweise ist nützlich, wenn die App „Startup“ für mehrere Umgebungen mit vielen Codeunterschieden pro Umgebung konfigurieren muss.

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        StartupConfigureServices(services);
    }

    public void ConfigureStagingServices(IServiceCollection services)
    {
        StartupConfigureServices(services);
    }

    private void StartupConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
    }

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

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

        app.UseStaticFiles();
        app.UseMvc();
    }

    public void ConfigureStaging(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (!env.IsStaging())
        {
            throw new Exception("Not staging.");
        }

        app.UseExceptionHandler("/Error");
        app.UseStaticFiles();
        app.UseMvc();
    }
}

Zusätzliche Ressourcen