Verwenden von mehreren Umgebungen in ASP.NET CoreUse multiple environments in ASP.NET Core

• 04/10/2019
• 7 Minuten Lesedauer
• • 
  • 

Von Rick AndersonBy Rick Anderson

ASP.NET Core konfiguriert das App-Verhalten basierend auf der Laufzeitumgebung mit einer Umgebungsvariablen.ASP.NET Core configures app behavior based on the runtime environment using an environment variable.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)View or download sample code (how to download)

UmgebungenEnvironments

ASP.NET Core liest die Umgebungsvariable ASPNETCORE_ENVIRONMENT beim Start der App und speichert diesen Wert unter IHostingEnvironment.EnvironmentName.ASP.NET Core reads the environment variable ASPNETCORE_ENVIRONMENT at app startup and stores the value in IHostingEnvironment.EnvironmentName. Sie können ASPNETCORE_ENVIRONMENT auf einen beliebigen Wert festlegen, das Framework unterstützt allerdings nur drei Werte: Entwicklung, Staging und Produktion.You can set ASPNETCORE_ENVIRONMENT to any value, but three values are supported by the framework: Development, Staging, and Production. Wenn ASPNETCORE_ENVIRONMENT nicht festgelegt ist, ist der Standardwert Production.If ASPNETCORE_ENVIRONMENT isn't set, it defaults to Production.

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:The preceding code:

• Ruft UseDeveloperExceptionPage auf, wenn ASPNETCORE_ENVIRONMENT auf Development festgelegt ist.Calls UseDeveloperExceptionPage when ASPNETCORE_ENVIRONMENT is set to Development.

• Ruft UseExceptionHandler auf, wenn der Wert von ASPNETCORE_ENVIRONMENT auf einen der folgenden Werte festgelegt ist:Calls UseExceptionHandler when the value of ASPNETCORE_ENVIRONMENT is set one of the following:

  • Staging
  • Production
  • Staging_2

Das Umgebungstaghilfsprogramm verwendet den Wert von IHostingEnvironment.EnvironmentName zum Einschließen oder Ausschließen von Markup im Element:The Environment Tag Helper uses the value of IHostingEnvironment.EnvironmentName to include or exclude markup in the element:

<environment include="Development">
    <div>&lt;environment include="Development"&gt;</div>
</environment>
<environment exclude="Development">
    <div>&lt;environment exclude="Development"&gt;</div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>
        &lt;environment include="Staging,Development,Staging_2"&gt;
    </div>
</environment>

Unter Windows und macOS wird bei Umgebungsvariablen und Werten die Groß-/Kleinschreibung nicht beachtet.On Windows and macOS, environment variables and values aren't case sensitive. Bei Linux-Umgebungsvariablen und -Werten wird die Groß-/Kleinschreibung standardmäßig beachtet.Linux environment variables and values are case sensitive by default.

EntwicklungDevelopment

In der Entwicklungsumgebung können Features aktiviert werden, die in der Produktion nicht verfügbar gemacht werden sollten.The development environment can enable features that shouldn't be exposed in production. Mit den ASP.NET Core-Vorlagen wird beispielsweise die Seite mit Ausnahmen für Entwickler in der Entwicklungsumgebung aktiviert.For example, the ASP.NET Core templates enable the Developer Exception Page in the development environment.

Die Umgebung für die Entwicklung lokaler Computer kann in der Datei Properties\launchSettings.json des Projekts festgelegt werden.The environment for local machine development can be set in the Properties\launchSettings.json file of the project. Mit in der Datei launchSettings.json festgelegten Umgebungsvariablen werden in der Systemumgebung festgelegte Werte überschrieben.Environment values set in launchSettings.json override values set in the system environment.

Die folgende JSON zeigt drei Profile aus der Datei launchSettings.json an:The following JSON shows three profiles from a launchSettings.json file:

{
  "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/"
    }
  }
}

"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.When the app is launched with dotnet run, the first profile with "commandName": "Project" is used. Der Wert von commandName gibt den zu startenden Webserver an.The value of commandName specifies the web server to launch. commandName kann einer der folgenden sein:commandName can be any one of the following:

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

