środowiska uruchomieniowe ASP.NET Core

ASP.NET Core konfiguruje zachowanie aplikacji na podstawie środowiska uruchomieniowego, co zwykle odzwierciedla miejsce działania aplikacji.

Aplikacje są zwykle uruchamiane w środowisku deweloperskim podczas lokalnego programowania i testowania na maszynie dewelopera z jednym zestawem skonfigurowanych zachowań. Z kolei działają one w środowisku produkcyjnym po wdrożeniu na serwerze z innym zestawem skonfigurowanych zachowań. Można użyć dowolnej liczby dodatkowych środowisk, takich jak środowisko przejściowe udostępniane przez platformę do przemieszczania aplikacji przed wdrożeniem na żywo lub innymi środowiskami tworzonymi przez deweloperów.

W tym artykule opisano środowiska uruchomieniowe aplikacji, sposób używania środowiska do kontrolowania zachowania aplikacji oraz sposobu ustawiania środowiska.

Aby uzyskać Blazor wskazówki dotyczące środowisk, które dodaje lub zastępuje wskazówki zawarte w tym artykule, zobacz ASP.NET Środowiska podstawoweBlazor.

Environments

Chociaż środowisko może być dowolną wartością ciągu, następujące wartości środowiska są udostępniane przez platformę:

• Development
• Staging
• Production

Środowisko produkcyjne jest skonfigurowane w celu zmaksymalizowania bezpieczeństwa, wydajności i niezawodności aplikacji. Typowe ustawienia i konfiguracja dewelopera, które różnią się od środowiska programistycznego, obejmują:

• Włączanie buforowania.
• Łączenie i minimalizowanie zasobów po stronie klienta oraz ich potencjalne serwowanie z sieci CDN.
• Wyłączanie stron błędów diagnostycznych i włączanie przyjaznych stron błędów.
• Włączanie rejestrowania i monitorowania produkcji. Na przykład rejestrowanie jest włączone dla usługi Azure Application Insights.

Ostatnie ustawienie środowiska odczytane przez aplikację określa środowisko aplikacji. Nie można zmienić środowiska aplikacji, gdy aplikacja jest uruchomiona.

Przemysł drzewny

Dane wyjściowe w powłoce poleceń uruchomionej aplikacji podczas uruchamiania wskazują środowisko aplikacji. W poniższym przykładzie aplikacja jest uruchomiona w środowisku przejściowym:

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

Zmienne środowiskowe określające środowisko uruchomieniowe

Aby określić środowisko uruchomieniowe, ASP.NET Core odczytuje z następujących zmiennych środowiskowych:

• DOTNET_ENVIRONMENT
• ASPNETCORE_ENVIRONMENT

W przypadku używania WebApplication, wartość DOTNET_ENVIRONMENT ma pierwszeństwo przed ASPNETCORE_ENVIRONMENT. W przypadku korzystania z WebHost pierwszeństwo ma ASPNETCORE_ENVIRONMENT.

DOTNET_ENVIRONMENT Jeśli zmienne środowiskowe i ASPNETCORE_ENVIRONMENT nie są ustawione, środowisko produkcyjne jest środowiskiem domyślnym.

W systemach Windows i macOS nazwy zmiennych środowiskowych nie są rozróżniane ze względu na wielkość liter. Zmienne środowiskowe Linux są wrażliwe na wielkość liter.

Kontrolowanie wykonywania kodu według środowiska

Użyj WebApplicationBuilder.Environment lub WebApplication.Environment warunkowo dodaj usługi lub oprogramowanie pośredniczące w zależności od bieżącego środowiska.

Następujący kod w pliku aplikacji Program :

• Używa WebApplication.Environment do odróżnienia środowiska.
• Wywołuje UseExceptionHandler, która dodaje oprogramowanie pośredniczące do obsługi wyjątków do potoku przetwarzania żądań w celu obsługi wyjątków.
• Wywołuje metodę UseHsts, która dodaje oprogramowanie pośredniczące HSTS w celu zastosowania nagłówkaStrict-Transport-Security.

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

