Использование нескольких сред в ASP.NET Core

Авторы: Рик Андерсон (Rick Anderson) и Кирк Ларкин (Kirk Larkin)

ASP.NET Core настраивает поведение приложения в зависимости от среды выполнения с помощью переменной среды.

Среды

Чтобы определить среду выполнения, ASP.NET Core считывает данные из следующих переменных среды:

1. DOTNET_ENVIRONMENT.
2. ASPNETCORE_ENVIRONMENT если вызывается метод WebApplication.CreateBuilder. Шаблоны по умолчанию для веб-приложений ASP.NET Core вызывают WebApplication.CreateBuilder. Значение DOTNET_ENVIRONMENT переопределяется ASPNETCORE_ENVIRONMENT при WebApplicationBuilder использовании. Для других узлов, таких как ConfigureWebHostDefaults и WebHost.CreateDefaultBuilder, ASPNETCORE_ENVIRONMENT имеет более высокий приоритет.

Переменной IHostEnvironment.EnvironmentName можно присвоить любое значение, но платформа предоставляет следующие значения:

• Development: на локальном компьютере в файле launchSettings.json для ASPNETCORE_ENVIRONMENT задается значение Development.
• Staging
• Production: значение по умолчанию, если DOTNET_ENVIRONMENT и ASPNETCORE_ENVIRONMENT не заданы.

Следующий код:

• Это аналогично коду, созданному на основе шаблонов ASP.NET Core.
• Включает страницу со сведениями об исключении для разработчика, если для ASPNETCORE_ENVIRONMENT задано значение Development. Это происходит автоматически благодаря методу WebApplication.CreateBuilder.
• Вызывает UseExceptionHandler, если переменная ASPNETCORE_ENVIRONMENT имеет любое значение, кроме Development.
• Предоставляет экземпляр IWebHostEnvironment в свойстве EnvironmentWebApplication.

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

Вспомогательная функция тега среды использует значение IHostEnvironment.EnvironmentName для включения или исключения разметки в элементе:

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

Страница со сведениями в примере кода включает предыдущую разметку и отображает значение IWebHostEnvironment.EnvironmentName.

В ОС Windows и macOS регистр символов в переменных среды и их значениях не учитывается. В ОС Linux в переменных среды и их значениях регистр символов по умолчанию учитывается.

Создание EnvironmentsSample

Пример кода, используемый в этой статье, основан на проекте Razor Pages с именем EnvironmentsSample.

Следующие команды .NET CLI создают и запускают веб-приложение с именем EnvironmentsSample:

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

При запуске приложение отобразит выходные данные, аналогичные следующим:

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

Настройка среды в командной строке

Используйте флаг --environment, чтобы задать среду. Например:

dotnet run --environment Production

Предыдущая команда задает среду Production и отображает в окне командной строки выходные данные, аналогичные приведенным ниже:

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

Разработка и launchSettings.json

В среде разработки могут быть включены функции, которые не должны быть доступны в рабочей среде. Например, шаблоны проектов ASP.NET Core включают в среде разработки страницу со сведениями об исключении для разработчика. Из-за затрат на производительность область проверка и проверка зависимостей происходит только в разработке.

Среду для локального компьютера разработки можно задать в файле Properties\launchSettings.json проекта. Значения среды, заданные в launchSettings.json переопределении значений в системной среде.

Файл launchSettings.json:

• используется только на локальном компьютере разработки;
• не развернут;
• содержит параметры профиля.

В следующем фрагменте JSON показан файл launchSettings.json для веб-проекта ASP.NET Core с именем EnvironmentsSample, созданный с помощью Visual Studio или 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"
      }
    }
  }
}

Приведенный выше файл JSON содержит два профиля:

• EnvironmentsSample: имя профиля — это имя проекта. Как первый из перечисленных профилей этот профиль используется по умолчанию. Ключ "commandName" имеет значение "Project", поэтому запускается веб-сервер Kestrel.

• IIS Express: ключ "commandName" имеет значение "IISExpress", поэтому IISExpress является веб-сервером.

Профиль запуска можно задать для проекта или любого другого профиля, включенного в launchSettings.jsonнего. Например, на приведенном ниже изображении при выборе имени проекта запускается веб-сервер Kestrel.

