ASP.NET Core futtatókörnyezetek

ASP.NET Core az alkalmazás viselkedését a futtatókörnyezet alapján konfigurálja, amely általában azt tükrözi, hogy hol fut az alkalmazás.

Az alkalmazások általában a fejlesztői környezetben futnak a helyi fejlesztés és tesztelés során egy fejlesztő gépén egy konfigurált viselkedéskészlettel. Ezzel szemben a termelési környezetben futnak, amikor egy más konfigurált viselkedési csoporttal rendelkező kiszolgálóra vannak telepítve. Bármilyen számú további környezet használható, például a keretrendszer által az alkalmazások élő üzembe helyezés előtti előkészítéshez biztosított átmeneti környezete vagy a fejlesztők által létrehozott egyéb környezetek.

Ez a cikk az alkalmazás futtatókörnyezeteit, az alkalmazás viselkedésének szabályozását és a környezet beállítását ismerteti.

A jelen cikkben szereplő útmutatást kiegészítő vagy felülíró környezetekkel kapcsolatos Blazor útmutatásért tekintse meg ASP.NET Core-környezeteketBlazor.

Environments

Bár a környezet bármilyen sztringérték lehet, a keretrendszer a következő környezeti értékeket biztosítja:

• Development
• Staging
• Production

A production környezet úgy van konfigurálva, hogy maximalizálja a biztonságot, a teljesítményt és az alkalmazás megbízhatóságát. A fejlesztői környezettől eltérő gyakori fejlesztői beállítások és konfigurációk a következők:

• A gyorsítótárazás engedélyezése.
• Ügyféloldali erőforrások összekapcsolása és minifyingje, valamint potenciálisan a CDN-ből való kiszolgálásuk.
• A diagnosztikai hibalapok letiltása és a barátságos hibalapok engedélyezése.
• A termelési naplózás és figyelés engedélyezése. A naplózás például engedélyezve van az Azure Application Insightsban.

Az alkalmazás által beolvasott utolsó környezeti beállítás határozza meg az alkalmazás környezetét. Az alkalmazás környezete nem módosítható, amíg az alkalmazás fut.

Logging

Az indításkor futó alkalmazás parancshéjában megjelenő kimenet az alkalmazás környezetét jelzi. Az alábbi példában az alkalmazás az előkészítési környezetben fut:

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

A futtatókörnyezetet meghatározó környezeti változók

A futtatókörnyezet meghatározásához ASP.NET Core a következő környezeti változókból olvas be:

• DOTNET_ENVIRONMENT
• ASPNETCORE_ENVIRONMENT

Használata WebApplication esetén az DOTNET_ENVIRONMENT érték elsőbbséget élvez ASPNETCORE_ENVIRONMENT-tel szemben. A WebHost használata esetén a ASPNETCORE_ENVIRONMENT élvez elsőbbséget.

Ha a DOTNET_ENVIRONMENT és ASPNETCORE_ENVIRONMENT környezeti változók nincsenek beállítva, akkor az éles környezet az alapértelmezett környezet.

Windows és macOS rendszeren a környezeti változók neve nem megkülönbözteti a kis- és nagybetűket. A Linux környezeti változói megkülönböztetik a kis- és nagybetűket.

Kódvégrehajtás szabályozása környezet szerint

Az WebApplicationBuilder.Environment vagy WebApplication.Environment használatával feltételesen hozzáadhat szolgáltatásokat vagy köztes szoftvereket a környezettől függően.

Az alkalmazás fájljában Program található következő kód:

• A környezet megkülönböztetésére használ WebApplication.Environment .
• Hívások UseExceptionHandler, amelyek kivételkezelés céljából hozzáadják a Exception Handler Middleware-t a kérelemfeldolgozó folyamathoz.
• Meghívja , amely hozzáadja a HSTS Middleware-t a fejléc alkalmazásához.

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

