ASP.NET Core-körningsmiljöer

ASP.NET Core konfigurerar appbeteende baserat på körningsmiljön, vilket vanligtvis återspeglar var appen körs.

Appar körs vanligtvis i utvecklingsmiljön under lokal utveckling och testning på en utvecklardator med en uppsättning konfigurerade beteenden. De körs däremot i produktionsmiljön när de distribueras till en server med en annan uppsättning konfigurerade beteenden. Valfritt antal ytterligare miljöer kan användas, till exempel mellanlagringsmiljön som tillhandahålls av ramverket för mellanlagring av en app före livedistribution eller andra miljöer som utvecklare skapar.

Den här artikeln beskriver appkörningsmiljöer, hur du använder miljön för att styra appens beteende och hur du ställer in miljön.

Vägledning Blazor för miljöer, som lägger till eller ersätter vägledningen i den här artikeln, finns i ASP.NET Core-miljöerBlazor.

Environments

Även om miljön kan vara valfritt strängvärde tillhandahålls följande miljövärden av ramverket:

• Development
• Staging
• Production

Produktionsmiljön är konfigurerad för att maximera säkerhet, prestanda och apptillförlitlighet. Vanliga inställningar och konfigurationer för utvecklare som skiljer sig från utvecklingsmiljön är:

• Aktivera cachelagring.
• Paketera och minimera resurser på klientsidan, och eventuellt leverera dem från ett CDN.
• Inaktivera diagnostikfelsidor och aktivera vänliga felsidor.
• Aktivera produktionsloggning och övervakning. Loggning är till exempel aktiverat för Azure Application Insights.

Den senaste miljöinställningen som lästes av appen avgör appens miljö. Det går inte att ändra appens miljö när appen körs.

Loggning / Skogsavverkning

Utdata i kommandogränssnittet för en app som körs vid start anger appens miljö. I följande exempel körs appen i mellanlagringsmiljön:

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

Miljövariabler som avgör körningsmiljön

För att fastställa körningsmiljön läser ASP.NET Core från följande miljövariabler:

DOTNET_ENVIRONMENT Om miljövariablerna och ASPNETCORE_ENVIRONMENT inte har angetts är produktionsmiljön standardmiljön.

I Windows och macOS är miljövariabelnamn inte skiftlägeskänsliga. Linux-miljövariabler är skiftlägeskänsliga.

Styr kodkörning beroende på miljö

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

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

    ...
}

I appen IHostEnvironment innehåller allmän information om appens värdmiljö, och IHostEnvironment.EnvironmentName egenskapen anger appens aktuella miljö.

Kontrollera renderat innehåll

Mata IHostEnvironment in i en serverrenderad Razor komponent och använd tjänstens tilläggsmetoder och EnvironmentName -egenskap för att fastställa miljön för rendering av innehåll:

@inject IHostEnvironment Env

@if (Env.IsDevelopment())
{
    <div>The environment is Development.</div>
}

@if (!Env.IsDevelopment())
{
    <div>The environment isn't Development.</div>
}

@if (Env.IsStaging() || Env.EnvironmentName == "Testing")
{
    <div>The environment is either Staging or Testing.</div>
}

För Blazor Web Appkomponenter som kräver att miljön styr klientside-återgivning, se Prerender ASP.NET Core-komponenterRazor.

Ange miljön i ett kommandogränssnitt när appen körs (dotnet run)

Använd alternativet-e|--environment för att ange miljön:

dotnet run -e Staging

Ange miljön med startinställningsfilen (launchSettings.json)

Miljön för lokal utveckling kan anges i Properties\launchSettings.json projektets fil. Miljövärden som anges i launchSettings.json åsidosätter värden som anges av systemmiljön.

Filen launchSettings.json:

• Används endast på den lokala utvecklingsdatorn.
• Distribueras inte när appen publiceras.
• Kan innehålla flera profiler, där var och en konfigurerar en annan miljö.

I följande exempel anges mellanlagringsmiljön för https startprofilen med hjälp av ASPNETCORE_ENVIRONMENT miljövariabeln:

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

I Visual Studio finns det två metoder för att ställa in miljön via startprofiler:

• Tryck på Alt+Retur eller välj Egenskaper när du har högerklickat på projektet i Solution Explorer. Välj Felsök>Allmänt, följt av att du väljer länken Öppna UI för startprofiler för felsökning.

• När projektet har valts i Solution Explorer väljer du {PROJEKTNAMN} Felsökningsinställningar från menyn Felsök, där {PROJECT NAME} platshållaren är ett projektnamn.

Föregående metoder öppnar dialogrutan Starta profiler där du kan redigera miljövariabelinställningarna i launchSettings.json filen. Ändringar som görs i projektprofiler börjar kanske inte gälla förrän webbservern har startats om. Kestrel måste startas om innan den kan identifiera ändringar som gjorts i dess miljö.

Profiler kan väljas i Visual Studio-användargränssnittet bredvid startknappen (►).

När en lösning innehåller flera projekt anger du bara miljön för startprojektet.

Du kan också använda dotnet run kommandot med -lp|--launch-profile alternativet inställt på profilens namn. Den här metoden stöder endast startprofiler baserat på Project kommandot.

dotnet run -lp "https"

När du använder Visual Studio Code med C# Dev Kit för Visual Studio Code (Komma igång med C# i VS Code) hämtas startprofiler från appens launchSettings.json fil.

Om C# Dev Kit inte används anger du ASPNETCORE_ENVIRONMENT miljövariabeln i .vscode/launch.jsonenv avsnittet, tillsammans med andra miljövariabler som anges i avsnittet:

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

Filen .vscode/launch.json används endast av Visual Studio Code.

Ange miljön med en miljövariabel

Det är ofta användbart att ange en specifik miljö för testning med en miljövariabel eller plattformsinställning. Om miljön inte har angetts är den som standard produktionsmiljön, vilket inaktiverar de flesta felsökningsfunktioner. Metoden för att ställa in miljön beror på operativsystemet.

Azure App Service

Appar som distribueras till Azure App Service använder produktionsmiljön som standard.

Information om hur ASPNETCORE_ENVIRONMENT du anger miljövariabeln finns i följande resurser i Azure-dokumentationen:

• Konfigurera en App Service-app
• Konfigurera mellanlagringsmiljöer i Azure App Service

Azure App Service startar automatiskt om appen när en appinställning har lagts till, ändrats eller tagits bort.

Ange miljövariabel för en process

Om du vill ange ASPNETCORE_ENVIRONMENT miljövariabeln för den aktuella sessionen (kommandoskal) när appen startas med dotnet run, använder du följande kommandon. När miljövariabeln har angetts startas appen utan en startprofil med hjälp av --no-launch-profile alternativet .

1. I kommandogränssnittet anger du miljövariabeln med lämplig metod för operativsystemet.

2. dotnet run Kör kommandot utan att använda en startprofil:

   dotnet run --no-launch-profile
   

När du använder PowerShell kan föregående steg kombineras i följande två kommandon. I följande exempel anges Staging-miljön:

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

Ange miljövariabel globalt

Använd lämplig vägledning för operativsystemet för att ange ASPNETCORE_ENVIRONMENT miljövariabeln.

ASPNETCORE_ENVIRONMENT När miljövariabeln har angetts globalt börjar den dotnet run gälla för kommandot i alla kommandogränssnitt som öppnas när värdet har angetts. Miljövärden som anges av startprofiler i den launchSettings.json filen åsidosätter värden som angetts för systemets miljö.

Ange miljön för appar som distribuerats till IIS

För att ange miljövariabeln med ASPNETCORE_ENVIRONMENT-filen, se web.config.

Om du vill ange miljövariabeln för distributionen till IIS inkluderar du <EnvironmentName> egenskapen i publiceringsprofilen (.pubxml) eller projektfilen. I följande exempel anges miljön i web.config till mellanlagringsmiljön när projektet publiceras:

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

Information om hur ASPNETCORE_ENVIRONMENT du anger miljövariabeln för en app som körs i en isolerad programpool (stöds i IIS 10.0 eller senare) finns i Miljövariabler <miljöVariables>. ASPNETCORE_ENVIRONMENT När miljövariabeln har angetts för en programpool åsidosätter dess värde en inställning på systemnivå.