Значение commandName может определять запускаемый веб-сервер. commandName может иметь одно из следующих значений:

• IISExpress : запускает IIS Express.
• IIS : веб-сервер не запущен. Службы IIS должны быть доступны.
• Project : запускает Kestrel.

Вкладка свойств проекта Отладка / Общие в Visual Studio 2022 содержит ссылку Открыть пользовательский интерфейс профилей запуска отладки. Эта ссылка открывает диалоговое окно "Профили запуска" , которое позволяет изменять параметры переменной среды в launchSettings.json файле. Диалоговое окно Профили запуска также можно открыть из меню Отладка, выбрав Свойства отладки <имя проекта>. Для вступления в силу изменений, внесенных в профили проекта, может потребоваться перезапуск веб-сервера. Чтобы сервер Kestrel обнаружил изменения, внесенные в среду, его необходимо перезапустить.

launchSettings.json Следующий файл содержит несколько профилей:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:59481",
      "sslPort": 44308
    }
  },
  "profiles": {
    "EnvironmentsSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "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"
      }
    }
  }
}

Профили можно выбирать:

• В пользовательском интерфейсе Visual Studio.

• С помощью команды CLI dotnet run. При этом для параметра --launch-profile нужно задать имя профиля. Этот подход поддерживает только профили Kestrel.

  dotnet run --launch-profile "EnvironmentsSample"
  

Предупреждение

launchSettings.json не следует хранить секреты. Для хранения секретов во время разработки в локальной среде можно использовать средство Secret Manager.

При использовании Visual Studio Code переменные среды можно задать в .vscode/launch.json файле. В следующем примере задается несколько переменных среды для значений конфигурации узла:

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

Файл .vscode/launch.json используется только Visual Studio Code.

Производство

Конфигурация рабочей среды должна обеспечивать максимальный уровень безопасности, производительности и надежности приложений. Некоторые общие параметры, отличные от разработки:

• Кэширование.
• ресурсы на стороне клиента объединяются в пакеты, уплотняются и могут предоставляться из сети CDN;
• страницы с сообщениями об ошибках диагностики отключены;
• включены страницы с понятными пользователям сообщениями об ошибках;
• включены средства ведения журналов и мониторинга в рабочей среде (например, с использованием Application Insights).

Настройка среды путем настройки переменной среды

Часто бывает полезным указать определенную среду для тестирования с переменной среды или параметром платформы. Если среда не указана, по умолчанию используется среда Production, в которой большинство функций отладки отключено. Способ указания среды зависит от операционной системы.

При создании узла среду приложения определяет последний параметр среды, считанный приложением. Среду приложения невозможно изменить во время его выполнения.

На странице со сведениями в примере кода отображается значение IWebHostEnvironment.EnvironmentName.

Служба приложений Azure

Production — значение по умолчанию, если DOTNET_ENVIRONMENT и ASPNETCORE_ENVIRONMENT не заданы. Приложения, развернутые в Azure, по умолчанию являются рабочими (Production).

Чтобы задать среду в приложении Службы приложений Azure с помощью портала, сделайте следующее:

1. Выберите приложение на странице Службы приложений.
2. В группе Параметры выберите Конфигурация.
3. На вкладке Параметры приложения выберите Новый параметр приложения.
4. В окне Добавить или изменить параметр приложения в поле Имя введите ASPNETCORE_ENVIRONMENT. В поле Значение укажите среду (например, Staging).
5. Установите флажок Параметр слота развертывания, если нужно, чтобы параметр среды оставался в текущем слоте при замене слота развертывания. Дополнительные сведения см. в статье Set up staging environments in Azure App Service (Настройка промежуточных сред в Службе приложений Azure) в документации по Azure.
6. Нажмите кнопку ОК, чтобы закрыть диалоговое окно Добавить или изменить параметр приложения.
7. Нажмите кнопку Сохранить в верхней части страницы Конфигурация.

Служба приложений Azure автоматически перезапускает приложение после добавления, изменения или удаления параметра приложения на портале Azure.

Windows — настройка переменной среды для процесса

Значения среды в переопределении, заданные в launchSettings.json системной среде.