Az előző példa a kérésfeldolgozási folyamat aktuális környezetét ellenőrzi. Ha szeretné ellenőrizni az aktuális környezetet a szolgáltatások konfigurálása közben, használja a builder.Environment helyett a app.Environment-et.

Az alkalmazásban az IHostEnvironment alkalmazás üzemeltetési környezetével kapcsolatos általános információk találhatók, a IHostEnvironment.EnvironmentName tulajdonság pedig az alkalmazás aktuális környezetét jelzi.

Renderelt tartalom szabályozása

Injektáljon IHostEnvironment egy kiszolgáló által renderelt Razor összetevőbe, és használja a szolgáltatás bővítménymódszereit és EnvironmentName tulajdonságát a tartalom renderelési környezetének meghatározásához:

@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>
}

Azokban az esetekben, amikor Blazor Web App környezetre van szükség az ügyféloldali renderelés vezérlésére, lásd: Prerender ASP.NET Core-összetevőkRazor.

A környezet beállítása parancshéjban az alkalmazás futtatásakor (dotnet run)

A környezet beállításához használja a -e|--environment következőt :

dotnet run -e Staging

A környezet beállítása az indítási beállításfájllal (launchSettings.json)

A helyi fejlesztés környezete a Properties\launchSettings.json projekt fájljában állítható be. Az launchSettings.json-ban beállított környezeti értékek felülírják a rendszerkörnyezet által beállított értékeket.

A launchSettings.json fájl:

• Csak a helyi fejlesztőgépen használható.
• Az alkalmazás közzétételekor nincs üzembe helyezve.
• Több profilt is tartalmazhat, amelyek mindegyike egy másik környezetet konfigurál.

Az alábbi példa az indítási profil átmeneti környezetét https állítja be a ASPNETCORE_ENVIRONMENT környezeti változó használatával:

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

A Visual Studióban kétféleképpen állíthatja be a környezetet indítási profilokkal:

• Nyomja le az Alt+Enter billentyűt , vagy válassza a Tulajdonságok lehetőséget , miután a jobb gombbal a projektre kattintott a Megoldáskezelőben. Válassza a Hibakeresés>Általános, majd a A hibakeresés indítási profiljainak megnyitása felhasználói felület hivatkozást.

• Ha a projekt ki van jelölve a Megoldáskezelőben, válassza a {PROJECT NAME} Hibakeresési tulajdonságok lehetőséget a Hibakeresés menüben, ahol a {PROJECT NAME} helyőrző egy projektnév.

Az előző megközelítések megnyitják a Profilok indítása párbeszédpanelt, ahol szerkesztheti a környezeti változó beállításait a launchSettings.json fájlban. Előfordulhat, hogy a projektprofilok módosításai csak a webkiszolgáló újraindítása után lépnek érvénybe. Kestrel újra kell indítani, mielőtt észlelni tudja a környezetében végrehajtott módosításokat.

A profilok a Start gomb (►) melletti Visual Studio felhasználói felületén választhatók ki.

Ha egy megoldás több projektet tartalmaz, csak az indítási projekt környezetét állítsa be.

Másik lehetőségként használja a dotnet run parancsot a -lp|--launch-profile opció beállításával a profil nevére. Ez a megközelítés csak a parancs alapján támogatja az indítási Project profilokat.

dotnet run -lp "https"

Ha a Visual Studio Code-ot a Visual Studio Code C# fejlesztői készletével használja (a C# használatának első lépései a VS Code-ban), a rendszer az indítási profilokat az alkalmazás fájljából launchSettings.json veszi fel.

Ha a C# Dev Kit nincs használatban, állítsa be a ASPNETCORE_ENVIRONMENT környezeti változót a .vscode/launch.jsonenv szakaszban, a szakaszban beállított többi környezeti változóval együtt:

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

A .vscode/launch.json fájlt csak a Visual Studio Code használja.

Környezet beállítása környezeti változóval

