Używanie wielu środowisk na platformie ASP.NET Core

Autorzy: Rick Anderson i Kirk Larkin

ASP.NET Core konfiguruje zachowanie aplikacji na podstawie środowiska uruchomieniowego przy użyciu zmiennej środowiskowej.

Środowiska

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

1. DOTNET_ENVIRONMENT
2. ASPNETCORE_ENVIRONMENT gdy metoda jest wywoływana WebApplication.CreateBuilder . Domyślne szablony aplikacji internetowej ASP.NET Core wywołają metodę WebApplication.CreateBuilder. Wartość DOTNET_ENVIRONMENT zastępuje ASPNETCORE_ENVIRONMENT się, gdy WebApplicationBuilder jest używana. W przypadku innych hostów, takich jak ConfigureWebHostDefaults i WebHost.CreateDefaultBuilder, ASPNETCORE_ENVIRONMENT ma wyższy priorytet.

IHostEnvironment.EnvironmentName Można ustawić dowolną wartość, ale następujące wartości są udostępniane przez platformę:

• Development: plik launch Ustawienia.json ustawia wartość ASPNETCORE_ENVIRONMENTDevelopment na maszynie lokalnej.
• Staging
• Production: wartość domyślna, jeśli DOTNET_ENVIRONMENTASPNETCORE_ENVIRONMENT nie została ustawiona.

Następujący kod powoduje:

• Jest podobny do kodu wygenerowanego przez szablony ASP.NET Core.
• Włącza stronę wyjątku dewelopera, gdy ASPNETCORE_ENVIRONMENT jest ustawiona wartość Development. Jest to wykonywane automatycznie przez metodę WebApplication.CreateBuilder .
• Wywołuje UseExceptionHandler metodę , gdy wartość parametru ASPNETCORE_ENVIRONMENT jest inna niż Development.
• IWebHostEnvironment Udostępnia wystąpienie we Environment właściwości WebApplication.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Pomocnik tagów środowiska używa wartości IHostEnvironment.EnvironmentName do uwzględnienia lub wykluczenia znaczników w elemencie :

<environment include="Development">
    <div>Environment is Development</div>
</environment>
<environment exclude="Development">
    <div>Environment is NOT Development</div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>Environment is: Staging, Development or Staging_2</div>
</environment>

Strona Informacje z przykładowego kodu zawiera poprzedni znacznik i wyświetla wartość IWebHostEnvironment.EnvironmentName.

W systemach Windows i macOS zmienne środowiskowe i wartości nie są uwzględniane wielkości liter. Zmienne środowiskowe i wartości systemu Linux są domyślnie uwzględniane wielkości liter.

Tworzenie środowiskPrzykład

Przykładowy kod używany w tym artykule jest oparty na Razor projekcie Pages o nazwie EnvironmentsSample.

Następujące polecenia interfejsu wiersza polecenia platformy .NET tworzą i uruchamiają aplikację internetową o nazwie EnvironmentsSample:

dotnet new webapp -o EnvironmentsSample
cd EnvironmentsSample
dotnet run --verbosity normal

Po uruchomieniu aplikacji zostaną wyświetlone dane wyjściowe podobne do następujących:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7152
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5105
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:\Path\To\EnvironmentsSample

Ustawianie środowiska w wierszu polecenia

Użyj flagi --environment , aby ustawić środowisko. Na przykład:

dotnet run --environment Production

Poprzednie polecenie ustawia środowisko na Production i wyświetla dane wyjściowe podobne do następujących w oknie polecenia:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7262
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5005
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Production
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\Path\To\EnvironmentsSample

Programowanie i uruchamianie Ustawienia.json

Środowisko programistyczne może włączać funkcje, które nie powinny być widoczne w środowisku produkcyjnym. Na przykład szablony projektów ASP.NET Core umożliwiają stronę wyjątku dla deweloperów w środowisku dewelopera. Ze względu na koszt wydajności walidacja zakresu i walidacja zależności odbywa się tylko w programowania.

Środowisko tworzenia maszyn lokalnych można ustawić w pliku Properties\launch Ustawienia.json projektu. Wartości środowiska ustawione w launchSettings.json zastąpieniu wartości ustawionych w środowisku systemowym.

Plik launchSettings.json:

• Jest używany tylko na lokalnym komputerze deweloperskim.
• Nie jest wdrożona.
• Zawiera ustawienia profilu.