Если приложение запускается с помощью команды dotnet run, то, чтобы задать переменную ASPNETCORE_ENVIRONMENT для текущего сеанса, используйте следующие команды в командной строке или в PowerShell:

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

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

Windows — глобальная настройка переменной среды

Предыдущая команда позволяет задать ASPNETCORE_ENVIRONMENT только для процессов, запускаемых из этого командного окна.

Чтобы задать это значение в Windows на глобальном уровне, используйте один из следующих подходов.

• Откройте Панель управления>Система>Дополнительные параметры системы и добавьте или измените значение ASPNETCORE_ENVIRONMENT:

  

  

• Откройте командную строку администратора и выполните команду setx либо откройте командную строку администратора PowerShell и используйте [Environment]::SetEnvironmentVariable:

  • setx ASPNETCORE_ENVIRONMENT Staging /M
    

    Параметр /M задает переменную среды на уровне системы. Если параметр /M не используется, переменная среды задается для учетной записи пользователя.

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

    Параметр Machine задает переменную среды на уровне системы. При изменении значения параметра на User переменная среды задается для учетной записи пользователя.

Если переменная среды ASPNETCORE_ENVIRONMENT задана глобально, она действует для dotnet run в любом окне командной строки, открываемом после установки значения. Значения среды в переопределении, заданные в launchSettings.json системной среде.

Windows — использование web.config

Сведения об установке переменной среды ASPNETCORE_ENVIRONMENT с помощью web.config см. в разделе Настройка переменных среды статьи Файл web.config.

Windows — развертывания IIS

Включите свойство <EnvironmentName> в профиле публикации (.pubxml) или файле проекта. При этом подходе во время публикации проекта среда задается в файле web.config:

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

Чтобы задать переменную среды ASPNETCORE_ENVIRONMENT для приложения, выполняющегося в изолированном пуле приложений (такая возможность поддерживается в службах IIS 10.0 и более поздних версий), см. подраздел, посвященный команде AppCmd.exe, в разделе Переменные среды <environmentVariables>. Если переменная среды ASPNETCORE_ENVIRONMENT задана для пула приложений, ее значение переопределяет значение на уровне системы.

При размещении приложения в службах IIS и добавлении или изменении переменной среды ASPNETCORE_ENVIRONMENT используйте один из следующих подходов по применению нового значения в приложении.

• Из командной строки выполните команду net stop was /y, за которой следует net start w3svc.
• Перезапустите сервер.

macOS

Задать текущую среду в macOS можно в командной строке при запуске приложения:

ASPNETCORE_ENVIRONMENT=Staging dotnet run

Также можно задать среду с помощью команды export до запуска приложения:

export ASPNETCORE_ENVIRONMENT=Staging

Переменные среды на уровне компьютера задаются в файле BASHRC или BASH_PROFILE. Измените файл в любом текстовом редакторе. Добавьте следующий оператор:

export ASPNETCORE_ENVIRONMENT=Staging

Linux

В дистрибутивах Linux используйте команду export в командной строке для значений переменных на уровне сеанса или в файле bash_profile для значений среды на уровне компьютера.

Указание среды в коде

Чтобы задать среду в коде, при создании WebApplicationBuilder используйте WebApplicationOptions.EnvironmentName, как показано в следующем примере:

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

Конфигурация для разных сред

Сведения о загрузке конфигурации в зависимости от среды см. в разделе Конфигурация в ASP.NET Core.

Настройка служб и ПО промежуточного слоя в зависимости от среды

Используйте WebApplicationBuilder.Environment или WebApplication.Environment для условного добавления служб или ПО промежуточного слоя в зависимости от текущей среды. Шаблон проекта включает пример кода, который добавляет ПО промежуточного слоя, только если текущая среда не является средой для разработки:

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

Выделенный код проверяет текущую среду при создании конвейера запросов. Чтобы проверить текущую среду во время настройки служб, используйте builder.Environment вместо app.Environment.

Дополнительные ресурсы

• Просмотреть или скачать образец кода (описание загрузки)
• Запуск приложения в ASP.NET Core
• Конфигурация в ASP.NET Core
• Среды ASP.NET Core Blazor