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

Artykuł
04/11/2023

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:

DOTNET_ENVIRONMENT
ASPNETCORE_ENVIRONMENT gdy metoda jest wywoływana WebApplication.CreateBuilder . Domyślne szablony aplikacji internetowej ASP.NET Core wywołają metodę WebApplication.CreateBuilder. Wartość ASPNETCORE_ENVIRONMENT zastępuje DOTNET_ENVIRONMENTwartość .

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

DOTNET_ENVIRONMENT
ASPNETCORE_ENVIRONMENT gdy metoda jest wywoływana WebApplication.CreateBuilder . Domyślne szablony aplikacji internetowej ASP.NET Core wywołają metodę WebApplication.CreateBuilder. Zastępowanie DOTNET_ENVIRONMENTASPNETCORE_ENVIRONMENT wartości w przypadku WebApplicationBuilder użycia. 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 launchSettings.json ustawia ASPNETCORE_ENVIRONMENT wartość na Development komputerze lokalnym.
Staging
Production: wartość domyślna, jeśli DOTNET_ENVIRONMENT nie ASPNETCORE_ENVIRONMENT została ustawiona.

Następujący kod powoduje:

Jest podobny do kodu wygenerowanego przez szablony ASP.NET Core.
Włącza stronę wyjątku dla deweloperów , gdy ASPNETCORE_ENVIRONMENT jest ustawiona wartość Development. Jest to wykonywane automatycznie przez metodę WebApplication.CreateBuilder .
Wywołuje wywołania UseExceptionHandlerASPNETCORE_ENVIRONMENT , gdy wartość jest niczym innym 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. 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 uruchamianieSettings.json

Środowisko programistyczne może włączać funkcje, które nie powinny być uwidocznione w środowisku produkcyjnym. Na przykład szablony projektów ASP.NET Core umożliwiają stronę wyjątków 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\launchSettings.json projektu. Wartości środowiska ustawione w launchSettings.json wartościach zastępowania ustawionych w środowisku systemowym.

Plik launchSettings.json:

Jest używany tylko na lokalnej maszynie programistycznej.
Nie jest wdrażany.
Zawiera ustawienia profilu.

W poniższej JSlaunchSettings.json sekcji ON przedstawiono plik dla projektu internetowego ASP.NET Core o nazwie EnvironmentsSample utworzony za pomocą programu Visual Studio lub dotnet new:

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

Powyższy element JSON zawiera dwa profile:

EnvironmentsSample: nazwa profilu to nazwa projektu. Jako pierwszy profil na liście ten profil jest domyślnie używany. Klucz "commandName" ma wartość "Project", Kestrel dlatego serwer internetowy jest uruchamiany.
IIS Express: klucz "commandName" ma wartość "IISExpress", dlatego IISExpress jest serwerem sieci Web.

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

IIS Express uruchamiania w menu

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

IISExpress: uruchamia IIS Express.
IIS : nie uruchomiono serwera internetowego. Oczekuje się, że usługi IIS będą dostępne.
Project : uruchamia program Kestrel.

Właściwości projektu programu Visual Studio 2022 Debugowanie/Ogólne zawiera link Interfejs użytkownika otwierania profilów uruchamiania debugowania . Ten link otwiera okno dialogowe Uruchamianie profilów , 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ę Właściwości> debugowania projektu. Zmiany wprowadzone w profilach projektów mogą nie obowiązywać do momentu ponownego uruchomienia serwera internetowego. Kestrel przed wykryciem zmian wprowadzonych w środowisku należy uruchomić ponownie.

Ustawienie zmiennych środowiskowych właściwości projektu

Następujący launchSettings.json 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"
      }
    }
  }
}

Można wybrać profile:

Z poziomu interfejsu użytkownika programu Visual Studio.
Za pomocą polecenia interfejsu dotnet run wiersza polecenia z --launch-profile opcją ustawioną na nazwę profilu. Takie podejście obsługuje Kestrel tylko profile.
```
dotnet run --launch-profile "SampleApp"
```

Ostrzeżenie

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

W przypadku korzystania z 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 Visual Studio Code.

Produkcja