Poniżej JSprzedstawiono plik dla projektu internetowego platformy ASP.NET Core o nazwie EnvironmentsSample utworzony za pomocą programu Visual Studio lub dotnet newlaunchSettings.json :

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:59481",
      "sslPort": 44308
    }
  },
  "profiles": {
    "EnvironmentsSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

JSPowyższy element ON zawiera dwa profile:

• EnvironmentsSample: Nazwa profilu to nazwa projektu. Jako pierwszy profil na liście ten profil jest używany domyślnie. Klucz "commandName" ma wartość "Project", dlatego Kestrel serwer internetowy jest uruchamiany.

• IIS Express"commandName": Klucz ma wartość "IISExpress", dlatego IISExpress jest serwerem sieci Web.

Profil uruchamiania można ustawić na projekt lub dowolny inny profil uwzględniony w programie launchSettings.json. Na przykład na poniższej ilustracji wybranie nazwy projektu spowoduje uruchomienie serwera internetowego.Kestrel

Wartość parametru commandName może określać serwer internetowy do uruchomienia. commandName może być jednym z następujących elementów:

• IISExpress : uruchamia program IIS Express.
• IIS : brak uruchomionego serwera internetowego. Oczekuje się, że usługi IIS będą dostępne.
• Project : uruchamia Kestrelprogram .

Właściwości projektu programu Visual Studio 2022 Debugowanie/ Ogólne zawiera link Interfejs użytkownika otwórz profile uruchamiania debugowania. Ten link otwiera okno dialogowe Uruchom profile , które umożliwia edytowanie ustawień zmiennej środowiskowej launchSettings.json w pliku. Możesz również otworzyć okno dialogowe Uruchamianie profilów z menu Debugowanie , wybierając <pozycję Nazwa> projektu Właściwości debugowania. 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.

launchSettings.json Następujący plik zawiera wiele profilów:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:59481",
      "sslPort": 44308
    }
  },
  "profiles": {
    "EnvironmentsSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "EnvironmentsSample-Staging": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
      }
    },
    "EnvironmentsSample-Production": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Profile można wybrać:

• Z poziomu interfejsu użytkownika programu Visual Studio.

• Za pomocą polecenia interfejsu dotnet run wiersza polecenia z opcją --launch-profile ustawioną na nazwę profilu. Takie podejście obsługuje Kestrel tylko profile.

  dotnet run --launch-profile "EnvironmentsSample"
  

Ostrzeżenie

launchSettings.json nie powinien przechowywać wpisów tajnych. Narzędzie Secret Manager może służyć do przechowywania wpisów tajnych na potrzeby programowania lokalnego.

W przypadku korzystania z programu Visual Studio Code zmienne środowiskowe można ustawić w .vscode/launch.json pliku. W poniższym przykładzie ustawiono kilka zmiennych środowiskowych dla wartości konfiguracji hosta:

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

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

Produkcyjne

Środowisko produkcyjne należy skonfigurować tak, aby zmaksymalizować bezpieczeństwo, wydajność i niezawodność aplikacji. Oto niektóre typowe ustawienia, które różnią się od programowania:

• Buforowanie.
• Zasoby po stronie klienta są powiązane, zminimalizowane i potencjalnie obsługiwane z sieci CDN.
• Strony błędów diagnostycznych są wyłączone.
• Włączone przyjazne strony błędów.
• Włączono rejestrowanie produkcyjne i monitorowanie. Na przykład przy użyciu Szczegółowe informacje aplikacji.

Ustawianie środowiska przez ustawienie zmiennej środowiskowej

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

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

Na stronie Informacje z przykładowego kodu jest wyświetlana wartość IWebHostEnvironment.EnvironmentName.

Azure App Service

Production jest wartością domyślną, jeśli DOTNET_ENVIRONMENTASPNETCORE_ENVIRONMENT i nie zostały ustawione. Aplikacje wdrażane na platformie Azure są Production domyślnie.

Aby ustawić środowisko w aplikacji usługi aplikacja systemu Azure Service przy użyciu portalu:

1. Wybierz aplikację na stronie App Services .
2. W grupie Ustawienia wybierz pozycję Konfiguracja.
3. Na karcie Ustawienia aplikacji wybierz pozycję Nowe ustawienie aplikacji.
4. W oknie Dodawanie/edytowanie ustawienia aplikacji podaj ASPNETCORE_ENVIRONMENT nazwę. W polu Wartość podaj środowisko (na przykład Staging).
5. Zaznacz pole wyboru Ustawienie miejsca wdrożenia, jeśli chcesz, aby ustawienie środowiska pozostało z bieżącym miejscem podczas zamiany miejsc wdrożenia. Aby uzyskać więcej informacji, zobacz Konfigurowanie środowisk przejściowych w usłudze aplikacja systemu Azure Service w dokumentacji platformy Azure.
6. Wybierz przycisk OK , aby zamknąć okno dialogowe Dodawanie/Edytowanie ustawienia aplikacji.
7. Wybierz pozycję Zapisz w górnej części strony Konfiguracja .

