среды выполнения ASP.NET Core

ASP.NET Core настраивает поведение приложения в зависимости от среды выполнения, которая обычно отражает место работы приложения.

Приложения обычно выполняются в среде разработки во время локальной разработки и тестирования на компьютере разработчика с одним набором настроенного поведения. В отличие от этого, они выполняются в рабочей среде при развертывании на сервере с другим набором настроенных поведений. Можно использовать любое количество дополнительных сред, таких как промежуточная среда, предоставляемая платформой для промежуточного развертывания до динамического развертывания или других сред, создаваемых разработчиками.

В этой статье описывается среда выполнения приложений, использование среды для управления поведением приложения и настройка среды.

Инструкции Blazor по средам, которые добавляются в инструкции, приведенные в этой статье, см . в разделе ASP.NET Основные Blazor среды.

Environments

Хотя среда может быть любым строковым значением, следующие значения среды предоставляются платформой:

• Development
• Staging
• Production

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

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

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

Logging

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

info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Staging

Переменные среды, определяющие среду выполнения

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

DOTNET_ENVIRONMENT ASPNETCORE_ENVIRONMENT Если переменные среды не заданы, рабочая среда — это среда по умолчанию.

На Windows и macOS имена переменных среды не зависят от регистра. Переменные среды Linux чувствительны к регистру.

Управление выполнением кода по среде

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

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

    ...
}

В приложении IHostEnvironment предоставляются общие сведения о среде размещения приложения, а IHostEnvironment.EnvironmentName свойство указывает текущую среду приложения.

Отображаемое содержимое

Вставьте IHostEnvironment в сервером-отрисованный компонент Razor и используйте методы расширения службы и свойство EnvironmentName, чтобы определить среду для отрисовки содержимого.

@inject IHostEnvironment Env

@if (Env.IsDevelopment())
{
    <div>The environment is Development.</div>
}

@if (!Env.IsDevelopment())
{
    <div>The environment isn't Development.</div>
}

@if (Env.IsStaging() || Env.EnvironmentName == "Testing")
{
    <div>The environment is either Staging or Testing.</div>
}

Сведения Blazor Web Appо том, что требуется среда для управления отрисовкой на стороне клиента, см. в разделе Предварительная отрисовка компонентов ASP.NET Core Razor.

Установка среды в командной оболочке при запуске приложения (dotnet run)

Используйте -e|--environment опцию, чтобы установить среду:

dotnet run -e Staging

Настройка среды с помощью файла параметров запуска (launchSettings.json)

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

Файл launchSettings.json:

• используется только на локальном компьютере разработки;
• Не развертывается при публикации приложения.
• Может содержать несколько профилей, каждый из которых настраивает другую среду.

В следующем примере устанавливается среда подготовки для профиля запуска https с помощью переменной среды ASPNETCORE_ENVIRONMENT.

"https": {
  "commandName": "Project",
  "dotnetRunMessages": true,
  "launchBrowser": true,
  "applicationUrl": "https://localhost:7205",
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Staging"
  }
}

В Visual Studio существует два подхода к настройке среды с помощью профилей запуска:

• Нажмите Alt+Enter или выберите Свойства, щелкнув правой кнопкой мыши проект в Обозревателе Решений. Выберите Отладка>Общие, а затем выберите ссылку Открыть интерфейс профилей запуска отладки.

• Выбрав проект в обозревателе решений, выберите свойства отладки {PROJECT NAME} в меню отладки , где {PROJECT NAME} заполнитель является именем проекта.

Приведенные выше подходы открывают диалоговое окно "Профили запуска" , где можно изменить параметры переменной среды в launchSettings.json файле. Для вступления в силу изменений, внесенных в профили проекта, может потребоваться перезапуск веб-сервера. Чтобы сервер Kestrel обнаружил изменения, внесенные в среду, его необходимо перезапустить.

Профили можно выбрать в пользовательском интерфейсе Visual Studio рядом с кнопкой "Пуск" (*).

Если решение содержит несколько проектов, задайте только среду для запускаемого проекта.

Кроме того, используйте dotnet run команду с параметром-lp|--launch-profile, заданным для имени профиля. Этот подход поддерживает профили запуска, основанные только на Project команде.

dotnet run -lp "https"

При использовании Visual Studio Code с пакетом разработки C# для Visual Studio Code (начало работы с C# в VS Code) профили запуска собираются из файла приложения launchSettings.json .

Если набор средств разработки на C# не используется, задайте ASPNETCORE_ENVIRONMENT переменную среды в .vscode/launch.jsonenv разделе, а также другие переменные среды, заданные в разделе:

"env": {
    "ASPNETCORE_ENVIRONMENT": "Staging",
    ...
},

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

Настройка среды с использованием переменной среды

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

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

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

Чтобы задать ASPNETCORE_ENVIRONMENT переменную среды, ознакомьтесь со следующими ресурсами в документации По Azure:

• Настройка приложения службы приложений
• Настройка промежуточных сред в Службе приложений Azure

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

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