Powyższy przykład sprawdza bieżące środowisko dla potoku przetwarzania żądań. Aby sprawdzić bieżące środowisko podczas konfigurowania usług, użyj polecenia builder.Environment zamiast app.Environment.

W aplikacji IHostEnvironment znajdują się ogólne informacje o środowisku hostingu aplikacji, a IHostEnvironment.EnvironmentName właściwość wskazuje bieżące środowisko aplikacji.

Kontrolka zawartości renderowanej

Wstrzyknij IHostEnvironment do składnika Razor renderowanego przez serwer i użyj metod rozszerzenia usługi oraz właściwości EnvironmentName w celu określenia środowiska renderowania zawartości.

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

Aby uzyskać informacje o Blazor Web Appśrodowiskach wymagających kontrolowania renderowania po stronie klienta, zobacz Prerender ASP.NET Core components (Składniki prerender ASP.NET CoreRazor).

Ustawianie środowiska w powłoce poleceń w trakcie uruchamiania aplikacji (dotnet run)

-e|--environment Użyj opcji , aby ustawić środowisko:

dotnet run -e Staging

Ustawianie środowiska przy użyciu pliku ustawień uruchamiania (launchSettings.json)

Środowisko programowania lokalnego można ustawić w Properties\launchSettings.json pliku projektu. Wartości środowiska ustawione w launchSettings.json zastępują wartości ustawione przez środowisko systemowe.

Plik launchSettings.json:

• Jest używany tylko na lokalnym komputerze deweloperskim.
• Nie jest wdrażana po opublikowaniu aplikacji.
• Może zawierać wiele profilów, z których każdy konfiguruje inne środowisko.

W przykładzie poniżej skonfigurowano środowisko przejściowe dla profilu uruchamiania https przy użyciu zmiennej środowiskowej ASPNETCORE_ENVIRONMENT.

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

W programie Visual Studio istnieją dwa podejścia do ustawiania środowiska za pośrednictwem profilów uruchamiania:

• Naciśnij Alt+Enter lub wybierz polecenie Właściwości po kliknięciu prawym przyciskiem myszy projektu w Eksploratorze rozwiązań. Wybierz pozycję Debuguj>Ogólne, a następnie wybierz link Otwórz interfejs profili uruchamiania debugowania.

• Po wybraniu projektu w Eksploratorze rozwiązań wybierz pozycję {NAZWA PROJEKTU} Właściwości debugowania z menu Debugowanie , gdzie {PROJECT NAME} symbol zastępczy jest nazwą projektu.

Powyższe podejścia otwierają okno dialogowe Uruchamianie profilów , w którym można edytować ustawienia zmiennej środowiskowej launchSettings.json w pliku. Zmiany wprowadzone w profilach projektów mogą nie obowiązywać do momentu ponownego uruchomienia serwera internetowego. Kestrel należy uruchomić ponownie przed wykryciem zmian wprowadzonych w jego środowisku.

Profile można wybrać w interfejsie użytkownika programu Visual Studio obok przycisku Uruchom (►).

Tylko dla projektu startowego należy ustawić środowisko, jeśli rozwiązanie zawiera wiele projektów.

Alternatywnie, użyj polecenia dotnet run z opcją -lp|--launch-profile ustawioną na nazwę profilu. Takie podejście obsługuje tylko profile uruchamiania oparte na poleceniu Project.

dotnet run -lp "https"

W przypadku korzystania z programu Visual Studio Code z zestawem C# Dev Kit dla programu Visual Studio Code (Wprowadzenie do języka C# w programie VS Code) profile uruchamiania launchSettings.json są pobierane z pliku aplikacji.

Jeśli zestaw deweloperski języka C# nie jest używany, ustaw zmienną środowiskową ASPNETCORE_ENVIRONMENT w sekcji .vscode/launch.json, wraz z innymi zmiennymi środowiskowymi ustawionymi w sekcji env:

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

Plik .vscode/launch.json jest używany tylko przez program Visual Studio Code.

Ustawianie środowiska za pomocą zmiennej środowiskowej