Ś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, minyfikowane i potencjalnie obsługiwane z sieci CDN.
Wyłączone strony błędów diagnostycznych.
Przyjazne strony błędów włączone.
Włączono rejestrowanie produkcyjne i monitorowanie. Na przykład przy użyciu usługi Application Insights.

Ustawianie środowiska przez ustawienie zmiennej środowiskowej

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

Gdy host zostanie skompilowany, ostatnie ustawienie środowiska odczytane przez aplikację określa środowisko aplikacji. Nie można zmienić środowiska aplikacji, gdy aplikacja jest uruchomiona.

Strona Informacje z przykładowego kodu wyświetla wartość IWebHostEnvironment.EnvironmentName.

Azure App Service

Production jest wartością domyślną, jeśli DOTNET_ENVIRONMENT i ASPNETCORE_ENVIRONMENT nie zostały ustawione. Aplikacje wdrożone na platformie Azure są Production domyślnie.

Aby ustawić środowisko w aplikacji Azure App Service przy użyciu portalu:

Wybierz aplikację na stronie Usługi App Services .
W grupie Ustawienia wybierz pozycję Konfiguracja.
Na karcie Ustawienia aplikacji wybierz pozycję Nowe ustawienie aplikacji.
W oknie Ustawienia Dodaj/Edytuj aplikację podaj ASPNETCORE_ENVIRONMENTnazwę. W polu Wartość podaj środowisko (na przykład Staging).
Zaznacz pole wyboru Ustawienie miejsca wdrożenia , jeśli chcesz, aby ustawienie środowiska pozostało z bieżącym miejscem, gdy miejsca wdrożenia zostaną zamienione. Aby uzyskać więcej informacji, zobacz Konfigurowanie środowisk przejściowych w Azure App Service w dokumentacji platformy Azure.
Wybierz przycisk OK , aby zamknąć okno dialogowe Dodawanie/edytowanie ustawienia aplikacji .
Wybierz pozycję Zapisz w górnej części strony Konfiguracja .

Azure App Service automatycznie ponownie uruchamia aplikację po dodaniu, zmianie lub usunięciu ustawienia aplikacji w Azure Portal.

Windows — ustawianie zmiennej środowiskowej dla procesu

Wartości środowiska w launchSettings.json wartościach zastępowania ustawione w środowisku systemowym.

Aby ustawić ASPNETCORE_ENVIRONMENT parametr dla bieżącej sesji podczas uruchamiania aplikacji 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

Poprzednie polecenia są ustawiane ASPNETCORE_ENVIRONMENT tylko dla procesów uruchamianych z tego okna poleceń.

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

Otwórzustawienia systemuPanel sterowania>System> Advanced 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 zastosowanie w dotnet run dowolnym oknie polecenia otwartym po ustawieniu wartości. Wartości środowiska w launchSettings.json wartościach zastępowania ustawione w środowisku systemowym.

Windows — korzystanie z web.config

Aby ustawić zmienną środowiskową za pomocą web.configpolecenia , zobacz sekcję ASPNETCORE_ENVIRONMENTUstawianie zmiennych środowiskowych w plikuweb.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 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 nowszych), zobacz sekcję poleceniaAppCmd.exe w środowisku Zmienne <środowiskoweVariables>. Gdy zmienna ASPNETCORE_ENVIRONMENT środowiskowa jest ustawiana dla puli aplikacji, jej wartość zastępuje ustawienie na poziomie systemu.

Podczas 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ść została odebrana przez aplikacje:

Wykonaj net stop was /y polecenie, a następnie net start w3svc z poziomu 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 przed export 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 ustawień środowiska na poziomie maszyny.

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

Aby uzyskać więcej informacji, zobacz Host ogólny platformy ASP.NET Core.

Konfiguracja według środowiska

Aby załadować konfigurację według środowiska, zobacz Konfiguracja w 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ładowy kod, 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 tworzenia potoku żądania. Aby sprawdzić bieżące środowisko podczas konfigurowania usług, użyj polecenia builder.Environment zamiast app.Environment.

Dodatkowe zasoby

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:

