Модуль ASP.NET Core (ANCM) для IIS

  • Статья

Модуль ASP.NET Core (ANCM) — это собственный модуль IIS, который подключается к конвейеру IIS, чтобы приложения ASP.NET Core могли работать со службами IIS. Приложения ASP.NET Core могут выполняться со службами IIS одним из следующих способов:

Каждая из моделей размещения имеет свои преимущества и недостатки. По умолчанию используется модель внутрипроцессного размещения из-за лучшей производительности и диагностики.

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

Установка модуля ASP.NET Core (ANCM)

Модуль ASP.NET Core (ANCM) устанавливается вместе со средой выполнения .NET Core из пакета размещения .NET Core. Модуль ASP.NET Core совместим с выпусками .NET в поддержке.

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

Скачайте установщик по следующей ссылке:

Текущий установщик пакета размещения .NET Core (прямая загрузка)

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

Руководство по публикации приложения ASP.NET Core на сервере IIS см. здесь: Публикация приложения ASP.NET Core в службах IIS.

Модуль ASP.NET Core (ANCM) — это собственный модуль IIS, который подключается к конвейеру IIS для выполнения следующих задач:

Поддерживаемые версии Windows:

  • Windows 7 или более поздней версии.
  • Windows Server 2012 R2 и более поздние версии

При размещении в процессе модуль использует реализацию внутрипроцессного сервера для IIS — HTTP-сервер IIS (IISHttpServer).

При размещении вне процесса модуль работает только с Kestrel. Модуль не работает с HTTP.sys.

Модели размещения

Модель внутрипроцессного размещения

По умолчанию приложения ASP.NET Core используют модель внутрипроцессного размещения.

При внутрипроцессном размещении применимы следующие характеристики:

  • HTTP-сервер IIS (IISHttpServer) используется вместо сервера Kestrel. Для внутрипроцессной обработки CreateDefaultBuilder вызывает UseIIS для выполнения следующих действий:

    • Регистрация IISHttpServer.
    • Настройка порта и базового пути, которые будет прослушивать сервер при выполнении за модулем ASP.NET Core.
    • Настройка перехвата ошибок запуска на узле.

  • Атрибут requestTimeout не применяется к внутрипроцессному размещению.

  • Совместное использование пула приложений среди приложений не поддерживается. Используйте один пул приложений для каждого приложения.

  • При использовании веб-развертывания или размещении файла app_offline.htm в развертывании вручную приложение может не завершить работу сразу при наличии открытого соединения. Например, подключение WebSocket может задерживать завершение работы приложения.

  • Архитектура (разрядность) приложения и установленная среда выполнения (x64 или x86) должны соответствовать архитектуре пула приложений.

  • Обнаружены отключения клиентов. Маркер отмены HttpContext.RequestAborted аннулируется при отключении клиента.

  • В ASP.NET Core 2.2.1 или более ранней версии возвращает рабочий каталог процесса, запущенного службами IIS, GetCurrentDirectory а не каталог приложения (например, C:\Windows\System32\inetsrv для w3wp.exe).

    Пример кода, который задает текущий каталог приложения, см. в разделе Класс CurrentDirectoryHelpers. Вызовите метод SetCurrentDirectory . Последующие вызовы GetCurrentDirectory возвращают каталог приложения.

  • При размещении в процессе AuthenticateAsync не вызывается внутри для инициализации пользователя. Таким образом, реализация IClaimsTransformation, используемая для преобразования утверждений после каждой проверки подлинности, не активируется по умолчанию. При преобразовании утверждений с реализацией IClaimsTransformation вызовите AddAuthentication для добавления служб проверки подлинности:

    public void ConfigureServices(IServiceCollection services)
{
    services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
    services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
}

public void Configure(IApplicationBuilder app)
{
    app.UseAuthentication();
}

Модель размещения вне процесса

Чтобы настроить приложение для размещения вне процесса, задайте значение <AspNetCoreHostingModel> свойства OutOfProcess в файле проекта (.csproj):

<PropertyGroup>
  <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>

Для внутрипроцессного размещения указано значение InProcess, которое является значением по умолчанию.

Значение <AspNetCoreHostingModel> не учитывает регистр, поэтому inprocess и outofprocess являются допустимыми значениями.

Сервер Kestrel используется вместо HTTP-сервера IIS (IISHttpServer).

При размещении вне процесса CreateDefaultBuilder вызывает UseIISIntegration в следующих целях.

  • Настройка порта и базового пути, которые будет прослушивать сервер при выполнении за модулем ASP.NET Core.
  • Настройка перехвата ошибок запуска на узле.

Изменения модели размещения

Если параметр hostingModel изменяется в файле web.config (как описано в разделе Конфигурация с помощью web.config), модуль перезапускает рабочий процесс для служб IIS.

Для IIS Express модуль не перезапускает рабочий процесс, а запускает нормальное завершение работы текущего процесса IIS Express. Следующий запрос для приложения порождает новый процесс IIS Express.

Имя процесса

Process.GetCurrentProcess().ProcessName сообщает w3wp/iisexpress (внутри процесса) или dotnet (вне процесса).

Многие собственные модули, такие как проверка подлинности Windows, остаются активными. Дополнительные сведения о модулях IIS, активных с модулем ASP.NET Core, см. в статье Модули IIS с ASP.NET Core.

