ASP.NET Core Web API. Работа с окружением (интерфейс IWebHostEnvironment)

Приложение ASP.NET Core Web API может взаимодействовать со своим окружением, используя свойство Environment класса WebApplication, которое предоставляет сведения об окружении в виде IWebHostEnvironment.

Свойства IWebHostEnvironment

Объект, реализующий IWebHostEnvironment предоставляет нам следующие свойства, позволяющие работать с окружением:

Для демонстрации значений этих свойств, создадим новое приложение ASP.NET Core Web API и добавим в файл Program.cs следующие строки:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
    
    //выводим в лог основную информацию об окружении
    app.Logger.LogInformation($"ApplicationName: {app.Environment.ApplicationName}");
    app.Logger.LogInformation($"ContentRootPath: {app.Environment.ContentRootPath}");
    app.Logger.LogInformation($"EnvironmentName: {app.Environment.EnvironmentName}");
    app.Logger.LogInformation($"WebRootPath: {app.Environment.WebRootPath}");
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

app.Run();

Теперь, после запуска приложения, в консоли мы увидим значения свойств app.Environment:

При этом, если мы запустим наше приложение НЕ из Visual Studio, а просто из проводника Windows, то показанная на рисунке выше информация не появится в консоли, а в строке:

Hosting Environment: ...

мы увидим строку Production вместо Development.  Этот, простой пример, с одной стороны, помогает нам понять, что содержит каждое из свойств в объекта Environment, а, с другой стороны, демонстрирует работу с одним из наиболее часто используемых при разработке Web API свойств IWebHostEnvironment — свойства EnvironmentName. Рассмотрим это свойство более подробно.

Свойство EnvironmentName и методы расширения для IHostEnvironment

Свойство EnvironmentName возвращает имя среды в которой запущено приложение. В зависимости от значения этого свойства приложение ASP.NET Core Web API может изменять своё поведение. По умолчанию, определено три имени среды окружения — это Development, Production и Stagging.

Для проверки значения свойства EnvironmentName используются методы расширения IHostEnvironment:

 Например, в нашем приложении есть такие строки:

if (app.Environment.IsDevelopment())
{
  //здесь код 
}

то есть, мы проверяем, имеет ли текущая среда имя Development и, если имеет, то выполняем какие-либо операции, например, как в нашем случае — в конвейер обработки запросов добавляются компоненты middleware для Swagger, а в лог выводятся значения свойств.

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

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

Чтобы определить имя среду окружения приложение ASP.NET Core действует следующим образом — считывает значение переменной среды ASPNETCORE_ENVIRONMENT при вызове метода WebApplication.CreateBuilder() и записывает полученное значение в свойство EnvironmentName. Если значение ASPNETCORE_ENVIRONMENTне было получено, то, по умолчанию, свойству EnvironmentName устанавливается значение Production. 

В проекте значение переменной ASPNETCORE_ENVIRONMENT устанавливается в файле launchSettings.json, который по умолчанию выглядит следующим образом:

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:44742",
      "sslPort": 44351
    }
  },
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "launchUrl": "swagger",
      "applicationUrl": "http://localhost:5154",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "launchUrl": "swagger",
      "applicationUrl": "https://localhost:7224;http://localhost:5154",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "launchUrl": "swagger",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Здесь нас интересует объект profiles в котором устанавливаются три профиля запуска приложения с именами http, https и IIS Express. Во всех трех случаях переменная ASPNETCORE_ENVIRONMENT содержит значение Development. Мы можем изменить эти значения на свои, например, определим профиль https следующим образом:

"https": {
  "commandName": "Project",
  "dotnetRunMessages": true,
  "launchBrowser": true,
  "launchUrl": "swagger",
  "applicationUrl": "https://localhost:7224;http://localhost:5154",
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Testing"
  }

Теперь запустим приложение и убедимся, что это значение используется приложением:

Второй вариант изменения значения переменной ASPNETCORE_ENVIRONMENT — воспользоваться в Visual Studio пунктом меню: Отладка — Свойства отладки для проекта:

В появившемся окне в удобном виде расположено содержимое профилей запуска из файла launchSettings.json:

Для того, чтобы проверить значение EnvironmentName, если это значение отличается от значение по умолчанию, используется метод расширения IsEnvironment(). Так, например, в нашем случае, чтобы при запуске приложения открывался интерфейс Swagger нам необходимо произвести вот такую проверку имени среду окружения:

if (app.Environment.IsEnvironment("Testing")) //проверяем, что значение EnvironmentName == Testing
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

Следует отдельно отметить, что файл launchSettings.json:

• Используется только на локальном компьютере разработчика.
• Не используется при развертывании приложения.

Если вам необходимо, чтобы при запуске приложения не из Visual Studio переменная ASPNETCORE_ENVIRONMENT имела значение отличное от Production, то можно воспользоваться глобальной настройкой этой переменной в среде Windows.

Глобальная настройка переменной ASPNETCORE_ENVIRONMENT

Чтобы установить значение ASPNETCORE_ENVIRONMENT в Windows 11, можно открыть параметры системы:

Набрать в строке поиска «переменные» и выбрать пункт:

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

После создания переменной среды можно запустить приложение (НЕ из Visual Studio, так как значение переменной будет перезаписано тем значением, которое задано в launchSettings.json) и убедиться, что значение ASPNETCORE_ENVIRONMENT было прочтено:

Также, можно запустить Power Shell с правами администратора и выполнить команду:

setx ASPNETCORE_ENVIRONMENT Staging /M

ключ /M -установит значение переменной на системном уровне. Соответственно, без ключа переменная будет установлена для текущей учётной записи пользователя.

Свойства ContentRootPath и WebRootPath

• ContentRootPath — это свойство, которое указывает на папку в котором содержатся файлы на которых строится приложения.
  • Если вы запустите exe-файл приложения вне Visual Studio, то это свойство будет указывать на папку в которой находится exe-файл приложения, json-файлы с настройками.
  • При запуске приложения в Visual Studio, например, в режиме отладки,ContentRootPath будет указывать на папку в которой находятся исходные файлы приложения (.cs, .cproj и т.д.).
• WebRootPath — это свойство, которое всегда указывает на папку в которой размещаются файлы web-приложения (html, js, css и т.д.). Обычно — это папка wwwroot (хотя, при необходимости, мы можем поменять это значение на любое другое).

Так, если вы создали проект ASP.NET Core Web API, то, по умолчанию в таком приложении папка wwwroot отсутствует и, свойство WebRootPath ничего не содержит. В обозревателе решений Visual Studio пустой проект выглядит следующим образом:

Если мы создадим в корне проекта папку с именем wwwroot, то Visual Studio автоматически распознает этут папку как место хранение файлов web-приложение — вы увидите, что эта папка изменит свою иконку:

Теперь, если снова запустить приложение, то свойство WebRootPath будет указывать на эту папку:

Итого

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