DOTNET_ENVIRONMENT
ASPNETCORE_ENVIRONMENT gdy ConfigureWebHostDefaults jest wywoływana. Domyślne szablony aplikacji internetowej ASP.NET Core wywołają metodę ConfigureWebHostDefaults. Wartość ASPNETCORE_ENVIRONMENT zastępuje DOTNET_ENVIRONMENTwartość .

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

Development : plik launchSettings.json ustawia ASPNETCORE_ENVIRONMENT wartość na Development komputerze lokalnym.
Staging
Production : wartość domyślna, jeśli DOTNET_ENVIRONMENT nie ASPNETCORE_ENVIRONMENT została ustawiona.

Następujący kod powoduje:

Wywołania UseDeveloperExceptionPage , gdy ASPNETCORE_ENVIRONMENT jest ustawiona na Developmentwartość .
Wywołuje, UseExceptionHandler gdy wartość jest ASPNETCORE_ENVIRONMENT ustawiona na Staging, Productionlub Staging_2.
IWebHostEnvironmentStartup.ConfigureWprowadza do pliku . Takie podejście jest przydatne, gdy aplikacja wymaga Startup.Configure dostosowania tylko dla kilku środowisk z minimalnymi różnicami kodu na środowisko.
Jest podobny do kodu wygenerowanego przez szablony ASP.NET Core.

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

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

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

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

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

<environment include="Development">
    <div>The effective tag is: <environment include="Development"></div>
</environment>
<environment exclude="Development">
    <div>The effective tag is: <environment exclude="Development"></div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>
        The effective tag is:
        <environment include="Staging,Development,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 dokumencie jest oparty na Razor projekcie Pages o nazwie EnvironmentsSample.

Poniższy kod tworzy i uruchamia aplikację internetową o nazwie EnvironmentsSample:

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

Po uruchomieniu aplikacji zostaną wyświetlone niektóre z następujących danych wyjściowych:

Using launch settings from c:\tmp\EnvironmentsSample\Properties\launchSettings.json
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
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:\tmp\EnvironmentsSample

Programowanie i uruchamianieSettings.json

Środowisko programistyczne może włączać funkcje, które nie powinny być uwidocznione w środowisku produkcyjnym. Na przykład szablony ASP.NET Core umożliwiają stronę wyjątków dla deweloperów w środowisku dewelopera.

Plik launchSettings.json:

Jest używany tylko na lokalnej maszynie programistycznej.
Nie jest wdrażany.
zawiera ustawienia profilu.

W poniższej JSlaunchSettings.json sekcji ON przedstawiono plik dla projektu internetowego ASP.NET Core o nazwie EnvironmentsSample utworzony za pomocą programu Visual Studio lub dotnet new:

{
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:64645",
      "sslPort": 44366
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Powyższy znacznik zawiera dwa profile:

IIS Express: domyślny profil używany podczas uruchamiania aplikacji z poziomu programu Visual Studio. Klucz "commandName" ma wartość "IISExpress", dlatego IISExpress jest serwerem sieci Web. Profil uruchamiania można ustawić na projekt lub dowolny inny profil. Na przykład na poniższej ilustracji wybranie nazwy projektu spowoduje uruchomienie serwera internetowegoKestrel.
EnvironmentsSample: nazwa profilu to nazwa projektu. Ten profil jest domyślnie używany podczas uruchamiania aplikacji za pomocą dotnet runpolecenia . Klucz "commandName" ma wartość "Project", dlatego Kestrel serwer internetowy jest uruchamiany.

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

IISExpress: uruchamia IIS Express.
IIS : nie uruchomiono serwera internetowego. Oczekuje się, że usługi IIS będą dostępne.
Project : uruchamia program Kestrel.

Karta Debugowanie właściwości projektu programu Visual Studio zawiera graficzny interfejs użytkownika do edycji launchSettings.json pliku. Zmiany wprowadzone w profilach projektów mogą nie obowiązywać do momentu ponownego uruchomienia serwera internetowego. Kestrel należy uruchomić ponownie, aby można było wykryć zmiany wprowadzone w jego środowisku.

Ustawienie zmiennych środowiskowych właściwości projektu

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

{
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:64645",
      "sslPort": 44366
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IISX-Production": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      }
    },
    "IISX-Staging": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "KestrelStaging": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging"
      }
    }
  }
}