Чтобы задать переменную среды ASPNETCORE_ENVIRONMENT для текущего сеанса (командной оболочки) при запуске приложения с помощью dotnet run, используйте следующие команды. После установки переменной среды приложение запускается без профиля запуска с помощью --no-launch-profile параметра.

1. В командной оболочке задайте переменную среды с помощью соответствующего подхода для операционной системы.

2. dotnet run Выполните команду без использования профиля запуска:

   dotnet run --no-launch-profile
   

При использовании PowerShell предыдущие шаги можно объединить в следующих двух командах. В следующем примере устанавливается промежуточная среда:

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

Глобальное определение переменной среды

Используйте соответствующее руководство для операционной системы, чтобы задать ASPNETCORE_ENVIRONMENT переменную среды.

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

Настройка среды для приложений, развернутых в IIS

Чтобы задать переменную среды с помощью файла ASPNETCORE_ENVIRONMENTweb.config, см. файл web.config.

Чтобы задать переменную среды для развертывания в IIS, включите <EnvironmentName> свойство в профиль публикации (PUBXML) или файл проекта. Следующий пример задает среду в web.config промежуточной среде при публикации проекта:

<PropertyGroup>
  <EnvironmentName>Staging</EnvironmentName>
</PropertyGroup>

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

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

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

Докер

Задайте среду приложения с помощью любого из подходов в этом разделе.

Используйте Dockerfile

ASPNETCORE_ENVIRONMENT Задайте переменную среды в Dockerfile с помощью инструкцииENV:

ENV ASPNETCORE_ENVIRONMENT=Staging

Используйте Docker Compose

Для приложений с несколькими службами, управляемыми с помощью Docker Compose, определите ASPNETCORE_ENVIRONMENT переменные среды в docker-compose.yml файле:

version: "3.9"
services:
  web:
    build: .
    ports:
      - "8000:5000"
    environment:
      - ASPNETCORE_ENVIRONMENT=Staging
      - API_KEY=...

Среда, установленная во время выполнения посредством Docker Compose, переопределяет среду, заданную в Dockerfile.

Используйте команду docker run

При запуске контейнера Docker с docker run командой задайте ASPNETCORE_ENVIRONMENT переменную среды с опцией -e|--env:

docker run -e ASPNETCORE_ENVIRONMENT=Staging aspnet_core_image

Среда, заданная во время выполнения, docker run переопределяет среду, заданную Dockerfile.

Файл среды Docker

ASPNETCORE_ENVIRONMENT Задайте переменную среды с помощью файла среды Docker (.env).

env_variables.env:

ASPNETCORE_ENVIRONMENT=Staging

Загрузите файл с параметром --env-file при выполнении docker run команды:

docker run --env-file ./env_variables.env aspnet_core_image

Среда, заданная во время выполнения, docker run переопределяет среду, заданную Dockerfile.

Настройка среды в коде запуска приложения

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    EnvironmentName = Environments.Staging
}); 

Загрузка конфигурации по среде

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

Доступ к среде из Startup класса

Startup Использование класса (Startup.cs) с методами ConfigureConfigureServices было необходимо до выпуска .NET 6 и всё ещё поддерживается.

Инъектируйте IWebHostEnvironment в конструктор Startup для управления выполнением кода. Этот подход полезен, если приложению требуется настроить код запуска только для нескольких сред с минимальными различиями в коде для каждой среды.

В следующем примере среда хранится в поле _env и управляет выполнением кода в зависимости от среды приложения.

public class Startup
{
    private readonly IWebHostEnvironment _env;

    public Startup(IWebHostEnvironment env)
    {
        _env = env;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else if (_env.IsStaging())
        {
            ...
        }
        else
        {
            ...
        }
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else
        {
            ...
        }

        ...
    }
}

Класс, специфический для Startup среды

Приложение может определить несколько Startup классов для разных сред с соглашением об именовании Startup{EnvironmentName}, где {ENVIRONMENT NAME} — заполнитель для имени среды.

Класс, у которого суффикс имени соответствует текущей среде, получает приоритет. Если соответствующий класс Startup{EnvironmentName} не найден, используется класс Startup.

Чтобы реализовать классы на основе Startup среды, создайте столько Startup{EnvironmentName} классов, сколько необходимо, и резервный Startup класс:

public class StartupDevelopment
{
    ...
}

public class StartupProduction
{
    ...
}

public class Startup
{
    ...
}

Где создается построитель хоста, вызовите HostingAbstractionsWebHostBuilderExtensions.UseStartup, принимающий имя сборки для загрузки правильного класса Startup.

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

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

Методы класса для конкретной Startup среды

Методы Configure и ConfigureServices поддерживают версии формы, специфичные для разных сред, таких как Configure{ENVIRONMENT NAME} и Configure{ENVIRONMENT NAME}Services, где заполнитель {ENVIRONMENT NAME} обозначает имя среды. Если имя соответствующей среды не найдено для именованных методов, используется метод ConfigureServices или Configure соответственно.

public void ConfigureDevelopmentServices(IServiceCollection services)
{
    ...
}

public void ConfigureStagingServices(IServiceCollection services)
{
    ...
}

public void ConfigureProductionServices(IServiceCollection services)
{
    ...
}

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

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

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