Gyakran hasznos egy adott környezet beállítása környezeti változóval vagy platformbeállítással való teszteléshez. Ha a környezet nincs beállítva, alapértelmezés szerint a termelési környezet lesz, amely letiltja a legtöbb hibakeresési funkciót. A környezet beállításának módja az operációs rendszertől függ.

Azure App Service

Az Azure App Service-ben üzembe helyezett alkalmazások alapértelmezés szerint a Production környezetet használják.

A környezeti változó beállításához ASPNETCORE_ENVIRONMENT tekintse meg a következő erőforrásokat az Azure dokumentációjában:

• App Service-alkalmazás konfigurálása
• Átmeneti környezetek beállítása az Azure App Service-ben

Az Azure App Service automatikusan újraindítja az alkalmazást egy alkalmazásbeállítás hozzáadása, módosítása vagy törlése után.

Környezeti változó beállítása folyamathoz

Az alábbi parancsokat használja a ASPNETCORE_ENVIRONMENT parancshéjjal indított alkalmazás aktuális munkamenetére vonatkozó dotnet run környezeti változó beállításához. A környezeti változó beállítása után az alkalmazás indítási profil nélkül indul el a --no-launch-profile beállítás használatával.

1. A parancshéjban állítsa be a környezeti változót az operációs rendszer megfelelő megközelítésével.

2. Indítsa el a dotnet run parancsot indítási profil használata nélkül:

   dotnet run --no-launch-profile
   

A PowerShell használatakor a fenti lépések az alábbi két parancsban kombinálhatók. Az alábbi példa az előkészítési környezetet állítja be:

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

Környezeti változó globális beállítása

A környezeti változó beállításához használja az operációs rendszer megfelelő útmutatóját ASPNETCORE_ENVIRONMENT .

Ha a ASPNETCORE_ENVIRONMENT környezeti változó globálisan van beállítva, az a parancs az érték beállítása után megnyitott bármely parancshéjban érvénybe lép. Az indítási profilok által a fájlban beállított környezeti értékek felülírják a rendszerkörnyezet számára beállított értékeket.

Az IIS-ben üzembe helyezett alkalmazások környezetének beállítása

A környezeti változó fájllal való beállításához ASPNETCORE_ENVIRONMENTweb.config lásd web.config fájlt.

Ha az üzembe helyezés környezeti változóját IIS-re szeretné állítani, adja meg a <EnvironmentName> tulajdonságot a közzétételi profilban (.pubxml) vagy a projektfájlban. A következő példa beállítja web.config környezetet az Átmeneti környezetre, amikor a projekt közzétételre kerül.

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

Az elkülönített alkalmazáskészletben futó alkalmazás környezeti változójának beállításához (IIS 10.0-s vagy újabb verziókban támogatott) tekintse meg a ASPNETCORE_ENVIRONMENTkörnyezeti változókat<>. Ha a ASPNETCORE_ENVIRONMENT környezeti változó egy alkalmazáskészlethez van beállítva, az értéke felülír egy rendszerszintű beállítást.

Amikor egy alkalmazást üzemeltet az IIS-ben, és hozzáadja vagy módosítja a ASPNETCORE_ENVIRONMENT környezeti változót, az alábbi módszerek egyikével érvénybe lép az új érték az alkalmazások futtatásához:

• Hajtsa végre net stop was /y, közvetlenül utána net start w3svc a parancssorban.
• Indítsa újra a kiszolgálót.

Kikötőmunkás

Állítsa be az alkalmazás környezetét az ebben a szakaszban ismertetett módszerek bármelyikével.

Dockerfile használata

Állítsa be a ASPNETCORE_ENVIRONMENT környezeti változót a Dockerfile-on belül az ENV utasítással:

ENV ASPNETCORE_ENVIRONMENT=Staging

A Docker Compose használata