Można wybrać profile:

Z poziomu interfejsu użytkownika programu Visual Studio.
dotnet run Za pomocą polecenia w powłoce poleceń z opcją --launch-profile ustawioną na nazwę profilu. Takie podejście obsługuje Kestrel tylko profile.
```
dotnet run --launch-profile "SampleApp"
```

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.

{
    "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 Visual Studio Code.

Produkcja

Buforowanie.
Zasoby po stronie klienta są powiązane, zminimalizowane i potencjalnie obsługiwane z sieci CDN.
Wyłączono strony błędów diagnostycznych.
Włączone przyjazne strony błędów.
Włączono rejestrowanie i monitorowanie w środowisku produkcyjnym. Na przykład przy użyciu usługi Application Insights.

Ustawianie środowiska

Często warto ustawić określone środowisko do testowania przy użyciu zmiennej środowiskowej lub ustawienia platformy. Jeśli środowisko nie jest ustawione, wartość domyślna Productionto , co powoduje wyłączenie większości funkcji debugowania. Metoda ustawiania środowiska zależy od systemu operacyjnego.

Podczas tworzenia 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 IWebHostEnvironment.EnvironmentNamewartość .

Azure App Service

Production jest wartością domyślną, jeśli DOTNET_ENVIRONMENT i ASPNETCORE_ENVIRONMENT nie zostały ustawione. Aplikacje wdrożone na platformie Azure są Production domyślnie.

Aby ustawić środowisko w Azure App Service, wykonaj następujące kroki:

Wybierz aplikację w bloku App Services .
W grupie Ustawienia wybierz blok Konfiguracja .
Na karcie Ustawienia aplikacji wybierz pozycję Nowe ustawienie aplikacji.
W oknie Dodawanie/edytowanie ustawienia aplikacji podaj ASPNETCORE_ENVIRONMENTnazwę. W polu Wartość podaj środowisko (na przykład Staging).
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 Azure App Service w dokumentacji platformy Azure.
Wybierz przycisk OK , aby zamknąć okno ustawienia Dodaj/Edytuj aplikację .
Wybierz pozycję Zapisz w górnej części bloku Konfiguracja .

Azure App Service automatycznie ponownie uruchamia aplikację po dodaniu, zmianie lub usunięciu ustawienia aplikacji w Azure Portal.

Windows

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

Aby ustawić ASPNETCORE_ENVIRONMENT dla bieżącej sesji, gdy aplikacja jest uruchamiana przy użyciu polecenia dotnet run, są używane następujące polecenia:

Wiersz polecenia

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

Program PowerShell

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

Powyższe polecenie ustawia ASPNETCORE_ENVIRONMENT tylko dla procesów uruchamianych z tego okna polecenia.

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

Otwórz ustawienia systemu Panel sterowania>System>Zaawansowane i dodaj lub edytuj ASPNETCORE_ENVIRONMENT wartość:
Otwórz administracyjny wiersz polecenia i użyj setx polecenia lub otwórz administracyjny wiersz polecenia programu PowerShell i użyj polecenia [Environment]::SetEnvironmentVariable:

Wiersz polecenia
```
setx ASPNETCORE_ENVIRONMENT Staging /M
```
Przełącznik /M wskazuje, aby ustawić zmienną środowiskową na poziomie systemu. /M Jeśli przełącznik nie jest używany, zmienna środowiskowa jest ustawiana dla konta użytkownika.

Program PowerShell
```
[Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Staging", "Machine")
```
Wartość Machine opcji wskazuje, aby ustawić 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.

web.config

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

Plik projektu lub profil publikowania

W przypadku wdrożeń usług IIS systemu Windows: Uwzględnij <EnvironmentName> właściwość w profilu publikowania (.pubxml) lub pliku projektu. To podejście ustawia środowisko w web.config po opublikowaniu projektu:

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

Na pulę aplikacji usług IIS

Aby ustawić zmienną ASPNETCORE_ENVIRONMENT środowiskową dla aplikacji uruchomionej w izolowanej puli aplikacji (obsługiwanej w usługach IIS 10.0 lub nowszej), zobacz sekcję AppCmd.exe polecenia w temacie Zmienne <środowiskoweWarianacje> środowiskowe. 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 lub zmieniania ASPNETCORE_ENVIRONMENT zmiennej środowiskowej użyj dowolnej z następujących metod, aby nowa wartość została odebrana przez aplikacje:

net start w3svc Następnie wykonaj net stop was /y polecenie w wierszu 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

Alternatywnie ustaw środowisko export przy użyciu polecenia 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 bash_profile pliku dla ustawień środowiska na poziomie maszyny.

Ustawianie środowiska w kodzie

Wywołanie UseEnvironment podczas kompilowania hosta. Zobacz Host ogólny platformy .NET w ASP.NET Core.

Konfiguracja według środowiska

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

Oparta na środowisku klasa i metody uruchamiania

Wstrzykiwanie elementu IWebHostEnvironment do klasy Startup

Wstrzykiwanie IWebHostEnvironment do konstruktora Startup . Takie podejście jest przydatne, gdy aplikacja wymaga skonfigurowania Startup tylko dla kilku środowisk z minimalnymi różnicami w kodzie na środowisko.

W poniższym przykładzie:

Środowisko jest przechowywane w _env polu.
_env jest używany w systemach ConfigureServices i Configure do stosowania konfiguracji uruchamiania na podstawie środowiska aplikacji.

public class Startup
{
    public Startup(IConfiguration configuration, IWebHostEnvironment env)
    {
        Configuration = configuration;
        _env = env;
    }

    public IConfiguration Configuration { get; }
    private readonly IWebHostEnvironment _env;

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            Console.WriteLine(_env.EnvironmentName);
        }
        else if (_env.IsStaging())
        {
            Console.WriteLine(_env.EnvironmentName);
        }
        else
        {
            Console.WriteLine("Not dev or staging");
        }

        services.AddRazorPages();
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

Konwencje klas uruchamiania

Po uruchomieniu aplikacji ASP.NET Core klasa Startup uruchamia aplikację. Aplikacja może definiować wiele Startup klas dla różnych środowisk. Odpowiednia Startup klasa jest wybierana w czasie wykonywania. Klasa, której sufiks nazwy pasuje do bieżącego środowiska, ma priorytet. Jeśli pasujący Startup{EnvironmentName} klasa nie zostanie znaleziona, zostanie użyta Startup klasa . Takie podejście jest przydatne, gdy aplikacja wymaga skonfigurowania uruchamiania dla kilku środowisk z wieloma różnicami w kodzie na środowisko. Typowe aplikacje nie będą potrzebować tego podejścia.

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

public class StartupDevelopment
{
    public StartupDevelopment(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app)
    {
        app.UseDeveloperExceptionPage();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public class StartupProduction
{
    public StartupProduction(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app)
    {

        app.UseExceptionHandler("/Error");
        app.UseHsts();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

UseStartup(IWebHostBuilder, String) Użyj przeciążenia, które akceptuje nazwę zestawu:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

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

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

Konwencje metod uruchamiania

Konfigurowanie i konfigurowanieUsługi obsługują wersje Configure<EnvironmentName> formularza specyficzne dla środowiska i Configure<EnvironmentName>Services. Configure<EnvironmentName>Services Jeśli dopasowanie lub Configure<EnvironmentName> metoda nie zostanie znaleziona, ConfigureServices zostanie użyta odpowiednio metoda lub Configure . Takie podejście jest przydatne, gdy aplikacja wymaga skonfigurowania uruchamiania dla kilku środowisk z wieloma różnicami w kodzie na środowisko:

public class Startup
{
    private void StartupConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages();
    }

    public void ConfigureDevelopmentServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureStagingServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureProductionServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        MyTrace.TraceMessage();

        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }

    public void ConfigureStaging(IApplicationBuilder app, IWebHostEnvironment env)
    {
        MyTrace.TraceMessage();

        app.UseExceptionHandler("/Error");
        app.UseHsts();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public static class MyTrace
{
    public static void TraceMessage([CallerMemberName] string memberName = "")
    {
        Console.WriteLine($"Method: {memberName}");
    }
}