Дополнительные возможности модуля ASP.NET Core:

  • Задание переменных среды для рабочего процесса.
  • Внесение в журнал выходных данных stdout для хранилища файлов с целью устранения неполадок при запуске.
  • Переадресация токенов проверки подлинности Windows.

Как установить и использовать модуль ASP.NET Core (ANCM)

Инструкции о том, как установить модуль ASP.NET Core, см. в разделе Установка пакета размещения .NET Core. Модуль ASP.NET Core совместим с выпусками .NET в поддержке.

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

Конфигурация с помощью файла 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 см. в статье Размещение ASP.NET Core в Windows со службами IIS.

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

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

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

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

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

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

 false
forwardWindowsAuthToken

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

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

 true
hostingModel

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

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

 InProcess
inprocess
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 — внутренняя ошибка сервера.

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

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

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

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

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

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

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

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

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

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

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

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

 false
stdoutLogFile

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

Указывает относительный или абсолютный путь к файлу, для которого регистрируются stdout и stderr из процесса, указанного в processPath. Относительные пути задаются относительно корневого каталога веб-сайта. Любой путь, начинающийся с ., относится к корневому каталогу веб-сайта, а все остальные пути рассматриваются как абсолютные пути. Все папки, указанные в пути, создаются модулем при создании файла журнала. С помощью разделителей подчеркивания метка времени, идентификатор процесса и расширение файла (.log) добавляются к последнему сегменту пути журнала stdoutLogFile. Если .\logs\stdout задано значение, пример журнала stdout сохраняется как stdout_20180205194132_1934.log в logs папке при сохранении 2/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 на серверах промежуточных процессов и тестирования, которые недоступны для ненадежных сетей, таких как Интернет.

app_offline.htm

Если файл с именем app_offline.htm обнаружен в корневом каталоге приложения, ASP.NET core Module пытается корректно завершить работу приложения и прекратить обработку входящих запросов. Если приложение по-прежнему выполняется через количество секунд, определенное атрибутом shutdownTimeLimit, модуль ASP.NET Core завершает выполняющийся процесс.

app_offline.htm Пока файл присутствует, модуль ASP.NET Core отвечает на запросы, отправляя обратно содержимое app_offline.htm файла. app_offline.htm После удаления файла следующий запрос запускает приложение.

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

Страница ошибок запуска

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

Если модулю ASP.NET Core не удается найти внутри- или внепроцессный обработчик запросов, откроется страница кода состояния 500.0 — ошибка загрузки внутри- или внепроцессного обработчика запросов.

Если в модели размещения внутри процесса модулю ASP.NET Core не удается запустить приложение, откроется страница кода состояния 500.30 — ошибка запуска.

Если в модели размещения вне процесса модулю ASP.NET Core не удается запустить серверный процесс или начинается серверный процесс, но ему не удается прослушать настроенный порт, появится страница кода состояния 502.5 — ошибка процесса.

Чтобы подавить отображение этой странице и вернуться к странице IIS кода состояния 5xx по умолчанию, используйте атрибут disableStartUpErrorPage. Дополнительные сведения о настройке пользовательских сообщений об ошибках см. в разделе Ошибки HTTP <httpErrors>.

Создание и перенаправление журнала

Модуль ASP.NET Core перенаправляет выходные потоки консоли stdout и stderr на диск, если заданы атрибуты stdoutLogEnabled и stdoutLogFile элемента aspNetCore. Все папки, указанные в пути stdoutLogFile, создаются модулем при создании файла журнала. Пул приложений должен иметь доступ на запись в папку, где записываются журналы (используйте атрибут IIS AppPool\<app_pool_name> для предоставления разрешения на запись).

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

Журнал stdout рекомендуется использовать только для устранения проблем с запуском приложений при размещении в IIS или при использовании поддержки во время разработки для служб IIS в Visual Studio, а не при локальной отладке и выполнении приложения с использованием IIS Express.

Не используйте журнал stdout для ведения общего журнала приложений. Для обычного входа в приложение ASP.NET Core используйте библиотеку ведения журналов, которая ограничивает размер файла журнала и выполняет циклический сдвиг журналов. Дополнительные сведения см. в разделе Сторонние поставщики ведения журналов.

При создании файла журнала автоматически добавляются отметка времени и расширение файла. Имя файла журнала состоит из добавления метки времени, идентификатора процесса и расширения файла (.log) к последнему сегменту stdoutLogFile пути (обычно stdout) с разделителями подчеркивания. stdoutLogFile Если путь заканчиваетсяstdout, в журнале для приложения с piD 1934, созданном 2/5.2018 в 19:42:32, имеется имя stdout_20180205194132_1934.logфайла.

Если stdoutLogEnabled имеет значение false, возникающие при запуске приложения ошибки записываются и передаются в журнал событий (макс. 30 КБ). После запуска все дополнительные журналы удаляются.

В следующем примере элемент aspNetCore настраивает ведение журнала stdout по относительному пути .\log\. Убедитесь, что идентификатор пользователя AppPool имеет разрешение на запись по указанному пути.

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="true"
    stdoutLogFile=".\logs\stdout"
    hostingModel="inprocess">
</aspNetCore>

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

