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

Czy ta strona jest pomocna?

Czy chcesz coś dodać do tej opinii?

Opinia zostanie wysłana do firmy Microsoft: po naciśnięciu przycisku Prześlij opinia zostanie użyta do ulepszania produktów i usług firmy Microsoft. Zasady ochrony prywatności.

Przez 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ść 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:

• 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>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 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ącego przykładu:

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

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.

Ś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.

launchSettings.json Plik:

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

Poniższy kod JSON przedstawia launchSettings.json plik projektu internetowego ASP.NET Core o nazwie EnvironmentsSample utworzony za pomocą 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 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.

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

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 interfejsu użytkownika 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 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 Szczegółowe informacje aplikacji.

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:

1. Wybierz aplikację na stronie Usługi App Services .
2. W grupie Ustawienia wybierz pozycję Konfiguracja.
3. Na karcie Ustawienia aplikacji wybierz pozycję Nowe ustawienie aplikacji.
4. W oknie Ustawienia Dodaj/Edytuj aplikację podaj ASPNETCORE_ENVIRONMENTnazwę. 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, gdy miejsca wdrożenia zostaną zamienione. Aby uzyskać więcej informacji, zobacz Konfigurowanie środowisk przejściowych w Azure App 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 .

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 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, 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 uruchamianych z tego okna polecenia.

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

• Otwórz Panel sterowania>SystemZaawansowane> ustawienia systemowe 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:

  • 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 — używanie web.config

Aby ustawić zmienną środowiskową za ASPNETCORE_ENVIRONMENT pomocą web.configpolecenia , zobacz sekcję Ustawianie 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ć 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 poleceniazmienne <ś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 ASPNETCORE_ENVIRONMENT lub zmieniania zmiennej środowiskowej użyj jednej z następujących metod, aby nowa wartość została pobrana 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 pliku bash_profile dla 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 .NET w 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 polecenia WebApplicationBuilder.Environment lub WebApplication.Environment , aby warunkowo dodać 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

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

Autor : 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ł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ć na dowolną wartość, ale struktura udostępnia następujące wartości:

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

Poniższy kod:

• Wywołuje UseDeveloperExceptionPage metodę , gdy ASPNETCORE_ENVIRONMENT jest ustawiona na Developmentwartość .
• Wywołuje UseExceptionHandler metodę , gdy wartość parametru jest ustawiona ASPNETCORE_ENVIRONMENT na Staging, Productionlub Staging_2.
• Wstrzykiwania IWebHostEnvironment do pliku Startup.Configure. Takie podejście jest przydatne, gdy aplikacja wymaga dostosowania Startup.Configure tylko dla kilku środowisk z minimalnymi różnicami w kodzie 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 tagu ś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 Windows i macOS zmienne środowiskowe i wartości nie są uwzględniane w wielkości liter. Zmienne środowiskowe i wartości systemu Linux są domyślnie uwzględniane wielkość 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 deweloperskie może włączać funkcje, które nie powinny być widoczne w środowisku produkcyjnym. Na przykład szablony ASP.NET Core włączają stronę wyjątków dla deweloperów w środowisku dewelopera.

Ś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 dewelopera.
• 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 przy użyciu 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"
      }
    }
  }
}

Poprzednia adiustacja zawiera dwa profile:

• IIS Express: domyślny profil używany podczas uruchamiania aplikacji z 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 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 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 przed wykryciem zmian wprowadzonych w środowisku należy uruchomić ponownie.

Następujący launchSettings.json 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 interfejsu użytkownika 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 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 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 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 Szczegółowe informacje aplikacji.

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, 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 Azure App Service, wykonaj następujące kroki:

1. Wybierz aplikację w bloku Usługi App Services .
2. W grupie Ustawienia wybierz blok Konfiguracja.
3. Na karcie Ustawienia aplikacji wybierz pozycję Nowe ustawienie aplikacji.
4. W oknie Ustawienia Dodaj/Edytuj aplikację podaj ASPNETCORE_ENVIRONMENTnazwę. 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, gdy miejsca wdrożenia zostaną zamienione. Aby uzyskać więcej informacji, zobacz Konfigurowanie środowisk przejściowych w Azure App 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 .

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 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, są używane następujące polecenia:

Wiersz polecenia

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

PowerShell

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

Poprzednie polecenie ustawia ASPNETCORE_ENVIRONMENT tylko procesy uruchamiane z tego okna poleceń.

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

• Otwórz ustawienia systemu Panel sterowania>SystemAdvanced> 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:

  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.

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

web.config

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

Project pliku lub profilu publikowania

W przypadku 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>

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ę poleceniaAppCmd.exe w temacie 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 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 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 bash_profile pliku dla ustawień środowiska na poziomie maszyny.

Ustawianie środowiska w kodzie

Wywołaj 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.

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 kilku środowisk z minimalnymi różnicami kodu na środowisko.

W poniższym przykładzie:

• Środowisko jest przechowywane w _env polu.
• _env jest używany w ConfigureServices programie 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 startupowa 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 znaleziono 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 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}");
    }
}

Dodatkowe zasoby

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