Файл web.config

  • Статья

web.config — это файл, который считывается службами IIS и модулем ASP.NET Core для настройки приложения, размещенного в службах IIS.

Расположение файла web.config

Для корректной настройки модуля ASP.NET Core необходимо наличие файла web.config в корневой папке содержимого развертываемого приложения (как правило, это основной путь приложения). Это расположение соответствует физическому пути веб-сайта, указанному в службах IIS. Файл web.config требуется в корне приложения, чтобы включить публикацию нескольких приложений с помощью веб-развертывания.

По физическому пути приложения находятся файлы с конфиденциальной информацией, например, {ASSEMBLY}.runtimeconfig.json, {ASSEMBLY}.xml (комментарии к XML-документации) и {ASSEMBLY}.deps.json, где заполнитель {ASSEMBLY} представляет собой имя сборки. web.config Когда файл присутствует и сайт запускается обычно, службы IIS не обслуживает эти конфиденциальные файлы, если они запрашиваются. web.config Если файл отсутствует, неправильно назван или не удается настроить сайт для нормального запуска, службы IIS могут предоставлять конфиденциальные файлы общедоступным образом.

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

Если в проекте нет файла web.config, он создается с правильными processPath и arguments для настройки модуля ASP.NET Core и переносится в опубликованные выходные данные.

web.config Если файл присутствует в проекте, файл преобразуется правильно и arguments настраивается processPath ASP.NET основной модуль и перемещается в опубликованные выходные данные. Преобразование не изменяет параметры конфигурации служб IIS, включенные в файл.

Файл web.config может предоставить дополнительные параметры конфигурации IIS, которые управляют активными модулями IIS. Сведения о модулях IIS, которые могут обрабатывать запросы к приложениям ASP.NET Core, см. в статье Модули IIS.

Создание, преобразование и публикация web.config файла обрабатывается целевым объектом MSBuild (_TransformWebConfig) при публикации проекта. Этот целевой объект присутствует в целевых веб-пакетах SDK (Microsoft.NET.Sdk.Web). Пакет SDK задается в начале файла проекта:

<Project Sdk="Microsoft.NET.Sdk.Web">

Чтобы веб-пакет SDK не преобразовывал файл web.config, используйте свойство <IsTransformWebConfigDisabled> в файле проекта:

<PropertyGroup>
  <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
</PropertyGroup>

При отключении веб-пакета SDK от преобразования файла processPath необходимо arguments вручную задать разработчиком. Дополнительные сведения см. в разделе Модуль ASP.NET Core для IIS.

Настройка модуля ASP.NET Core с помощью web.config

Модуль ASP.NET Core настроен с aspNetCore разделом system.webServer узла в файле сайта web.config .

Следующий файл web.config публикуется для зависимого от платформы развертывания и настраивает модуль ASP.NET Core для обработки запросов к сайту.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet"
                  arguments=".\MyApp.dll"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

Следующий файл web.config опубликован для автономного развертывания.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath=".\MyApp.exe"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

Значение false свойства InheritInChildApplications указывает, что параметры, заданные в элементе <location>, не наследуются приложениями, которые находятся во вложенном каталоге приложения.

Когда приложение развернуто в службе приложений Azure, путь stdoutLogFile задан как \\?\%home%\LogFiles\stdout. Путь сохраняет журналы stdout в LogFiles папку, которая является автоматически созданным службой расположением.

Сведения о конфигурации дочерних приложений IIS см. в разделе Расширенные конфигурации.

Атрибуты элемента aspNetCore

Атрибут Description По умолч.
arguments

Необязательный строковый атрибут.

Аргументы исполняемого файла, указанного в processPath.
disableStartUpErrorPage

Дополнительный логический атрибут.

Если значение равно true, страница 502.5 — ошибка процесса подавляется, и страница с кодом состояния 502, настроенная в web.config, имеет более высокий приоритет.

 false
forwardWindowsAuthToken

Дополнительный логический атрибут.

Если значение равно true, маркер безопасности отправляется дочернему процессу, прослушивающему порт %ASPNETCORE_PORT%, как заголовок MS-ASPNETCORE-WINAUTHTOKEN каждого запроса. Этот процесс вызывает CloseHandle по этому маркеру безопасности каждого запроса.

 true
hostingModel

Необязательный строковый атрибут.

Указывает модель размещения — внутри процесса (InProcess/inprocess) или вне процесса (OutOfProcess/outofprocess).

 OutOfProcess/outofprocess при отсутствии
processesPerApplication

Необязательный целочисленный атрибут.

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

†Для внутрипроцессного размещения установлено ограничение 1.

Параметр processesPerApplication не рекомендуется. Этот атрибут будет удален в будущем выпуске.

 По умолчанию: 1
Минимум: 1
Максимальное значение: 100†
processPath

Обязательный строковый атрибут.

Путь к исполняемому файлу, который запускает процесс прослушивания HTTP-запросов. Поддерживаются относительные пути. Если путь начинается с ., то начало пути считается относительно корневого каталога веб-сайта.
rapidFailsPerMinute