Сведения о создании правил фильтрации журналов см. в разделе Применение правил фильтрации журналов в коде в документации по ведению журналов ASP.NET Core.

Дополнительные сведения о форматах путей см. в разделе Форматы путей к файлам в системах Windows.

Расширенные журналы диагностики

Модуль ASP.NET Core можно настроить. Он позволяет работать с расширенными журналами диагностики. Добавьте элемент <handlerSettings> в элемент <aspNetCore> в web.config. Задайте параметру debugLevel значение TRACE, чтобы обеспечить высокую точность диагностических сведений:

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="false"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="inprocess">
  <handlerSettings>
    <handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
    <handlerSetting name="debugLevel" value="FILE,TRACE" />
  </handlerSettings>
</aspNetCore>

Все папки в пути (logs в предыдущем примере) создаются модулем при создании файла журнала. Пул приложений должен иметь доступ на запись в папку, где записываются журналы (используйте атрибут IIS AppPool\{APP POOL NAME} для предоставления разрешения на запись, где заполнитель {APP POOL NAME} — это имя пула приложений).

Значения уровня отладки (debugLevel) могут включать уровень и расположение.

Уровни (в порядке возрастания степени детализации):

  • ОШИБКА
  • ПРЕДУПРЕЖДЕНИЕ
  • INFO
  • ТРАССИРОВКА

Расположения (допускаются несколько расположений):

  • CONSOLE
  • EVENTLOG
  • ФАЙЛ

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

  • ASPNETCORE_MODULE_DEBUG_FILE: Путь к файлу журнала отладки. (Значение по умолчанию: aspnetcore-debug.log.)
  • ASPNETCORE_MODULE_DEBUG: параметр уровня отладки.

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

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

Пример элемента aspNetCore в файле web.config см. в разделе Конфигурация с помощью файла web.config.

Изменение размера стека

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

Настройте размер управляемого стека, задав для параметра stackSize значение в байтах в web.config. Размер по умолчанию — 1 048 576 байт (1 МБ).

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="false"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="inprocess">
  <handlerSettings>
    <handlerSetting name="stackSize" value="2097152" />
  </handlerSettings>
</aspNetCore>

Конфигурация прокси-сервера использует протокол HTTP и токен связывания

Применяется только к размещению вне процесса.

Прокси-сервер, созданный между модулем ASP.NET Core и Kestrel, использует протокол HTTP. Отсутствует риск перехвата трафика между модулем и Kestrel из расположения за пределами сервера.

Токен связывания гарантирует, что полученные Kestrel запросы были переданы через прокси-сервер IIS, а не из какого-либо другого источника. Этот токен создается и задается модулем в переменную среды (ASPNETCORE_TOKEN). Он также задается в заголовке (MS-ASPNETCORE-TOKEN) каждого запроса, переданного через прокси-сервер. ПО промежуточного слоя IIS проверяет каждый получаемый запрос, чтобы убедиться, что заголовок с токеном связывания соответствует значению переменной среды. Если значения токена не совпадают, запрос заносится в журнал и отклоняется. Переменная среды с токеном связывания и трафик между модулем и Kestrel недоступны из расположения за пределами сервера. Не зная значение токена связывания, злоумышленник не может отправлять запросы, обходящие проверку в ПО промежуточного слоя IIS.

Модуль ASP.NET Core с общей конфигурацией IIS

Программа установки модуля ASP.NET Core запускается с правами учетной записи TrustedInstaller. Так как учетная запись локальной системы не имеет разрешения на изменение пути к общей папке, используемого общей конфигурацией IIS, установщик выдает ошибку отказа в доступе при попытке настроить параметры модуля в файле в applicationHost.config общей папке.

При использовании общей конфигурации IIS на том же компьютере, где установлены службы IIS, запустите установщик пакета размещения ASP.NET Core с параметром OPT_NO_SHARED_CONFIG_CHECK со значением 1:

dotnet-hosting-{VERSION}.exe OPT_NO_SHARED_CONFIG_CHECK=1

Если путь к общей конфигурации не на том же компьютере, где установлены службы IIS, выполните следующие действия.

  1. Отключите общую конфигурацию IIS.
  2. Запустите установщик.
  3. Экспорт обновленного applicationHost.config файла в общую папку.
  4. Повторно включите общую конфигурацию IIS.

Версия модуля и журналы установщика хостинга Bundle

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

  1. В системе размещения перейдите в раздел %windir%\System32\inetsrv.
  2. Найдите файл aspnetcore.dll.
  3. Щелкните правой кнопкой мыши файл и выберите Свойства из контекстного меню.
  4. Перейдите на вкладку "Сведения". Версия файла и версия продукта представляют установленную версию модуля.

Журналы установщика пакета размещения для модуля находятся в папке C:\Users\%UserName%\AppData\Local\Temp. Имя файла — dd_DotNetCoreWinSvrHosting__{TIMESTAMP}_000_AspNetCoreModule_x64.log.

Модуль, схемы и расположение файлов конфигурации

Модуль