A Docker Compose-nal felügyelt többszolgáltatásos alkalmazásokhoz definiáljon ASPNETCORE_ENVIRONMENT környezeti változókat a fájlon docker-compose.yml belül:

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

A Futtatókörnyezetben a Docker Compose használatával beállított környezet felülírja a Dockerfile által beállított környezetet.

docker run A parancs használata

Ha a Docker-tárolót a docker run paranccsal futtatja, állítsa be a ASPNETCORE_ENVIRONMENT környezeti változót a -e|--env következő beállítással:

docker run -e ASPNETCORE_ENVIRONMENT=Staging aspnet_core_image

Futásidőben docker run beállított környezet felülbírálja a Dockerfile által beállított környezetet.

Docker-környezetfájl

Állítsa be a ASPNETCORE_ENVIRONMENT környezeti változót egy Docker-környezeti fájl (.env) használatával.

env_variables.env:

ASPNETCORE_ENVIRONMENT=Staging

A fájlt a --env-file opcióval töltse be a docker run parancs végrehajtásakor:

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

Futásidőben docker run beállított környezet felülbírálja a Dockerfile által beállított környezetet.

A környezet beállítása az alkalmazás indítási kódjában

A környezet kódban való beállításához használja a WebApplicationOptions.EnvironmentName létrehozásakor a WebApplicationBuilder-t, ahogyan az alábbi példában látható.

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

Konfiguráció betöltése környezet szerint

A konfiguráció környezet szerinti betöltéséhez lásd: Konfiguráció a ASP.NET Core-ban.

Hozzáférés a környezethez egy Startup osztályból

A .NET 6 kiadása előtt szükséges volt a Startup osztály (Startup.cs) Configure és a ConfigureServices metódusok használata, és most is támogatott.

Injektálja a IWebHostEnvironment-t a Startup konstruktorba a kódvégrehajtás szabályozása érdekében. Ez a módszer akkor hasznos, ha az alkalmazás csak néhány környezethez igényel indítási kódot, és környezetenként minimális kódeltérések vannak.

Az alábbi példában _env a környezet a mezőben van tárolva, és az alkalmazás környezete alapján szabályozza a kód végrehajtását:

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
        {
            ...
        }

        ...
    }
}

Környezetspecifikus Startup osztály

Egy alkalmazás több Startup osztályt is definiálhat különböző környezetekhez az elnevezési konvenciók Startup{EnvironmentName} osztályával, ahol a {ENVIRONMENT NAME} helyőrző a környezet neve.

Az osztály, amelynek neve utótagja megegyezik az aktuális környezettel, rangsorolásra kerül. Ha nem található egyező Startup{EnvironmentName} osztály, a rendszer az osztályt Startup használja.

A környezetalapú Startup osztályok implementálásához hozzon létre annyi Startup{EnvironmentName} osztályt, amennyi szükséges, és hozzon létre egy tartalék Startup osztályt:

public class StartupDevelopment
{
    ...
}

public class StartupProduction
{
    ...
}

public class Startup
{
    ...
}

Amikor a host builder létrejön, hívja meg a HostingAbstractionsWebHostBuilderExtensions.UseStartup metódust, amely egy szerelvény nevet fogad a megfelelő Startup osztály betöltéséhez:

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

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

Környezetspecifikus Startup osztálymódszerek

A Configure és ConfigureServices metódusok támogatják az Configure{ENVIRONMENT NAME} és Configure{ENVIRONMENT NAME}Services űrlapok környezetspecifikus verzióit, ahol a {ENVIRONMENT NAME} helyőrző a környezet neve. Ha nem található egyező környezetnév az elnevezett metódusokhoz, akkor a rendszer az vagy ConfigureServices a Configure metódust használja.

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

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

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

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

További erőforrások

• Mintakód megtekintése vagy letöltése (hogyan töltsd le)
• alkalmazás indítása a ASP.NET Core
• Az ASP.NET Core konfigurációja
• ASP.NET Core Blazor-környezetek