IWebHostEnvironment и окружение

Данное руководство устарело. Актуальное руководство: Руководство по ASP.NET Core 7

Для взаимодействия со средой, в которой запущено приложение, применяются объекты, реализующие интерфейс IHostingEnvironment. Этот интерфейс предлагает ряд свойств, с помощью которых мы можем получить информацию об окружении:

• ApplicationName: возвращает имя приложения

• EnvironmentName: возвращает описание среды, в которой хостируется приложение

• ContentRootPath: возвращает путь к корневой папке приложения

• WebRootPath: возвращает путь к папке, в которой хранится статический контент приложения, как правило, это папка wwwroot

• ContentRootFileProvider: возвращает реализацию интерфейса Microsoft.AspNetCore.FileProviders.IFileProvider, которая может использоваться для чтения файлов из папки ContentRootPath

• WebRootFileProvider: возвращает реализацию интерфейса Microsoft.AspNetCore.FileProviders.IFileProvider, которая может использоваться для чтения файлов из папки WebRootPath

При разработке мы можем использовать эти свойства. Но наиболее часто при разработке придется сталкиваться со свойством EnvironmentName. По умолчанию имеются три варианта значений для этого свойства: Development, Staging и Production. В проекте это свойство задается через установку переменной среды ASPNETCORE_ENVIRONMENT. Ее текущее значение можно посмотреть в свойствах проекта на вкладке Debug:

Здесь же также можно изменить значение этой переменной.

Кроме того, в проекте в папке Properties есть файл launchSettings.json, который также содержит описания переменных сред:

{
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:58666",
      "sslPort": 0
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "HelloApp": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Здесь можно увидеть, что переменная "ASPNETCORE_ENVIRONMENT" встречается два раза - для запуска через IISExpress и для запуска через Kestrel. В обоих случаях она имеет значение Development. Здесь мы также можем поменять значение этой переменной. Причем файл launchSettings.json переопределяет настройки проекта. Например, если в launchSettings.json мы определим "ASPNETCORE_ENVIRONMENT": "Production", то имя среды нашего проекта будет "Production", хотя в настройках проекта может стоять "Development".

Для определения значения этой переменной для интерфейса IWebHostEnvironment определены специальные методы расширения:

• IsEnvironment(string envName): возвращает true, если имя среды равно значению параметра envName

• IsDevelopment(): возвращает true, если имя среды - Development

• IsStaging(): возвращает true, если имя среды - Staging

• IsProduction(): возвращает true, если имя среды - Production

Например, при создании нового проекта в методе Configure() класса Startup можно найти следующие строки:

if (env.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}

Таким образом, если имя среды имеет значение "Development", то есть приложение находится в состоянии разработки, то при ошибке разработчик увидит детальное описание ошибки. Если же приложение развернуто на хостинге и соответственно имеет другое имя хостирующей среды, то простой пользователь при ошибке ничего не увидит. Таким образом, в зависимости от стадии, на которой находится проект, мы можем скрывать или задействовать часть функционала приложения.

Определение своих состояний среды

Хотя по умолчанию среда может принимать три состояния: Development, Staging, Production, но мы можем при желании вводить новые значения. Например, нам надо отслеживать какие-то дополнительные состояния. К примеру, изменим в файле launchSettings.json значение "ASPNETCORE_ENVIRONMENT" на "Test" (значение может быть произвольное):

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:58666",
      "sslPort": 0
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "Login": "Tom",
        "ASPNETCORE_ENVIRONMENT": "Test"
      }
    },
    "HelloApp": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Test"
      },
      "applicationUrl": "http://localhost:5000"
    }
  }
}

Далее мы можем использовать это состояния для выполнения различных действий. Например, используем состояние "Test" в классе Startup:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Hosting;

namespace HelloApp
{
    public class Startup
    {
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            app.Run(async (context) =>
            {
                context.Response.Headers["Content-Type"] = "text/html; charset=utf-8";
				
                if (env.IsEnvironment("Test")) // Если проект в состоянии "Test"
                {
                    await context.Response.WriteAsync("В состоянии тестирования");
                }
                else
                {
                    await context.Response.WriteAsync("В процессе разработки или в продакшене");
                }
            });
        }
    }
}