Необязательный целочисленный атрибут.

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

Не поддерживается для внутрипроцессного размещения.

 По умолчанию: 10
Минимум: 0
Максимум: 100
requestTimeout

Необязательный атрибут timespan.

Указывает продолжительность, на протяжении которой модуль ASP.NET Core ожидает ответа от процесса, прослушивающего порт %ASPNETCORE_PORT%.

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

Не применяется к внутрипроцессному размещению. Для внутрипроцессного размещения модуль ожидает, пока приложение не обработает запрос.

Допустимые значения для сегментов минут и секунд в строках находятся в диапазоне 0–59. Использование значения 60 для минут и секунд приведет к ошибке 500 — Internal Server Error (внутренняя ошибка сервера).

 По умолчанию: 00:02:00
Минимум: 00:00:00
Максимум: 360:00:00
shutdownTimeLimit

Необязательный целочисленный атрибут.

Длительность в секундах, когда модуль ожидает правильного завершения работы исполняемого файла при обнаружении app_offline.htm файла.

 По умолчанию: 10
Минимум: 0
Максимум: 600
startupTimeLimit

Необязательный целочисленный атрибут.

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

Внутрипроцессное размещение. Процесс не перезапускается и не использует параметр rapidFailsPerMinute.

Внепроцессное размещение. Модуль пытается перезапустить процесс, когда он получает новый запрос, и продолжает попытки перезапустить процесс при последующих входящих запросах, если только приложению не удастся запустится определенное количество раз (rapidFailsPerMinute) за последнюю минуту.

Значение 0 (ноль) не считается бесконечным временем ожидания.

 По умолчанию: 120
Минимум: 0
Максимум: 3600
stdoutLogEnabled

Дополнительный логический атрибут.

Если значение true, а stderr для процесса, stdout указанного вprocessPath, перенаправляется в файл, указанный в stdoutLogFile.

 false
stdoutLogFile

Необязательный строковый атрибут.

Указывает относительный или абсолютный путь к файлу, для которого stdout и stderr из процесса, указанного в processPath журнале. Относительные пути задаются относительно корневого каталога веб-сайта. Любой путь, начинающийся с ., относится к корневому каталогу веб-сайта, а все остальные пути рассматриваются как абсолютные пути. Все папки, указанные в пути, создаются модулем при создании файла журнала. Использование разделителей подчеркивания, метки времени, идентификатора процесса и расширения файла (.log) добавляются в последний сегмент stdoutLogFile пути. Если в качестве значения задано значение .\logs\stdout, например, журнал stdout сохраняется как stdout_20180205194132_1934.log в папке logs с датой 5 февраля 2018 г. в 19:41:32 с идентификатором процесса 1934.

 aspnetcore-stdout

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

Переменные среды для процесса можно указать в атрибуте processPath. Укажите переменную среды с дочерним элементом <environmentVariable> элемента коллекции <environmentVariables>. Переменные среды, установленные в этом разделе, имеют приоритет над переменными системной среды.

В приведенном ниже примере устанавливаются две переменные среды в web.config. ASPNETCORE_ENVIRONMENT настраивает среду приложения для Development. Разработчик может временно задать это значение в файле web.config, чтобы принудительно загрузить страницу исключений для разработчиков при отладке исключения приложения. CONFIG_DIR — пример пользовательской переменной среды, где разработчик написал код, который считывает значение при запуске, чтобы сформировать путь для загрузки файла конфигурации приложения.

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile=".\logs\stdout"
      hostingModel="inprocess">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
    <environmentVariable name="CONFIG_DIR" value="f:\application_config" />
  </environmentVariables>
</aspNetCore>

Примечание.

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

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

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

Установите только переменную среды ASPNETCORE_ENVIRONMENT для Development на серверах промежуточных процессов и тестирования, которые недоступны для ненадежных сетей, таких как Интернет.

Настройка служб IIS с помощью web.config

Конфигурация IIS зависит от <system.webServer> раздела web.config сценариев IIS, которые работают для приложений ASP.NET Core с помощью модуля ASP.NET Core. Например, конфигурация IIS работает для динамического сжатия. Если службы IIS настроены на уровне сервера для использования динамического сжатия, <urlCompression> элемент в файле приложения web.config может отключить его для приложения ASP.NET Core.

Дополнительные сведения см. в следующих разделах:

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

Разделы конфигурации web.config

Разделы конфигурации приложений web.config ASP.NET 4.x не используются приложениями ASP.NET Core для настройки:

  • <system.web>
  • <appSettings>
  • <connectionStrings>
  • <location>

Для настройки приложений ASP.NET Core используются другие поставщики конфигураций. Дополнительные сведения см. в статье Конфигурация.

Преобразование web.config

Если вам нужно преобразовать web.config при публикации, см. статью Преобразование web.config. Возможно, вам потребуется выполнить преобразование web.config при публикации, чтобы задать переменные среды на основе конфигурации, профиля или среды.

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