Często warto ustawić określone środowisko do testowania za pomocą zmiennej środowiskowej lub ustawienia platformy. Jeśli środowisko nie jest ustawione, domyślnie jest to środowisko produkcyjne, które wyłącza większość funkcji debugowania. Metoda ustawiania środowiska zależy od systemu operacyjnego.

Azure App Service

Aplikacje wdrożone w usłudze Azure App Service domyślnie przyjmują środowisko produkcyjne.

Aby ustawić zmienną ASPNETCORE_ENVIRONMENT środowiskową, zobacz następujące zasoby w dokumentacji platformy Azure:

• Konfigurowanie aplikacji usługi App Service
• Konfigurowanie środowisk przejściowych w usłudze Azure App Service

Usługa Azure App Service automatycznie uruchamia ponownie aplikację po dodaniu, zmianie lub usunięciu ustawienia aplikacji.

Ustawianie zmiennej środowiskowej dla procesu

Aby ustawić zmienną ASPNETCORE_ENVIRONMENT środowiskową dla bieżącej sesji (powłoki poleceń), gdy aplikacja jest uruchamiana przy użyciu dotnet runpolecenia , użyj następujących poleceń. Po ustawieniu zmiennej środowiskowej aplikacja jest uruchamiana bez użycia profilu uruchamiania, przy użyciu opcji --no-launch-profile.

1. W powłoce poleceń ustaw zmienną środowiskową przy użyciu optymalnej metody właściwej dla twojego systemu operacyjnego.

2. dotnet run Wykonaj polecenie bez użycia profilu uruchamiania:

   dotnet run --no-launch-profile
   

W przypadku korzystania z programu PowerShell powyższe kroki można połączyć w następujących dwóch poleceniach. Poniższy przykład ustawia środowisko testowe.

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

Globalne ustawianie zmiennej środowiskowej

Użyj odpowiednich wskazówek dla systemu operacyjnego, aby ustawić zmienną ASPNETCORE_ENVIRONMENT środowiskową.

Gdy zmienna ASPNETCORE_ENVIRONMENT środowiskowa jest ustawiana globalnie, ma ona wpływ na dotnet run polecenie w dowolnej powłoce poleceń otwieranej po ustawieniu wartości. Wartości środowiska ustawiane przez profile uruchamiania w launchSettings.json pliku zastępują wartości ustawione dla środowiska systemowego.

Ustawianie środowiska dla aplikacji wdrożonych w usługach IIS

Aby ustawić zmienną ASPNETCORE_ENVIRONMENT środowiskową z plikiem web.config, zobacz plik web.config.

Aby ustawić zmienną środowiskową podczas wdrażania dla usług IIS, uwzględnij <EnvironmentName> właściwość w profilu publikowania (.pubxml) lub pliku projektu. Poniższy przykład ustawia środowisko w web.config na środowisko Staging podczas publikacji projektu.

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

Aby ustawić zmienną ASPNETCORE_ENVIRONMENT środowiskową dla aplikacji uruchomionej w izolowanej puli aplikacji (obsługiwanej w usługach IIS 10.0 lub nowszych), zobacz Zmienne środowiskowe<>. Gdy zmienna ASPNETCORE_ENVIRONMENT środowiskowa jest ustawiona dla puli aplikacji, jej wartość zastępuje ustawienie na poziomie systemu.

W przypadku hostowania aplikacji w usługach IIS i dodawania lub zmieniania ASPNETCORE_ENVIRONMENT zmiennej środowiskowej użyj jednej z następujących metod, aby nowa wartość miała zastosowanie w przypadku uruchamiania aplikacji:

• Wykonaj net stop was /y, a następnie net start w3svc w powłoce poleceń.
• Uruchom ponownie serwer.

Docker

Ustaw środowisko aplikacji przy użyciu dowolnego podejścia w tej sekcji.

Korzystanie z pliku Dockerfile

Ustaw zmienną ASPNETCORE_ENVIRONMENT środowiskową w pliku Dockerfile przy użyciu instrukcji ENV :

ENV ASPNETCORE_ENVIRONMENT=Staging

Korzystanie z narzędzia Docker Compose