usługa aplikacja systemu Azure automatycznie uruchamia ponownie aplikację po dodaniu, zmianie lub usunięciu ustawienia aplikacji w witrynie Azure Portal.

Windows — ustawianie zmiennej środowiskowej dla procesu

Wartości środowiska w launchSettings.json zastąpieniu wartości ustawionych w środowisku systemowym.

Aby ustawić ASPNETCORE_ENVIRONMENT element dla bieżącej sesji, gdy aplikacja jest uruchamiana przy użyciu polecenia dotnet run, użyj następujących poleceń w wierszu polecenia lub w programie PowerShell:

set ASPNETCORE_ENVIRONMENT=Staging
dotnet run --no-launch-profile

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

Windows — globalne ustawianie zmiennej środowiskowej

Powyższe polecenia są ustawiane ASPNETCORE_ENVIRONMENT tylko dla procesów uruchomionych w tym oknie polecenia.

Aby ustawić wartość globalnie w systemie Windows, użyj jednej z następujących metod:

• Otwórz Panel sterowania> Ustawienia> systemu zaawansowanego systemu i dodaj lub edytuj ASPNETCORE_ENVIRONMENT wartość:

  

  

• Otwórz wiersz polecenia administracyjnego i użyj setx polecenia lub otwórz administracyjny wiersz polecenia programu PowerShell i użyj polecenia [Environment]::SetEnvironmentVariable:

  • setx ASPNETCORE_ENVIRONMENT Staging /M
    

    Przełącznik /M ustawia zmienną środowiskową na poziomie systemu. /M Jeśli przełącznik nie jest używany, zmienna środowiskowa jest ustawiana dla konta użytkownika.

  • [Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Staging", "Machine")
    

    Opcja Machine ustawia zmienną środowiskową na poziomie systemu. Jeśli wartość opcji zostanie zmieniona na User, zmienna środowiskowa zostanie ustawiona dla konta użytkownika.

Gdy zmienna ASPNETCORE_ENVIRONMENT środowiskowa jest ustawiana globalnie, ma ona zastosowanie dotnet run w dowolnym oknie polecenia otwartym po ustawieniu wartości. Wartości środowiska w launchSettings.json zastąpieniu wartości ustawionych w środowisku systemowym.

Windows — korzystanie z pliku web.config

Aby ustawić zmienną środowiskową za pomocą web.configpolecenia , zobacz sekcję ASPNETCORE_ENVIRONMENT Ustawianie zmiennych środowiskowych pliku web.config.

Windows — wdrożenia usług IIS

Uwzględnij <EnvironmentName> właściwość w profilu publikowania (.pubxml) lub pliku projektu. To podejście ustawia środowisko w pliku web.config po opublikowaniu projektu:

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

Aby ustawić ASPNETCORE_ENVIRONMENT zmienną środowiskową dla aplikacji uruchomionej w izolowanej puli aplikacji (obsługiwanej w usługach IIS 10.0 lub nowszej), zobacz sekcję AppCmd.exe polecenia zmienne <środowiskoweVariables>. Gdy zmienna ASPNETCORE_ENVIRONMENT środowiskowa jest ustawiana dla puli aplikacji, jej wartość zastępuje ustawienie na poziomie systemu.

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

• Wykonaj net stop was /y polecenie, a następnie net start w3svc z wiersza polecenia.
• Uruchom ponownie serwer.

macOS

Ustawienie bieżącego środowiska dla systemu macOS można wykonać w wierszu podczas uruchamiania aplikacji:

ASPNETCORE_ENVIRONMENT=Staging dotnet run

Możesz też ustawić środowisko export przed uruchomieniem aplikacji:

export ASPNETCORE_ENVIRONMENT=Staging

Zmienne środowiskowe na poziomie maszyny są ustawiane w pliku bashrc lub .bash_profile . Edytuj plik przy użyciu dowolnego edytora tekstów. Dodaj następującą instrukcję:

export ASPNETCORE_ENVIRONMENT=Staging

Linux

W przypadku dystrybucji systemu Linux użyj export polecenia w wierszu polecenia dla ustawień zmiennych opartych na sesji i pliku bash_profile dla ustawień środowiska na poziomie komputera.

Ustawianie środowiska w kodzie

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
}); 

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Konfiguracja według środowiska

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

Konfigurowanie usług i oprogramowania pośredniczącego 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. Szablon projektu zawiera przykład kodu, który dodaje oprogramowanie pośredniczące tylko wtedy, gdy bieżące środowisko nie jest programowaniem:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Wyróżniony kod sprawdza bieżące środowisko podczas kompilowania potoku żądania. Aby sprawdzić bieżące środowisko podczas konfigurowania usług, użyj polecenia builder.Environment zamiast app.Environment.

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