När du är värd för en app i IIS och lägger till eller ändrar ASPNETCORE_ENVIRONMENT miljövariabeln använder du någon av följande metoder för att få det nya värdet att börja gälla för appar som körs:

• Kör net stop was /y följt av net start w3svc i ett kommandogränssnitt.
• Starta om servern.

Docker

Ange appens miljö med någon av metoderna i det här avsnittet.

Använd en Dockerfile

ASPNETCORE_ENVIRONMENT Ange miljövariabeln i Dockerfile med hjälp av instruktionenENV:

ENV ASPNETCORE_ENVIRONMENT=Staging

Använda Docker Compose

För appar med flera tjänster som hanteras med Docker Compose definierar du ASPNETCORE_ENVIRONMENT miljövariabler i docker-compose.yml filen:

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

En miljövariabel vid körning med Docker Compose åsidosätter en miljövariabel som anges av Dockerfile.

docker run Använd kommandot

När du kör Docker-containern med docker run kommandot anger du ASPNETCORE_ENVIRONMENT miljövariabeln med alternativet -e|--env :

docker run -e ASPNETCORE_ENVIRONMENT=Staging aspnet_core_image

En miljö som anges vid körning med docker run åsidosätter en miljö som angetts av Dockerfile.

Docker-miljöfil

ASPNETCORE_ENVIRONMENT Ange miljövariabeln med hjälp av en Docker-miljöfil (.env).

env_variables.env:

ASPNETCORE_ENVIRONMENT=Staging

Läs in filen med alternativet --env-file när kommandot körsdocker run:

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

En miljö som anges vid körning med docker run åsidosätter en miljö som angetts av Dockerfile.

Ange miljön i appens startkod

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

Läsa in konfiguration efter miljö

Information om hur du läser in konfiguration efter miljö finns i Konfiguration i ASP.NET Core.

Få åtkomst till miljön från en Startup klass

Användning av en Startup klass (Startup.cs) med Configure och ConfigureServices metoder krävdes före lanseringen av .NET 6 och stöds fortfarande.

Mata IWebHostEnvironment in i Startup konstruktorn för att styra kodkörningen. Den här metoden är användbar när appen kräver att startkoden konfigureras för endast ett fåtal miljöer med minimala kodskillnader per miljö.

I följande exempel lagras miljön i _env fältet och styr kodkörningen baserat på appens miljö:

public class Startup
{
    private readonly IWebHostEnvironment _env;

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

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else if (_env.IsStaging())
        {
            ...
        }
        else
        {
            ...
        }
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else
        {
            ...
        }

        ...
    }
}

Miljöspecifik Startup klass

En app kan definiera flera Startup klasser för olika miljöer med namngivningskonventionen Startup{EnvironmentName} klass, där {ENVIRONMENT NAME}-platshållaren är miljönamnet.

Klassen vars namnsuffix matchar den aktuella miljön prioriteras. Om en matchande Startup{EnvironmentName}-klass inte hittas, används Startup-klassen.

Om du vill implementera miljöbaserade Startup klasser skapar du så många Startup{EnvironmentName} klasser som behövs och en reservklass Startup :

public class StartupDevelopment
{
    ...
}

public class StartupProduction
{
    ...
}

public class Startup
{
    ...
}

När värdverktyget skapas anropar du HostingAbstractionsWebHostBuilderExtensions.UseStartup, som accepterar ett sammansättningsnamn för att läsa in rätt Startup klass:

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

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

Miljöspecifika Startup klassmetoder

Metoderna Configure och ConfigureServices stöder miljöspecifika versioner av formuläret Configure{ENVIRONMENT NAME} och Configure{ENVIRONMENT NAME}Services, där {ENVIRONMENT NAME} platshållaren är miljönamnet. Om ett matchande miljönamn inte hittas för de namngivna metoderna används ConfigureServices-metoden respektive Configure-metoden.

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

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

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

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

Ytterligare resurser

• Visa eller ladda ned exempelkod (hur du laddar ned)
• Start av applikation i ASP.NET Core
• Konfiguration i ASP.NET Core
• ASP.NET Core Blazor miljöer