Udostępnij za pośrednictwem


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

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z bieżącą wersją, zapoznaj się z wersją tego artykułu platformy .NET 8.

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz .NET i .NET Core Support Policy (Zasady obsługi platformy .NET Core). Aby zapoznać się z bieżącą wersją, zapoznaj się z wersją tego artykułu platformy .NET 8.

Ważne

Te informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany, zanim zostanie wydany komercyjnie. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

Aby zapoznać się z bieżącą wersją, zapoznaj się z wersją tego artykułu platformy .NET 8.

Autorzy: Rick Anderson i Kirk Larkin

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

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.

Ś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ść ASPNETCORE_ENVIRONMENT zastępuje DOTNET_ENVIRONMENTwartość .

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ę:

Następujący kod powoduje:

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 launchSettings.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\launchSettings.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ższy kod JSON przedstawia launchSettings.json plik dla projektu internetowego ASP.NET Core o nazwie EnvironmentsSample utworzonego 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 kod JSON 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

Uruchamianie programu IIS Express w menu

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.

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: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 usługi Application Insights.

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_ENVIRONMENT ASPNETCORE_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ę Zmienne środowiskowe.
  3. Na karcie Ustawienia aplikacji wybierz pozycję + Dodaj.
  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ść:

    Właściwości zaawansowane systemu

    Zmienna środowiskowa platformy ASPNET Core

  • 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

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 ConfigureWebHostDefaults jest wywoływany. 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ę:

Następujący kod powoduje:

  • Wywołania UseDeveloperExceptionPage , gdy ASPNETCORE_ENVIRONMENT jest ustawiona wartość Development.
  • Wywołuje UseExceptionHandler , gdy wartość parametru jest ustawiona ASPNETCORE_ENVIRONMENT na Staging, Productionlub Staging_2.
  • Wstrzykiwania IWebHostEnvironment do Startup.Configure. Takie podejście jest przydatne, gdy aplikacja wymaga dostosowania Startup.Configure 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 launchSettings.json

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

Środowisko tworzenia maszyn lokalnych można ustawić w pliku Properties\launchSettings.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ższy kod JSON przedstawia launchSettings.json plik dla projektu internetowego ASP.NET Core o nazwie EnvironmentsSample utworzonego 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 dołączony profil. Na przykład na poniższej ilustracji wybranie nazwy projektu spowoduje uruchomienie serwera internetowego.Kestrel

    Uruchamianie programu IIS Express w menu

  • 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 program IIS Express.
  • IIS : brak uruchomionego serwera internetowego. Oczekuje się, że usługi IIS będą dostępne.
  • Project : uruchamia Kestrelprogram .

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 przed wykryciem zmian wprowadzonych 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"
      }
    }
  }
}

Profile można wybrać:

  • Z poziomu interfejsu użytkownika programu Visual Studio.

  • dotnet run Za pomocą polecenia w powłoce poleceń 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 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 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 usługi Application Insights.

Ustawianie środowiska

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_ENVIRONMENT ASPNETCORE_ENVIRONMENT i nie zostały ustawione. Aplikacje wdrażane na platformie Azure są Production domyślnie.

Aby ustawić środowisko w usłudze aplikacja systemu Azure Service, wykonaj następujące kroki:

  1. Wybierz aplikację w bloku App Services .
  2. W grupie Ustawienia wybierz blok 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 ustawienia Dodaj/Edytuj aplikację.
  7. Wybierz pozycję Zapisz w górnej części bloku Konfiguracja .

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

Windows

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

Aby ustawić ASPNETCORE_ENVIRONMENT parametr 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

Poprzednie polecenie ustawia ASPNETCORE_ENVIRONMENT tylko dla procesów uruchomionych z tego okna 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ść:

    Właściwości zaawansowane systemu

    Zmienna środowiskowa platformy ASPNET Core

  • Otwórz wiersz polecenia administracyjnego 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 pomocą web.configpolecenia , zobacz sekcję ASPNETCORE_ENVIRONMENT Ustawianie zmiennych środowiskowych pliku web.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 pliku web.config po opublikowaniu projektu:

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

Na pulę aplikacji usług IIS

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ę AppCmd.exe polecenia w temacie 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 lub zmieniania ASPNETCORE_ENVIRONMENT zmiennej środowiskowej użyj dowolnej 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 bash_profile pliku dla ustawień środowiska na poziomie maszyny.

Ustawianie środowiska w kodzie

Wywołaj metodę UseEnvironment podczas kompilowania hosta. Zobacz Host ogólny platformy .NET w programie ASP.NET Core.

Konfiguracja według środowiska

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

Klasy i metody uruchamiania oparte na środowisku

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 kodu na środowisko.

W poniższym przykładzie:

  • Środowisko jest przechowywane w _env terenie.
  • _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 nie można odnaleźć pasującej Startup{EnvironmentName} klasy, zostanie użyta Startup klasa. Takie podejście jest przydatne, gdy aplikacja wymaga skonfigurowania uruchamiania dla kilku środowisk z wieloma różnicami kodu 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 specyficzne dla środowiska formularza Configure<EnvironmentName> 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}");
    }
}

Dodatkowe zasoby