Beim Start einer App mit dotnet run tritt Folgendes ein:When an app is launched with dotnet run:

• Die Datei launchSettings.json wird, sofern verfügbar, gelesen.launchSettings.json is read if available. Durch environmentVariables-Einstellungen in der Datei launchSettings.json werden Umgebungsvariablen überschrieben.environmentVariables settings in launchSettings.json override environment variables.
• Die Hostingumgebung wird angezeigt.The hosting environment is displayed.

Die folgende Ausgabe zeigt eine App, die mit dotnet run gestartet wurde:The following output shows an app started with dotnet run:

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:The Visual Studio project properties Debug tab provides a GUI to edit the launchSettings.json file:

An Projektprofilen vorgenommene Änderungen werden möglicherweise erst nach einem Neustart des Webservers wirksam.Changes made to project profiles may not take effect until the web server is restarted. Kestrel muss neu gestartet werden, bevor es an der Umgebung vorgenommene Änderungen erkennen kann.Kestrel must be restarted before it can detect changes made to its environment.

Wenn Sie Visual Studio Code verwenden, können Umgebungsvariablen in der Datei .vscode/launch.json festgelegt werden.When using Visual Studio Code, environment variables can be set in the .vscode/launch.json file. Im folgenden Beispiel wird die Umgebung auf Development festgelegt:The following example sets the environment to Development:

{
   "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.A .vscode/launch.json file in the project isn't read when starting the app with dotnet run in the same way as Properties/launchSettings.json. 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.When launching an app in development that doesn't have a launchSettings.json file, either set the environment with an environment variable or a command-line argument to the dotnet run command.

ProduktionProduction

Die Produktionsumgebung sollte so konfiguriert werden, dass Sicherheit, Leistung und Stabilität der App maximiert werden.The production environment should be configured to maximize security, performance, and app robustness. Allgemeine Einstellungen, die sich von der Entwicklung unterscheiden, sind zum Beispiel:Some common settings that differ from development include:

• Zwischenspeicherung.Caching.
• Clientseitige Ressourcen werden gebündelt, verkleinert und potenziell von einem CDN bedient.Client-side resources are bundled, minified, and potentially served from a CDN.
• Seiten zur Fehlerdiagnose sind deaktiviert.Diagnostic error pages disabled.
• Angezeigte Fehlerseiten sind aktiviert.Friendly error pages enabled.
• Die Produktionsprotokollierung und -überwachung ist aktiviert.Production logging and monitoring enabled. Beispiel: Application Insights.For example, Application Insights.

Festlegen der UmgebungSet the environment

Es ist oft nützlich, zu Testzwecken eine bestimmte Umgebung festzulegen.It's often useful to set a specific environment for testing. Wenn die Umgebung nicht festgelegt ist, wird Production als Standardwert verwendet, wodurch die meisten Debugfeatures deaktiviert werden.If the environment isn't set, it defaults to Production, which disables most debugging features. Welche Methode zum Festlegen der Umgebung verwendet wird, hängt vom Betriebssystem ab.The method for setting the environment depends on the operating system.

Azure App ServiceAzure App Service

Führen Sie die folgenden Schritte durch, um die Umgebung in Azure App Service festzulegen:To set the environment in Azure App Service, perform the following steps:

1. Wählen Sie die App auf dem Blatt App Services aus.Select the app from the App Services blade.
2. Wählen Sie in der Gruppe EINSTELLUNGEN das Blatt Anwendungseinstellung aus.In the SETTINGS group, select the Application settings blade.
3. Wählen Sie im Bereich Anwendungseinstellung Neue Einstellung hinzufügen aus.In the Application settings area, select Add new setting.
4. Für Geben Sie einen Namen, bieten ASPNETCORE_ENVIRONMENT.For Enter a name, provide ASPNETCORE_ENVIRONMENT. Für Geben Sie einen Wert, geben Sie die Umgebung (z. B. Staging).For Enter a value, provide the environment (for example, Staging).
5. Aktivieren Sie das Kontrollkästchen Sloteinstellung, wenn Sie möchten, dass die Umgebungseinstellung im aktuellen Slot bleibt, wenn Bereitstellungsslots getauscht werden.Select the Slot Setting check box if you wish the environment setting to remain with the current slot when deployment slots are swapped. Weitere Informationen finden Sie in der Azure-Dokumentation: Welche Einstellungen werden ausgetauscht?.For more information, see Azure Documentation: Which settings are swapped?.
6. Klicken Sie oben auf dem Blatt auf Speichern.Select Save at the top of the blade.

Azure App Service startet die App automatisch neu, nachdem eine App-Einstellung (Umgebungsvariable) im Azure-Portal hinzugefügt, geändert oder gelöscht wurde.Azure App Service automatically restarts the app after an app setting (environment variable) is added, changed, or deleted in the Azure portal.

WindowsWindows

Zum Festlegen der ASPNETCORE_ENVIRONMENT für die aktuelle Sitzung werden folgende Befehle verwendet, wenn die App mit dotnet run gestartet wird:To set the ASPNETCORE_ENVIRONMENT for the current session when the app is started using dotnet run, the following commands are used:

EingabeaufforderungCommand prompt

set ASPNETCORE_ENVIRONMENT=Development

PowerShellPowerShell

$Env:ASPNETCORE_ENVIRONMENT = "Development"

Diese Befehle sind nur für das aktuelle Fenster wirksam.These commands only take effect for the current window. Wenn das Fenster geschlossen wird, wird die Einstellung ASPNETCORE_ENVIRONMENT auf die Standardeinstellung oder den Computerwert zurückgesetzt.When the window is closed, the ASPNETCORE_ENVIRONMENT setting reverts to the default setting or machine value.

Wenn Sie den Wert in Windows global festlegen möchten, nutzen Sie eine der folgenden Möglichkeiten:To set the value globally in Windows, use either of the following approaches:

• Öffnen Sie Systemsteuerung > System > Erweiterte Systemeinstellungen, und fügen Sie den Wert ASPNETCORE_ENVIRONMENT hinzu, oder bearbeiten Sie ihn:Open the Control Panel > System > Advanced system settings and add or edit the ASPNETCORE_ENVIRONMENT value:

  

  

• 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:Open an administrative command prompt and use the setx command or open an administrative PowerShell command prompt and use [Environment]::SetEnvironmentVariable:

  EingabeaufforderungCommand prompt

  setx ASPNETCORE_ENVIRONMENT Development /M
  

  Mit dem Parameter /M wird angegeben, dass die Umgebungsvariable auf Systemebene festgelegt wird.The /M switch indicates to set the environment variable at the system level. Ohne den Parameter /M wird die Umgebungsvariable für das Nutzerkonto festgelegt.If the /M switch isn't used, the environment variable is set for the user account.

  PowerShellPowerShell

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

  Mit dem Optionswert Machine wird angegeben, dass die Umgebungsvariable auf Systemebene festgelegt wird.The Machine option value indicates to set the environment variable at the system level. Verwenden Sie stattdessen den Optionswert User, wird die Umgebungsvariable für das Nutzerkonto festgelegt.If the option value is changed to User, the environment variable is set for the user account.

Sobald die Umgebungsvariable ASPNETCORE_ENVIRONMENT global festgelegt wird, gilt sie in jedem geöffneten Befehlsfenster für dotnet run.When the ASPNETCORE_ENVIRONMENT environment variable is set globally, it takes effect for dotnet run in any command window opened after the value is set.

web.configweb.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.To set the ASPNETCORE_ENVIRONMENT environment variable with web.config, see the Setting environment variables section of ASP.NET Core-Modul.

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

Pro IIS-AnwendungspoolPer IIS Application Pool

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>.To set the ASPNETCORE_ENVIRONMENT environment variable for an app running in an isolated Application Pool (supported on IIS 10.0 or later), see the AppCmd.exe command section of the Environment Variables <environmentVariables> topic. Wurde die Umgebungsvariable ASPNETCORE_ENVIRONMENT für einen Anwendungspool festgelegt, überschreibt der Wert die Einstellung auf Systemebene.When the ASPNETCORE_ENVIRONMENT environment variable is set for an app pool, its value overrides a setting at the system level.

macOSmacOS

Das Festlegen der aktuellen Umgebung für macOS kann inline während der Ausführung der App erfolgen:Setting the current environment for macOS can be performed in-line when running the app:

ASPNETCORE_ENVIRONMENT=Development dotnet run

Legen Sie die Umgebung alternativ mit export vor der Ausführung der App fest:Alternatively, set the environment with export prior to running the app:

export ASPNETCORE_ENVIRONMENT=Development

Umgebungsvariablen auf Computerebene werden in der BASHRC- oder BASH_PROFILE-Datei festgelegt.Machine-level environment variables are set in the .bashrc or .bash_profile file. Bearbeiten Sie die Datei mit einem beliebigen Text-Editor.Edit the file using any text editor. Fügen Sie die folgende Anweisung hinzu:Add the following statement:

export ASPNETCORE_ENVIRONMENT=Development

LinuxLinux

Verwenden Sie bei Linux-Distributionen für sitzungsbasierte Variableneinstellungen den Befehl export in der Befehlszeile und die BASH-PROFILE-Datei für Umgebungseinstellungen auf Computerebene.For Linux distros, use the export command at a command prompt for session-based variable settings and bash_profile file for machine-level environment settings.

Konfiguration nach UmgebungConfiguration by environment

Zum Laden von „Konfiguration nach Umgebung“ empfehlen wir:To load configuration by environment, we recommend:

• appsettings-Dateien (appsettings.<Umgebung>.json).appsettings files (appsettings.<Environment>.json). Weitere Informationen finden Sie unter Konfiguration: Dateikonfigurationsanbieter.See Configuration: File configuration provider.
• Umgebungsvariablen (in jedem System festgelegt, in dem die App gehostet wird)environment variables (set on each system where the app is hosted). Weitere Informationen finden Sie unter Konfiguration: Dateikonfigurationsanbieter und Sicheres Speichern geheimer App-Schlüssel in der Entwicklung: Umgebungsvariablen.See Configuration: File configuration provider and Safe storage of app secrets in development: Environment variables.
• Secret Manager (nur in der Entwicklungsumgebung)Secret Manager (in the Development environment only). Siehe Sichere Speicherung von app-Geheimnissen bei der Entwicklung in ASP.NET Core.See Sichere Speicherung von app-Geheimnissen bei der Entwicklung in ASP.NET Core.

Umgebungsbasierte Startklasse und MethodenEnvironment-based Startup class and methods

Konventionen der Startup-KlasseStartup class conventions

Nach dem Start einer ASP.NET Core-App lädt die Startklasse die App.When an ASP.NET Core app starts, the Startup class bootstraps the app. Die App kann je nach Umgebung unterschiedliche Startup-Klassen definieren (z.B. StartupDevelopment). Zur Laufzeit wird dann die passende Startup-Klasse ausgewählt.The app can define separate Startup classes for different environments (for example, StartupDevelopment), and the appropriate Startup class is selected at runtime. Die Klasse, deren Namenssuffix mit der aktuellen Umgebung übereinstimmt, wird priorisiert.The class whose name suffix matches the current environment is prioritized. Ist keine übereinstimmende Startup{EnvironmentName}-Klasse vorhanden, wird die Klasse Startup verwendet.If a matching Startup{EnvironmentName} class isn't found, the Startup class is used.

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:To implement environment-based Startup classes, create a Startup{EnvironmentName} class for each environment in use and a fallback Startup class:

// 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:Use the UseStartup(IWebHostBuilder, String) overload that accepts an assembly name:

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“Startup method conventions

Configure und ConfigureServices unterstützen umgebungsspezifische Versionen der Form Configure<EnvironmentName> und Configure<EnvironmentName>Services:Configure and ConfigureServices support environment-specific versions of the form Configure<EnvironmentName> and Configure<EnvironmentName>Services:

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 RessourcenAdditional resources

• Anwendungsstart in ASP.NET Core
• Konfiguration in ASP.NET Core
• IHostingEnvironment.EnvironmentNameIHostingEnvironment.EnvironmentName