IIS (x86/amd64):

  • %windir%\System32\inetsrv\aspnetcore.dll

  • %windir%\SysWOW64\inetsrv\aspnetcore.dll

  • %ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

  • %ProgramFiles(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

IIS Express (x86/amd64):

  • %ProgramFiles%\IIS Express\aspnetcore.dll

  • %ProgramFiles(x86)%\IIS Express\aspnetcore.dll

  • %ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll

  • %ProgramFiles(x86)%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll

Схема

IIS

  • %windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml

  • %windir%\System32\inetsrv\config\schema\aspnetcore_schema_v2.xml

IIS Express

  • %ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml

  • %ProgramFiles%\IIS Express\config\schema\aspnetcore_schema_v2.xml

Настройка

IIS

  • %windir%\System32\inetsrv\config\applicationHost.config

IIS Express

  • Visual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.config

  • CLI iisexpress.exe: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config

Файлы можно найти, выполнив поиск aspnetcore в applicationHost.config файле.

Модуль ASP.NET Core (ANCM) — это собственный модуль IIS, который подключается к конвейеру IIS для выполнения следующих задач:

Поддерживаемые версии Windows:

  • Windows 7 или более поздней версии.
  • Windows Server 2008 R2 или более поздней версии

При размещении в процессе модуль использует реализацию внутрипроцессного сервера для IIS — HTTP-сервер IIS (IISHttpServer).

При размещении вне процесса модуль работает только с Kestrel. Модуль не работает с HTTP.sys.

Модели размещения

Модель внутрипроцессного размещения

Чтобы настроить приложение для внутрипроцессного размещения, добавьте свойство <AspNetCoreHostingModel> к файлу проекта приложения со значением InProcess (размещение вне процесса имеет значение OutOfProcess):

<PropertyGroup>
  <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
</PropertyGroup>

Модель внутрипроцессного размещения не поддерживается для приложений ASP.NET Core, предназначенных для .NET Framework.

Значение <AspNetCoreHostingModel> не учитывает регистр, поэтому inprocess и outofprocess являются допустимыми значениями.

Если свойство <AspNetCoreHostingModel> отсутствует в файле, значение по умолчанию — OutOfProcess.

При внутрипроцессном размещении применимы следующие характеристики:

  • HTTP-сервер IIS (IISHttpServer) используется вместо сервера Kestrel. Для внутрипроцессной обработки CreateDefaultBuilder вызывает UseIIS для выполнения следующих действий:

    • Регистрация IISHttpServer.
    • Настройка порта и базового пути, которые будет прослушивать сервер при выполнении за модулем ASP.NET Core.
    • Настройка перехвата ошибок запуска на узле.

  • Атрибут requestTimeout не применяется к внутрипроцессному размещению.

  • Совместное использование пула приложений среди приложений не поддерживается. Используйте один пул приложений для каждого приложения.

  • При использовании веб-развертывания или размещении файла app_offline.htm в развертывании вручную приложение может не завершить работу сразу при наличии открытого соединения. Например, подключение websocket может задерживать завершение работы приложения.

  • Архитектура (разрядность) приложения и установленная среда выполнения (x64 или x86) должны соответствовать архитектуре пула приложений.

  • Обнаружены отключения клиентов. При отключении клиента происходит отмена токена отмены HttpContext.RequestAborted.

  • В ASP.NET Core 2.2.1 и более ранних версий GetCurrentDirectory возвращает рабочий каталог процесса, запущенного службами IIS, а не каталог приложения (например, C:\Windows\System32\inetsrv для w3wp.exe).

    Пример кода, который задает текущий каталог приложения, см. в разделе Класс CurrentDirectoryHelpers. Вызовите метод SetCurrentDirectory . Последующие вызовы GetCurrentDirectory возвращают каталог приложения.

  • При размещении в процессе AuthenticateAsync не вызывается внутри для инициализации пользователя. Таким образом, реализация IClaimsTransformation, используемая для преобразования утверждений после каждой проверки подлинности, не активируется по умолчанию. При преобразовании утверждений с реализацией IClaimsTransformation вызовите AddAuthentication для добавления служб проверки подлинности:

    public void ConfigureServices(IServiceCollection services)
{
    services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
    services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
}

public void Configure(IApplicationBuilder app)
{
    app.UseAuthentication();
}

Модель размещения вне процесса

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

  • Не указывайте свойство <AspNetCoreHostingModel>. Если свойство <AspNetCoreHostingModel> отсутствует в файле, значение по умолчанию — OutOfProcess.
  • Установите для свойства <AspNetCoreHostingModel> значение OutOfProcess (внутрипроцессное размещение имеет значение InProcess):
<PropertyGroup>
  <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>

Это значение не учитывает регистр, поэтому inprocess и outofprocess являются допустимыми значениями.

Сервер Kestrel используется вместо HTTP-сервера IIS (IISHttpServer).

Для внепроцессной обработки CreateDefaultBuilder вызывает UseIISIntegration для выполнения следующих действий:

  • Настройка порта и базового пути, которые будет прослушивать сервер при выполнении за модулем ASP.NET Core.
  • Настройка перехвата ошибок запуска на узле.

Изменения модели размещения

Если параметр hostingModel изменяется в файле web.config (как описано в разделе Конфигурация с помощью web.config), модуль перезапускает рабочий процесс для служб IIS.

Для IIS Express модуль не перезапускает рабочий процесс, а запускает нормальное завершение работы текущего процесса IIS Express. Следующий запрос для приложения порождает новый процесс IIS Express.

Имя процесса

Process.GetCurrentProcess().ProcessName сообщает w3wp/iisexpress (внутри процесса) или dotnet (вне процесса).

Многие собственные модули, такие как проверка подлинности Windows, остаются активными. Дополнительные сведения о модулях IIS, активных с модулем ASP.NET Core, см. в статье Модули IIS с ASP.NET Core.

Дополнительные возможности модуля ASP.NET Core:

  • Задание переменных среды для рабочего процесса.
  • Внесение в журнал выходных данных stdout для хранилища файлов с целью устранения неполадок при запуске.
  • Переадресация токенов проверки подлинности Windows.

Как установить и использовать модуль ASP.NET Core (ANCM)

Инструкции о том, как установить модуль ASP.NET Core, см. в разделе Установка пакета размещения .NET Core. Модуль ASP.NET Core совместим с выпусками .NET в поддержке.

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

Конфигурация с помощью файла 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 см. в статье Размещение ASP.NET Core в Windows со службами IIS.

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

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

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

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

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

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

 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 — внутренняя ошибка сервера.

 По умолчанию: 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, stdout и stderr для процесса, указанного в атрибуте processPath, перенаправляются к файлу, заданному в атрибуте stdoutLogFile.

 false
stdoutLogFile

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

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

 aspnetcore-stdout

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

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

В следующем примере устанавливаются две переменные среды. 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 на серверах промежуточных процессов и тестирования, которые недоступны для ненадежных сетей, таких как Интернет.

App_offline.htm

Если файл с именем app_offline.htm обнаружен в корневом каталоге приложения, ASP.NET core Module пытается корректно завершить работу приложения и прекратить обработку входящих запросов. Если приложение по-прежнему выполняется через количество секунд, определенное атрибутом shutdownTimeLimit, модуль ASP.NET Core завершает выполняющийся процесс.

app_offline.htm Пока файл присутствует, модуль ASP.NET Core отвечает на запросы, отправляя обратно содержимое app_offline.htm файла. app_offline.htm После удаления файла следующий запрос запускает приложение.

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

Страница ошибок запуска

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

Если модулю ASP.NET Core не удается найти внутри- или внепроцессный обработчик запросов, откроется страница кода состояния 500.0 — ошибка загрузки внутри- или внепроцессного обработчика запросов.

Если в модели размещения внутри процесса модулю ASP.NET Core не удается запустить приложение, откроется страница кода состояния 500.30 — ошибка запуска.

Если в модели размещения вне процесса модулю ASP.NET Core не удается запустить серверный процесс или начинается серверный процесс, но ему не удается прослушать настроенный порт, появится страница кода состояния 502.5 — ошибка процесса.

Чтобы подавить отображение этой странице и вернуться к странице IIS кода состояния 5xx по умолчанию, используйте атрибут disableStartUpErrorPage. Дополнительные сведения о настройке пользовательских сообщений об ошибках см. в разделе Ошибки HTTP <httpErrors>.

Создание и перенаправление журнала

Модуль ASP.NET Core перенаправляет выходные потоки консоли stdout и stderr на диск, если заданы атрибуты stdoutLogEnabled и stdoutLogFile элемента aspNetCore. Все папки, указанные в пути stdoutLogFile, создаются модулем при создании файла журнала. Пул приложений должен иметь доступ на запись в папку, где записываются журналы (используйте атрибут IIS AppPool\{APP POOL NAME} для предоставления разрешения на запись, где заполнитель {APP POOL NAME} — это имя пула приложений).

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

Журнал stdout рекомендуется использовать только для устранения проблем с запуском приложений при размещении в IIS или при использовании поддержки во время разработки для служб IIS в Visual Studio, а не при локальной отладке и выполнении приложения с использованием IIS Express.

Не используйте журнал stdout для ведения общего журнала приложений. Для обычного входа в приложение ASP.NET Core используйте библиотеку ведения журналов, которая ограничивает размер файла журнала и выполняет циклический сдвиг журналов. Дополнительные сведения см. в разделе Сторонние поставщики ведения журналов.

При создании файла журнала автоматически добавляются отметка времени и расширение файла. Имя файла журнала состоит из добавления метки времени, идентификатора процесса и расширения файла (.log) к последнему сегменту stdoutLogFile пути (обычно stdout) с разделителями подчеркивания. stdoutLogFile Если путь заканчиваетсяstdout, в журнале для приложения с piD 1934, созданном 2/5.2018 в 19:42:32, имеется имя stdout_20180205194132_1934.logфайла.

Если stdoutLogEnabled имеет значение false, возникающие при запуске приложения ошибки записываются и передаются в журнал событий (макс. 30 КБ). После запуска все дополнительные журналы удаляются.

В следующем примере элемент aspNetCore настраивает ведение журнала stdout по относительному пути .\log\. Убедитесь в том, что идентификатор пользователя пула приложений имеет разрешение на запись по указанному пути.

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="true"
    stdoutLogFile=".\logs\stdout"
    hostingModel="inprocess">
</aspNetCore>

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

Дополнительные сведения о форматах путей см. в разделе Форматы путей к файлам в системах Windows.

Расширенные журналы диагностики

Модуль ASP.NET Core можно настроить. Он позволяет работать с расширенными журналами диагностики. Добавьте элемент <handlerSettings> в элемент <aspNetCore> в web.config. Задайте параметру debugLevel значение TRACE, чтобы обеспечить высокую точность диагностических сведений:

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="false"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="inprocess">
  <handlerSettings>
    <handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
    <handlerSetting name="debugLevel" value="FILE,TRACE" />
  </handlerSettings>
</aspNetCore>

Папки в пути, предоставленном <handlerSetting> значению (logs в предыдущем примере), не создаются модулем автоматически и должны существовать в развертывании. Пул приложений должен иметь доступ на запись в папку, где записываются журналы (используйте атрибут IIS AppPool\{APP POOL NAME} для предоставления разрешения на запись, где заполнитель {APP POOL NAME} — это имя пула приложений).

Значения уровня отладки (debugLevel) могут включать уровень и расположение.

Уровни (в порядке возрастания степени детализации):

  • ОШИБКА
  • ПРЕДУПРЕЖДЕНИЕ
  • INFO
  • ТРАССИРОВКА

Расположения (допускаются несколько расположений):

  • CONSOLE
  • EVENTLOG
  • ФАЙЛ

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

  • ASPNETCORE_MODULE_DEBUG_FILE: Путь к файлу журнала отладки. (Значение по умолчанию: aspnetcore-debug.log.)
  • ASPNETCORE_MODULE_DEBUG: параметр уровня отладки.

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

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

Пример элемента aspNetCore в файле web.config см. в разделе Конфигурация с помощью файла web.config.

Конфигурация прокси-сервера использует протокол HTTP и токен связывания

Применяется только к размещению вне процесса.

Прокси-сервер, созданный между модулем ASP.NET Core и Kestrel, использует протокол HTTP. Отсутствует риск перехвата трафика между модулем и Kestrel из расположения за пределами сервера.

Токен связывания гарантирует, что полученные Kestrel запросы были переданы через прокси-сервер IIS, а не из какого-либо другого источника. Этот токен создается и задается модулем в переменную среды (ASPNETCORE_TOKEN). Он также задается в заголовке (MS-ASPNETCORE-TOKEN) каждого запроса, переданного через прокси-сервер. ПО промежуточного слоя IIS проверяет каждый получаемый запрос, чтобы убедиться, что заголовок с токеном связывания соответствует значению переменной среды. Если значения токена не совпадают, запрос заносится в журнал и отклоняется. Переменная среды с токеном связывания и трафик между модулем и Kestrel недоступны из расположения за пределами сервера. Не зная значение токена связывания, злоумышленник не может отправлять запросы, обходящие проверку в ПО промежуточного слоя IIS.

Модуль ASP.NET Core с общей конфигурацией IIS

Установщик основных модулей ASP.NET запускается с привилегиями учетной TrustedInstaller записи. Так как учетная запись локальной системы не имеет разрешения на изменение пути к общей папке, используемого общей конфигурацией IIS, установщик выдает ошибку отказа в доступе при попытке настроить параметры модуля в файле в applicationHost.config общей папке.

При использовании общей конфигурации IIS на том же компьютере, где установлены службы IIS, запустите установщик пакета размещения ASP.NET Core с параметром OPT_NO_SHARED_CONFIG_CHECK со значением 1:

dotnet-hosting-{VERSION}.exe OPT_NO_SHARED_CONFIG_CHECK=1

Если путь к общей конфигурации не на том же компьютере, где установлены службы IIS, выполните следующие действия.

  1. Отключите общую конфигурацию IIS.
  2. Запустите установщик.
  3. Экспорт обновленного applicationHost.config файла в общую папку.
  4. Повторно включите общую конфигурацию IIS.

Версия модуля и журналы установщика хостинга Bundle

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

  1. В системе размещения перейдите в раздел %windir%\System32\inetsrv.
  2. Найдите файл aspnetcore.dll.
  3. Щелкните правой кнопкой мыши файл и выберите Свойства из контекстного меню.
  4. Перейдите на вкладку "Сведения". Версия файла и версия продукта представляют установленную версию модуля.

Журналы установщика пакета размещения для модуля находятся в папке C:\\Users\\%UserName%\\AppData\\Local\\Temp. Файл имеет имя dd_DotNetCoreWinSvrHosting__\{TIMESTAMP}_000_AspNetCoreModule_x64.log, где заполнитель {TIMESTAMP} — это метка времени.

Модуль, схемы и расположение файлов конфигурации

Модуль

IIS (x86/amd64):

  • %windir%\System32\inetsrv\aspnetcore.dll

  • %windir%\SysWOW64\inetsrv\aspnetcore.dll

  • %ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

  • %ProgramFiles(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll

IIS Express (x86/amd64):

  • %ProgramFiles%\IIS Express\aspnetcore.dll

  • %ProgramFiles(x86)%\IIS Express\aspnetcore.dll

  • %ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll

  • %ProgramFiles(x86)%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll

Схема

IIS

  • %windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml

  • %windir%\System32\inetsrv\config\schema\aspnetcore_schema_v2.xml

IIS Express

  • %ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml

  • %ProgramFiles%\IIS Express\config\schema\aspnetcore_schema_v2.xml

Настройка

IIS

  • %windir%\System32\inetsrv\config\applicationHost.config

IIS Express

  • Visual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.config

  • CLI iisexpress.exe: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config

Файлы можно найти, выполнив поиск aspnetcore в applicationHost.config файле.

Модуль ASP.NET Core (ANCM) — это собственный модуль IIS, который подключается к конвейеру IIS для переадресации веб-запросов в серверные приложения ASP.NET Core.

Поддерживаемые версии Windows:

  • Windows 7 или более поздней версии.
  • Windows Server 2008 R2 или более поздней версии

Модуль работает только с Kestrel. Модуль несовместим с HTTP.sys.

Так как приложения ASP.NET Core выполняются в процессе, отделенном от рабочего процесса IIS, этот модуль также обрабатывает управление процессами. Модуль запускает процесс для приложения ASP.NET Core при поступлении первого запроса и перезапускает приложение при сбое. Это, по сути, совпадает с поведением приложений ASP.NET 4.x, выполняемых внутрипроцессно в IIS и управляемых службой активации процессов Windows (WAS).

На следующей схеме показана связь между IIS, модулем ASP.NET Core и приложением:

ASP.NET Core Module

Запросы поступают из Интернета в драйвер HTTP.sys в режиме ядра. Драйвер направляет запросы к службам IIS на настроенный порт веб-сайта — обычно 80 (HTTP) или 443 (HTTPS). Модуль перенаправляет запросы к Kestrel на случайный порт для приложения, который не является портом 80 или 443.

Модуль задает порт с помощью переменной среды во время запуска, а ПО промежуточного слоя для интеграции IIS настраивает сервер для прослушивания http://localhost:{port}. Выполняются дополнительные проверки, и запросы не из модуля отклоняются. Модуль не поддерживает переадресацию по HTTPS, поэтому запросы переадресовываются по протоколу HTTP, даже если были получены IIS по протоколу HTTPS.

После того, как Kestrel получает запрос от модуля, запрос передается в конвейер ПО промежуточного слоя ASP.NET Core. Конвейер ПО промежуточного слоя обрабатывает запрос и передает его в качестве экземпляра HttpContext в логику приложения. ПО промежуточного слоя, добавленное с использованием интеграции IIS, обновляет схему, удаленный IP-адрес и базовый путь с учетом перенаправления запроса к Kestrel. Отклик приложения передается обратно в службу IIS, которая отправляет его обратно в HTTP-клиент, инициировавший запрос.

Многие собственные модули, такие как проверка подлинности Windows, остаются активными. Дополнительные сведения о модулях IIS, активных с модулем ASP.NET Core, см. в статье Модули IIS с ASP.NET Core.

Дополнительные возможности модуля ASP.NET Core:

  • Задание переменных среды для рабочего процесса.
  • Внесение в журнал выходных данных stdout для хранилища файлов с целью устранения неполадок при запуске.
  • Переадресация токенов проверки подлинности Windows.

Как установить и использовать модуль ASP.NET Core (ANCM)

Инструкции о том, как установить модуль ASP.NET Core, см. в разделе Установка пакета размещения .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>
  <system.webServer>
    <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
    </handlers>
    <aspNetCore processPath="dotnet"
                arguments=".\MyApp.dll"
                stdoutLogEnabled="false"
                stdoutLogFile=".\logs\stdout" />
  </system.webServer>
</configuration>

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

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

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

Сведения о конфигурации дочерних приложений IIS см. в статье Размещение ASP.NET Core в Windows со службами IIS.

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

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

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

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

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

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

 false
forwardWindowsAuthToken

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

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

 true
processesPerApplication

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

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

Параметр 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 указывается в часах, минутах и секундах.

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

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

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

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

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

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

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

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

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

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

 false
stdoutLogFile

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

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

 aspnetcore-stdout

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

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

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

Переменные среды, заданные в этом разделе, конфликтуют с переменными системной среды с такими же именами. Если переменная среды задана и в файле web.config, и на уровне системы в Windows, значение из файла web.config добавляется к значению переменной системной среды (например, ASPNETCORE_ENVIRONMENT: Development;Development), которая препятствует запуску приложения.

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

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile="\\?\%home%\LogFiles\stdout">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
    <environmentVariable name="CONFIG_DIR" value="f:\application_config" />
  </environmentVariables>
</aspNetCore>

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

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

App_offline.htm

Если файл с именем app_offline.htm обнаружен в корневом каталоге приложения, ASP.NET core Module пытается корректно завершить работу приложения и прекратить обработку входящих запросов. Если приложение по-прежнему выполняется через количество секунд, определенное атрибутом shutdownTimeLimit, модуль ASP.NET Core завершает выполняющийся процесс.

app_offline.htm Пока файл присутствует, модуль ASP.NET Core отвечает на запросы, отправляя обратно содержимое app_offline.htm файла. app_offline.htm После удаления файла следующий запрос запускает приложение.

Страница ошибок запуска

Если модулю ASP.NET Core не удается запустить серверный процесс или начинается серверный процесс, но ему не удается прослушать настроенный порт, появится страница кода состояния 502.5 — ошибка процесса. Чтобы подавить эту страницу и вернуться к странице IIS кода состояния 502 по умолчанию, используйте атрибут disableStartUpErrorPage. Дополнительные сведения о настройке пользовательских сообщений об ошибках см. в разделе Ошибки HTTP <httpErrors>.

Создание и перенаправление журнала

Модуль ASP.NET Core перенаправляет выходные потоки консоли stdout и stderr на диск, если заданы атрибуты stdoutLogEnabled и stdoutLogFile элемента aspNetCore. Все папки, указанные в пути stdoutLogFile, создаются модулем при создании файла журнала. Пул приложений должен иметь доступ на запись в папку, где записываются журналы (используйте атрибут IIS AppPool\<app_pool_name> для предоставления разрешения на запись).

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

Журнал stdout рекомендуется использовать только для устранения проблем с запуском приложений при размещении в IIS или при использовании поддержки во время разработки для служб IIS в Visual Studio, а не при локальной отладке и выполнении приложения с использованием IIS Express.

Не используйте журнал stdout для ведения общего журнала приложений. Для обычного входа в приложение ASP.NET Core используйте библиотеку ведения журналов, которая ограничивает размер файла журнала и выполняет циклический сдвиг журналов. Дополнительные сведения см. в разделе Сторонние поставщики ведения журналов.

При создании файла журнала автоматически добавляются отметка времени и расширение файла. Имя файла журнала составляется путем добавления метки времени, идентификатора процесса и расширения файла (.log) к последнему сегменту атрибута пути stdoutLogFile (обычно stdout) с символами подчеркивания в качестве разделителей. Если атрибут пути stdoutLogFile заканчивается элементом stdout, журнал приложения с идентификатором 1934, созданный 5 февраля 2018 г. в 19:42:32, будет иметь имя stdout_20180205194132_1934.log.

В следующем примере элемент aspNetCore настраивает ведение журнала stdout по относительному пути .\log\. Убедитесь, что идентификатор пользователя AppPool имеет разрешение на запись по указанному пути.

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="true"
    stdoutLogFile=".\logs\stdout">
</aspNetCore>

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

Сведения о создании правил фильтрации журналов см. в разделе Применение правил фильтрации журналов в коде в документации по ведению журналов ASP.NET Core.

Дополнительные сведения о форматах путей см. в разделе Форматы путей к файлам в системах Windows.

Конфигурация прокси-сервера использует протокол HTTP и токен связывания

Прокси-сервер, созданный между модулем ASP.NET Core и Kestrel, использует протокол HTTP. Отсутствует риск перехвата трафика между модулем и Kestrel из расположения за пределами сервера.

Токен связывания гарантирует, что полученные Kestrel запросы были переданы через прокси-сервер IIS, а не из какого-либо другого источника. Этот токен создается и задается модулем в переменную среды (ASPNETCORE_TOKEN). Он также задается в заголовке (MS-ASPNETCORE-TOKEN) каждого запроса, переданного через прокси-сервер. ПО промежуточного слоя IIS проверяет каждый получаемый запрос, чтобы убедиться, что заголовок с токеном связывания соответствует значению переменной среды. Если значения токена не совпадают, запрос заносится в журнал и отклоняется. Переменная среды с токеном связывания и трафик между модулем и Kestrel недоступны из расположения за пределами сервера. Не зная значение токена связывания, злоумышленник не может отправлять запросы, обходящие проверку в ПО промежуточного слоя IIS.

Модуль ASP.NET Core с общей конфигурацией IIS

Программа установки модуля ASP.NET Core запускается с правами учетной записи TrustedInstaller. Поскольку учетная запись локальной системы не имеет разрешения на изменение пути к общей папке, используемого общей конфигурацией IIS, установщик получает ошибку отказа в доступе при попытке настроить параметры модуля в файле applicationHost.config общей папки.

При использовании общей конфигурации IIS выполните следующие действия.

  1. Отключите общую конфигурацию IIS.
  2. Запустите установщик.
  3. Экспортируйте обновленный файл applicationHost.config в общую папку.
  4. Повторно включите общую конфигурацию IIS.

Версия модуля и журналы установщика хостинга Bundle

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

  1. В системе размещения перейдите к папке %windir%\System32\inetsrv.
  2. Найдите файл aspnetcore.dll.
  3. Щелкните правой кнопкой мыши файл и выберите Свойства из контекстного меню.
  4. Перейдите на вкладку "Сведения". Версия файла и версия продукта представляют установленную версию модуля.

Журналы установщика пакета размещения для модуля находятся в папке C:\Users\%UserName%\AppData\Local\Temp. Имя файла — dd_DotNetCoreWinSvrHosting__<метка_времени>_000_AspNetCoreModule_x64.log.

Модуль, схемы и расположение файлов конфигурации

Модуль

IIS (x86/amd64):

  • %windir%\System32\inetsrv\aspnetcore.dll

  • %windir%\SysWOW64\inetsrv\aspnetcore.dll

IIS Express (x86/amd64):

  • %ProgramFiles%\IIS Express\aspnetcore.dll

  • %ProgramFiles(x86)%\IIS Express\aspnetcore.dll

Схема

IIS

  • %windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml

IIS Express

  • %ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml

Настройка

IIS

  • %windir%\System32\inetsrv\config\applicationHost.config

IIS Express

  • Visual Studio: {КОРЕНЬ ПРИЛОЖЕНИЯ}\.vs\config\applicationHost.config

  • iisexpress.exe CLI: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config

Файлы можно найти путем поиска aspnetcore в файле applicationHost.config.

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