W przypadku aplikacji wieloserwisowych zarządzanych za pomocą narzędzia Docker Compose zdefiniuj zmienne środowiskowe w pliku ASPNETCORE_ENVIRONMENTdocker-compose.yml.

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

Środowisko ustawione w czasie wykonywania za pomocą narzędzia Docker Compose zastępuje środowisko ustawione przez plik Dockerfile.

Użyj polecenia docker run

Podczas uruchamiania kontenera Docker za docker run pomocą polecenia ustaw ASPNETCORE_ENVIRONMENT zmienną środowiskową przy użyciu opcji -e|--env:

docker run -e ASPNETCORE_ENVIRONMENT=Staging aspnet_core_image

Środowisko ustawione w czasie wykonywania za pomocą docker run zastępuje środowisko ustawione w pliku Dockerfile.

Plik środowiska platformy Docker

Ustaw zmienną ASPNETCORE_ENVIRONMENT środowiskową przy użyciu pliku środowiska platformy Docker (.env).

env_variables.env:

ASPNETCORE_ENVIRONMENT=Staging

Załaduj plik z --env-file opcją w trakcie wykonywania docker run polecenia:

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

Środowisko ustawione w czasie wykonywania za pomocą docker run zastępuje środowisko ustawione w pliku Dockerfile.

Ustawianie środowiska w kodzie uruchamiania aplikacji

Aby ustawić środowisko w kodzie, użyj polecenia WebApplicationOptions.EnvironmentName podczas tworzenia WebApplicationBuilderelementu , jak pokazano w poniższym przykładzie:

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

Ładowanie konfiguracji według środowiska

Aby załadować konfigurację według środowiska, zobacz Konfiguracja w programie ASP.NET Core.

Uzyskiwanie dostępu do środowiska z Startup klasy

Użycie klasy Startup z metodami Startup.cs i Configure było wymagane przed wydaniem platformy .NET 6 i pozostaje obsługiwane.

Wstrzyknij IWebHostEnvironment do konstruktora Startup w celu sterowania wykonywaniem kodu. Takie podejście jest przydatne, gdy aplikacja wymaga skonfigurowania kodu uruchamiania tylko dla kilku środowisk z minimalnymi różnicami kodu na środowisko.

W poniższym przykładzie środowisko jest przechowywane w _env polu i kontroluje wykonywanie kodu w oparciu o środowisko aplikacji:

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

        ...
    }
}

Klasa specyficzna dla Startup środowiska

Aplikacja może definiować wiele Startup klas dla różnych środowisk zgodnie z konwencją nazewnictwa Startup{EnvironmentName} klasy, gdzie {ENVIRONMENT NAME} jest nazwą środowiska.

Klasa, której sufiks nazwy pasuje do bieżącego środowiska, ma priorytet. Jeśli nie można odnaleźć pasującej Startup{EnvironmentName} klasy, zostanie użyta Startup klasa.

Aby zaimplementować klasy oparte na Startup środowisku, utwórz dowolną liczbę Startup{EnvironmentName} klas zgodnie z potrzebami i rezerwową klasę Startup :

public class StartupDevelopment
{
    ...
}

public class StartupProduction
{
    ...
}

public class Startup
{
    ...
}

Tam, gdzie tworzony jest konstruktor hosta, wywołaj metodę HostingAbstractionsWebHostBuilderExtensions.UseStartup, która akceptuje nazwę zestawu, aby załadować właściwą Startup klasę.

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

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

Metody klasy specyficzne dla Startup środowiska

Metody Configure i ConfigureServices obsługują wersje formularza Configure{ENVIRONMENT NAME} specyficzne dla środowiska oraz Configure{ENVIRONMENT NAME}Services, gdzie {ENVIRONMENT NAME} symbol zastępczy jest nazwą środowiska. Jeśli nie można odnaleźć pasującej nazwy środowiska dla nazwanych metod, zostanie użyta metoda ConfigureServices lub Configure.

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

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

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

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

Dodatkowe zasoby

• Wyświetl lub pobierz przykładowy kod (jak pobrać)
• Uruchamianie aplikacji na platformie ASP.NET Core
• Konfiguracja w programie ASP.NET Core
• Środowiska platformy ASP.NET Core Blazor