Módulo do ASP.NET Core (ANCM) para IIS

Artigo
11/30/2023

Observação

Esta não é a versão mais recente deste artigo. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Aviso

Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, confira .NET e a Política de Suporte do .NET Core. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Importante

Essas informações relacionam-se ao produto de pré-lançamento, que poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

O ANCM (Módulo ASP.NET Core) é um módulo nativo do IIS que se conecta ao pipeline do IIS, permitindo que os aplicativos do ASP.NET Core funcionem com o IIS. Execute os aplicativos do ASP.NET Core com o IIS:

Hospedar um aplicativo ASP.NET Core dentro do processo de trabalho do IIS (w3wp.exe), chamado o modelo de hospedagem no processo.
Encaminhar solicitações da Web a um aplicativo ASP.NET Core de back-end que executa o servidor Kestrel, chamado o modelo de hospedagem de fora do processo.

Há compensações entre cada modelo de hospedagem. Por padrão, o modelo de hospedagem em processo é usado devido a um melhor desempenho e diagnóstico.

Para obter mais informações e orientação sobre a configuração, consulte os seguintes tópicos:

Implementações de servidor Web em ASP.NET Core

Instalar o ANCM (Módulo do ASP.NET Core)

O ANCM (Módulo do ASP.NET Core) é instalado com o Runtime do .NET Core do Pacote de Hospedagem do .NET Core. O Módulo do ASP.NET Core é compatível com versões do .NET incluídas no suporte anteriores e posteriores.

Alterações interruptivas e avisos de segurança são relatados no repositório Comunicados. Os comunicados podem ser limitados a uma versão específica selecionando um filtro Rótulo.

Baixe o instalador usando o seguinte link:

Instalador de pacote de hospedagem do .NET Core atual (download direto)

Para obter mais informações, incluindo a instalação de uma versão anterior do módulo, confira Pacote de hospedagem.

Para ter uma experiência de tutorial sobre como publicar um aplicativo ASP.NET Core em um servidor do IIS, consulte Publicar um aplicativo ASP.NET Core no IIS.

O ANCM (Módulo do ASP.NET Core) é um módulo nativo do IIS que se conecta ao pipeline do IIS para:

Hospedar um aplicativo ASP.NET Core dentro do processo de trabalho do IIS (w3wp.exe), chamado o modelo de hospedagem no processo.
Encaminhar solicitações da Web a um aplicativo ASP.NET Core de back-end que executa o servidor Kestrel, chamado o modelo de hospedagem de fora do processo.

Versões do Windows com suporte:

Windows 7 ou posterior
Windows Server 2012 R2 ou versões posteriores

Ao fazer uma hospedagem em processo, o módulo usa uma implementação de servidor em processo do IIS, chamado Servidor HTTP do IIS (IISHttpServer).

Ao hospedar de fora do processo, o módulo só funciona com o Kestrel. O módulo não funciona com HTTP.sys.

Modelos de hospedagem

Modelo de hospedagem em processo

Os aplicativos do ASP.NET Core assumem como padrão o modelo de hospedagem em processo.

As seguintes características se aplicam ao hospedar em processo:

O servidor HTTP do IIS (IISHttpServer) é usado em vez do servidor Kestrel. Em processo, CreateDefaultBuilder chama UseIIS para:
- Registrar o IISHttpServer.
- Configurar a porta e o caminho base nos quais o servidor deve escutar ao ser executado por trás do Módulo do ASP.NET Core.
- Configurar o host para capturar erros de inicialização.
O requestTimeout atributo não se aplica à hospedagem em processo.
Não há suporte para o compartilhamento do pool de aplicativos entre aplicativos. Use um pool de aplicativos por aplicativo.
Ao usar a Implantação da Web ou inserir manualmente um arquivo app_offline.htm na implantação, o aplicativo talvez não seja desligado imediatamente se houver uma conexão aberta. Por exemplo, uma conexão WebSocket pode atrasar o desligamento do aplicativo.
A arquitetura (número de bit) do aplicativo e o runtime instalado (x64 ou x86) devem corresponder à arquitetura do pool de aplicativos.
As desconexões do cliente são detectadas. O token de cancelamento HttpContext.RequestAborted é cancelado quando o cliente se desconecta.
No ASP.NET Core 2.2.1 ou anterior, GetCurrentDirectory retorna o diretório de trabalho do processo iniciado pelo IIS em vez de o diretório do aplicativo (por exemplo, C:\Windows\System32\inetsrv para w3wp.exe).

Para obter o código de exemplo que define o diretório atual do aplicativo, confira a classe CurrentDirectoryHelpers. Chame o método SetCurrentDirectory . As chamadas seguintes a GetCurrentDirectory fornecem o diretório do aplicativo.
Ao hospedar em processo, AuthenticateAsync não é chamado internamente para inicializar um usuário. Portanto, uma implementação IClaimsTransformation usada para transformar as declarações após cada autenticação não é ativada por padrão. Quando a transformação de declarações com uma implementação IClaimsTransformation, chame AddAuthentication para adicionar serviços de autenticação:
```
public void ConfigureServices(IServiceCollection services)
{
    services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
    services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
}

public void Configure(IApplicationBuilder app)
{
    app.UseAuthentication();
}
```
- Não há suporte para implantações de implantar (arquivo único).

Modelo de hospedagem de fora do processo

Para configurar um aplicativo para hospedagem fora do processo, defina o valor da propriedade <AspNetCoreHostingModel> como OutOfProcess no arquivo de projeto (.csproj):

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

A hospedagem em processo é definida com InProcess, que é o valor padrão.

O valor de <AspNetCoreHostingModel> não diferencia maiúsculas de minúsculas, portanto, inprocess e outofprocess são valores válidos.

O servidor Kestrel é usado, em vez do servidor HTTP do IIS (IISHttpServer).

Fora do processo, CreateDefaultBuilder chama UseIISIntegration para:

Configurar a porta e o caminho base nos quais o servidor deve escutar ao ser executado por trás do Módulo do ASP.NET Core.
Configurar o host para capturar erros de inicialização.

Alterações no modelo de hospedagem

Se a configuração hostingModel for alterada no arquivo web.config (explicado na seção Configuração com web.config), o módulo reciclará o processo de trabalho do IIS.

Para o IIS Express, o módulo não recicla o processo de trabalho, mas em vez disso, dispara um desligamento normal do processo atual do IIS Express. A próxima solicitação para o aplicativo gera um novo processo do IIS Express.

Nome do processo

Process.GetCurrentProcess().ProcessName relata w3wp/iisexpress (em processo) ou dotnet (fora do processo).

Muitos módulos nativos, como a Autenticação do Windows, permanecem ativos. Para saber mais sobre módulos do IIS ativos com o Módulo do ASP.NET Core, confira Módulos do IIS com o ASP.NET Core.

O Módulo do ASP.NET Core também pode:

Definir variáveis de ambiente para o processo de trabalho.
Registrar a saída StdOut no armazenamento de arquivo para a solução de problemas de inicialização.
Encaminhar tokens de autenticação do Windows.

Como instalar e usar o ANCM (Módulo do ASP.NET Core)

Para obter instruções de como instalar o Módulo do ASP.NET Core, confira Instalar o Pacote de Hospedagem do .NET Core. O Módulo do ASP.NET Core é compatível com versões do .NET incluídas no suporte anteriores e posteriores.

Alterações interruptivas e avisos de segurança são relatados no repositório Comunicados. Os comunicados podem ser limitados a uma versão específica selecionando um filtro Rótulo.

Configuração com web.config

O Módulo do ASP.NET Core está configurado com a seção aspNetCore do nó system.webServer no arquivo web.config do site.

O seguinte arquivo web.config é publicado para uma implantação dependente de estrutura e configura o Módulo do ASP.NET Core para manipular solicitações de site:

<?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>

O seguinte web.config é publicado para uma implantação autossuficiente:

<?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>

A propriedade InheritInChildApplications é definida como false para indicar que as configurações especificadas no elemento <location> não são herdadas por aplicativos que residem em um subdiretório do aplicativo.

Quando um aplicativo é implantado no Serviço de Aplicativo do Azure, o caminho stdoutLogFile é definido para \\?\%home%\LogFiles\stdout. O caminho salva logs de stdout para a pasta LogFiles, que é um local criado automaticamente pelo serviço.

Para obter informações sobre a configuração de subaplicação do IIS, consulte Hospedar o ASP.NET Core no Windows com o IIS.

Atributos do elemento aspNetCore

Atributo	Descrição	Padrão
`arguments`	Atributo de cadeia de caracteres opcional. Argumentos para o executável especificado em processPath.
`disableStartUpErrorPage`	Atributo booliano opcional. Se for true, a página 502.5 – Falha do Processo será suprimida e a página de código de status 502, configurada no web.config, terá precedência.	`false`
`forwardWindowsAuthToken`	Atributo booliano opcional. Se for true, o token será encaminhado para o processo filho escutando em `%ASPNETCORE_PORT%` como um cabeçalho `'MS-ASPNETCORE-WINAUTHTOKEN'` por solicitação. É responsabilidade desse processo chamar CloseHandle nesse token por solicitação.	`true`
`hostingModel`	Atributo de cadeia de caracteres opcional. Especifica o modelo de hospedagem como em processo (`InProcess`/`inprocess`) ou de fora do processo (`OutOfProcess`/`outofprocess`).	`InProcess` `inprocess`
`processesPerApplication`	Atributo inteiro opcional. Especifica o número de instâncias do processo especificado na configuração processPath que pode ser ativada por aplicativo. †Para hospedagem em processo, o valor está limitado a `1`. A configuração `processesPerApplication` é desencorajada. Esse atributo será removido em uma versão futura.	Padrão: `1` Mín.: `1` Máx.: `100`†
`processPath`	Atributo de cadeia de caracteres obrigatório. Caminho para o executável que inicia um processo que escuta solicitações HTTP. Caminhos relativos são compatíveis. Se o caminho começa com `.`, o caminho é considerado relativo à raiz do site.
`rapidFailsPerMinute`	Atributo inteiro opcional. Especifica o número de vezes que o processo especificado em processPath pode falhar por minuto. Se esse limite for excedido, o módulo interromperá a inicialização do processo pelo restante do minuto. Sem suporte com hospedagem padrão.	Padrão: `10` Mín.: `0` Máx.: `100`
`requestTimeout`	Atributo de intervalo de tempo opcional. Especifica a duração para a qual o Módulo do ASP.NET Core aguarda uma resposta do processo que escuta em %ASPNETCORE_PORT%. Em versões do Módulo do ASP.NET Core que acompanham a versão do ASP.NET Core 2.1 ou posterior, o `requestTimeout` é especificado em horas, minutos e segundos. Não se aplica à hospedagem em processo. Para a hospedagem em processo, o módulo aguarda o aplicativo processar a solicitação. Os valores válidos para segmentos de minutos e segundos da cadeia de caracteres estão no intervalo 0 a 59. O uso de 60 no valor para minutos ou segundos resulta em um 500 - Erro Interno do Servidor.	Padrão: `00:02:00` Mín.: `00:00:00` Máx.: `360:00:00`
`shutdownTimeLimit`	Atributo inteiro opcional. Duração em segundos que o módulo espera para o executável desligar normalmente quando o arquivo `app_offline.htm` é detectado.	Padrão: `10` Mín.: `0` Máx.: `600`
`startupTimeLimit`	Atributo inteiro opcional. Duração em segundos que o módulo espera para o arquivo executável iniciar um processo escutando na porta. Se esse tempo limite é excedido, o módulo encerra o processo. Ao hospedar em processo: o processo não é reiniciado e não usa a configuração rapidFailsPerMinute. Ao hospedar de fora do processo: o módulo tentará reiniciar o processo quando ele receber uma nova solicitação e continuará a tentar reiniciar o processo em solicitações subsequentes de entrada, a menos que o aplicativo falhe em iniciar um número de vezes igual a rapidFailsPerMinute no último minuto sem interrupção. Um valor de 0 (zero) não é considerado um tempo limite infinito.	Padrão: `120` Mín.: `0` Máx.: `3600`
`stdoutLogEnabled`	Atributo booliano opcional. Se for true, stdout e stderr para o processo especificado em processPath serão redirecionados para o arquivo especificado em stdoutLogFile.	`false`
`stdoutLogFile`	Atributo de cadeia de caracteres opcional. Especifica o caminho relativo ou absoluto para o qual stdout e stderr do processo especificado em processPath são registrados em log. Os caminhos relativos são relativos à raiz do site. Qualquer caminho começando com `.` é relativo à raiz do site e todos os outros caminhos são tratados como caminhos absolutos. Todas as pastas fornecidas no caminho são criadas pelo módulo quando o arquivo de log é criado. Usando delimitadores de sublinhado, um carimbo de data/hora, uma ID de processo e a extensão de arquivo (`.log`) são adicionados ao último segmento do caminho stdoutLogFile. Se `.\logs\stdout` é fornecido como um valor, um log de exemplo stdout é salvo como `stdout_20180205194132_1934.log` na pasta `logs` quando salvos em 5/2/2018, às 19:41:32, com uma ID de processo de 1934.	`aspnetcore-stdout`

Definir variáveis de ambiente

Variáveis de ambiente podem ser especificadas para o processo no atributo processPath. Especificar uma variável de ambiente com o elemento filho <environmentVariable> de um elemento de coleção <environmentVariables>. Variáveis de ambiente definidas nesta seção têm precedência sobre variáveis de ambiente do sistema.

O exemplo a seguir define duas variáveis de ambiente em web.config. ASPNETCORE_ENVIRONMENT configura o ambiente do aplicativo para Development. Um desenvolvedor pode definir esse valor temporariamente no arquivo web.config para forçar o carregamento da Página de Exceções do Desenvolvedor ao depurar uma exceção de aplicativo. CONFIG_DIR é um exemplo de uma variável de ambiente definida pelo usuário, em que o desenvolvedor escreveu código que lê o valor de inicialização para formar um caminho no qual carregar o arquivo de configuração do aplicativo.

<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>

Observação

Em vez de configurar o ambiente diretamente no web.config, você pode incluir a propriedade <EnvironmentName> no perfil de publicação (.pubxml) ou no perfil de projeto. Esta abordagem define o ambiente no arquivo web.config quando o projeto é publicado:

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

Aviso

Defina a variável de ambiente apenas ASPNETCORE_ENVIRONMENT para Development em servidores de preparo e de teste que não estão acessíveis a redes não confiáveis, tais como a Internet.

`app_offline.htm`

Se um arquivo com o nome app_offline.htm é detectado no diretório raiz de um aplicativo, o Módulo do ASP.NET Core tenta desligar normalmente o aplicativo e parar o processamento de solicitações de entrada. Se o aplicativo ainda está em execução após o número de segundos definido em shutdownTimeLimit, o Módulo do ASP.NET Core encerra o processo em execução.

Enquanto o arquivo app_offline.htm estiver presente, o Módulo do ASP.NET Core responderá às solicitações enviando o conteúdo do arquivo app_offline.htm. Quando o arquivo app_offline.htm é removido, a próxima solicitação inicia o aplicativo.

Ao usar o modelo de hospedagem de fora do processo, talvez o aplicativo não desligue imediatamente se houver uma conexão aberta. Por exemplo, uma conexão WebSocket pode atrasar o desligamento do aplicativo.

Página de erro de inicialização

A hospedagem em processo e fora do processo produzem páginas de erro personalizadas quando falham ao iniciar o aplicativo.

Se o Módulo do ASP.NET Core falhar ao encontrar o manipulador de solicitação em processo ou fora do processo, uma página de código de status 500.0 – falha ao carregar manipulador no processo/fora do processo será exibida.

No caso da hospedagem em processo, se o módulo do ASP.NET Core falhar ao iniciar o aplicativo, uma página de código de status 500.30 – falha ao iniciar será exibida.

Para hospedagem fora do processo, se o Módulo do ASP.NET Core falhar ao iniciar o processo de back-end ou se o processo de back-end iniciar, mas falhar ao escutar na porta configurada, uma página de código de status 502.5 – falha no processo será exibida.

Para suprimir essa página e reverter para a página de código de status 5xx padrão do IIS, use o atributo disableStartUpErrorPage. Para obter mais informações sobre como configurar mensagens de erro personalizadas, veja Erros HTTP <httpErrors>.

Criação de log e redirecionamento

O Módulo do ASP.NET Core redireciona as saídas de console stdout e stderr para o disco se os atributos stdoutLogEnabled e stdoutLogFile do elemento aspNetCore forem definidos. Todas as pastas no caminho stdoutLogFile são criadas pelo módulo quando o arquivo de log é criado. O pool de aplicativos deve ter acesso de gravação ao local em que os logs foram gravados (use IIS AppPool\<app_pool_name> para fornecer permissão de gravação).

Logs não sofrem rotação, a menos que ocorra a reciclagem/reinicialização do processo. É responsabilidade do hoster limitar o espaço em disco consumido pelos logs.

O uso do log stdout só é recomendado para solucionar problemas de inicialização de aplicativo ao hospedar no IIS ou ao usar o suporte em tempo de desenvolvimento para o IIS com o Visual Studio, não durante a depuração local e a execução do aplicativo com IIS Express.

Não use o log de stdout para fins gerais de registro em log do aplicativo. Para registro em log de rotina em um aplicativo ASP.NET Core, use uma biblioteca de registro em log que limita o tamanho do arquivo de log e realiza a rotação de logs. Para obter mais informações, veja provedores de log de terceiros.

Uma extensão de arquivo e um carimbo de data/hora são adicionados automaticamente quando o arquivo de log é criado. O nome do arquivo de log é composto por meio do acréscimo do carimbo de data/hora, da ID do processo e da extensão de arquivo (.log) para o último segmento do caminho stdoutLogFile (normalmente stdout), delimitados por sublinhados. Se o caminho stdoutLogFile termina com stdout, um log para um aplicativo com um PID de 1934, criado em 5/2/2018 às 19:42:32, tem o nome de arquivo stdout_20180205194132_1934.log.

Se stdoutLogEnabled for falso, os erros que ocorrerem na inicialização do aplicativo serão capturados e emitidos no log de eventos até 30 KB. Após a inicialização, todos os logs adicionais são descartados.

O elemento de exemplo aspNetCore a seguir configura o registro em log stdout no caminho relativo .\log\. Confirme se a identity do usuário do pool de aplicativos tem permissão para gravar no caminho fornecido.

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

Ao publicar um aplicativo para implantação do Serviço de Aplicativo do Azure, o SDK da Web define o valor stdoutLogFile como \\?\%home%\LogFiles\stdout. A variável de ambiente %home é predefinida para aplicativos hospedados pelo Serviço de Aplicativo do Azure.

Para criar regras de filtro de log, confira a seção Aplicar regras de filtro de log no código da documentação de registro em log do ASP.NET Core.

Para obter mais informações sobre formatos de caminho, confira Formatos de caminho de arquivo em sistemas Windows.

Logs de diagnóstico avançados

O Módulo do ASP.NET Core é configurável para fornecer logs de diagnóstico avançados. Adicione a <handlerSettings> elemento para o <aspNetCore> elemento no web.config. A definição de debugLevel como TRACE expõe uma fidelidade maior de informações de diagnóstico:

<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>

Todas as pastas no caminho (logs no exemplo anterior) são criadas pelo módulo quando o arquivo de log é criado. O pool de aplicativos deve ter acesso de gravação ao local em que os logs foram gravados (use IIS AppPool\{APP POOL NAME}, onde o espaço reservado {APP POOL NAME} é o nome do pool de aplicativos para fornecer permissão de gravação).

Os valores do nível de depuração (debugLevel) podem incluir o nível e a localização.

Níveis (na ordem do menos para o mais detalhado):

ERROR
WARNING
INFO
RASTREAMENTO

Locais (vários locais são permitidos):

CONSOLE
EVENTLOG
FILE

As configurações do manipulador também podem ser fornecidas por meio de variáveis de ambiente:

ASPNETCORE_MODULE_DEBUG_FILE: caminho para o arquivo de log de depuração. (padrão: aspnetcore-debug.log)
ASPNETCORE_MODULE_DEBUG: configuração do nível de depuração.

Aviso

Não deixe o log de depuração habilitado na implantação por mais tempo que o necessário para solucionar um problema. O tamanho do log não é limitado. Deixar o log de depuração habilitado pode esgotar o espaço em disco disponível e causar falha no servidor ou no serviço de aplicativo.

Veja Configuração com web.config para obter um exemplo do elemento aspNetCore no arquivo web.config.

Modificar o tamanho da pilha

Aplica-se somente ao usar o modelo de hospedagem em processo.

Configurar o tamanho da pilha gerenciada usando a configuração stackSize em bytes em web.config. O tamanho padrão é de 1.048.576 bytes (1 MB).

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

A configuração de proxy usa o protocolo HTTP e um token de emparelhamento

Só se aplica à hospedagem de fora do processo.

O proxy criado entre o módulo ASP.NET Core e o Kestrel usa o protocolo HTTP. Não há nenhum risco de interceptação do tráfego entre o módulo e o Kestrel em um local fora do servidor.

Um token de emparelhamento é usado para assegurar que as solicitações recebidas pelo Kestrel foram transmitidas por proxy pelo IIS e que não são provenientes de outra origem. O token de emparelhamento é criado e definido em uma variável de ambiente (ASPNETCORE_TOKEN) pelo módulo. O token de emparelhamento também é definido em um cabeçalho (MS-ASPNETCORE-TOKEN) em cada solicitação com proxy. O Middleware do IIS verifica cada solicitação recebida para confirmar se o valor de cabeçalho do token de emparelhamento corresponde ao valor da variável de ambiente. Se os valores do token forem incompatíveis, a solicitação será registrada em log e rejeitada. A variável de ambiente do token de emparelhamento e o tráfego entre o módulo e o Kestrel não são acessíveis em um local fora do servidor. Sem saber o valor do token de emparelhamento, um invasor cibernético não pode enviar solicitações que ignoram a verificação no Middleware do IIS.

Módulo do ASP.NET Core com uma configuração do IIS compartilhada

O instalador do módulo do ASP.NET Core é executado com os privilégios da conta de TrustedInstaller. Como a conta do sistema local não tem permissão de modificação para o caminho de compartilhamento usado pela Configuração Compartilhada do IIS, o instalador lança um erro de acesso negado ao tentar definir as configurações do módulo no arquivo applicationHost.config no compartilhamento.

Ao usar uma configuração compartilhada de IIS no mesmo computador que a instalação do IIS, execute o instalador do pacote de hospedagem do ASP.NET Core com o parâmetro OPT_NO_SHARED_CONFIG_CHECK definido como 1:

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

Quando o caminho para a configuração compartilhada não está no mesmo computador que a instalação do IIS, siga estas etapas:

Desabilite a configuração compartilhada de IIS.
Execute o instalador.
Exporte o arquivo applicationHost.config atualizado para o compartilhamento.
Reabilite a Configuração Compartilhada do IIS.

Versão do módulo e logs do instalador do pacote de hospedagem

Para determinar a versão do Módulo do ASP.NET Core instalado:

No sistema de hospedagem, acesse %windir%\System32\inetsrv.
Localize o arquivo aspnetcore.dll.
Clique com o botão direito do mouse no arquivo e selecione Propriedades no menu contextual.
Selecione a guia Detalhes. A Versão do arquivo e a Versão do produto representam a versão instalada do módulo.

Os logs de instalador do pacote de hospedagem para o módulo são encontrados em C:\Users\%UserName%\AppData\Local\Temp. O arquivo é denominado dd_DotNetCoreWinSvrHosting__{TIMESTAMP}_000_AspNetCoreModule_x64.log.

Locais dos arquivos de módulo, de esquema e de configuração

Módulo

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

Esquema

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

Configuração

IIS

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

IIS Express

Visual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.config
CLI do iisexpress.exe: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config

Os arquivos podem ser encontrados pesquisando aspnetcore no arquivo applicationHost.config.

O ANCM (Módulo do ASP.NET Core) é um módulo nativo do IIS que se conecta ao pipeline do IIS para:

Hospedar um aplicativo ASP.NET Core dentro do processo de trabalho do IIS (w3wp.exe), chamado o modelo de hospedagem no processo.
Encaminhar solicitações da Web a um aplicativo ASP.NET Core de back-end que executa o servidor Kestrel, chamado o modelo de hospedagem de fora do processo.

Versões do Windows com suporte:

Windows 7 ou posterior
Windows Server 2008 R2 ou posterior

Ao fazer uma hospedagem em processo, o módulo usa uma implementação de servidor em processo do IIS, chamado Servidor HTTP do IIS (IISHttpServer).

Ao hospedar de fora do processo, o módulo só funciona com o Kestrel. O módulo não funciona com HTTP.sys.

Modelos de hospedagem

Modelo de hospedagem em processo

Para configurar um aplicativo para hospedagem em processo, adicione a propriedade <AspNetCoreHostingModel> ao arquivo de projeto do aplicativo com um valor de InProcess (a hospedagem de fora do processo é definida com OutOfProcess):

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

Não há suporte para o modelo de hospedagem em processo para aplicativos ASP.NET Core direcionados ao .NET Framework.

O valor de <AspNetCoreHostingModel> não diferencia maiúsculas de minúsculas, portanto, inprocess e outofprocess são valores válidos.

Se a propriedade <AspNetCoreHostingModel> não estiver presente no arquivo, o valor padrão será OutOfProcess.

As seguintes características se aplicam ao hospedar em processo:

O servidor HTTP do IIS (IISHttpServer) é usado em vez do servidor Kestrel. Em processo, CreateDefaultBuilder chama UseIIS para:
- Registrar o IISHttpServer.
- Configurar a porta e o caminho base nos quais o servidor deve escutar ao ser executado por trás do Módulo do ASP.NET Core.
- Configurar o host para capturar erros de inicialização.
O requestTimeout atributo não se aplica à hospedagem em processo.
Não há suporte para o compartilhamento do pool de aplicativos entre aplicativos. Use um pool de aplicativos por aplicativo.
Ao usar a Implantação da Web ou inserir manualmente um arquivo app_offline.htm na implantação, o aplicativo talvez não seja desligado imediatamente se houver uma conexão aberta. Por exemplo, uma conexão websocket pode atrasar o desligamento do aplicativo.
A arquitetura (número de bit) do aplicativo e o runtime instalado (x64 ou x86) devem corresponder à arquitetura do pool de aplicativos.
As desconexões do cliente são detectadas. O token de cancelamento HttpContext.RequestAborted é cancelado quando o cliente se desconecta.
No ASP.NET Core 2.2.1 ou anterior, GetCurrentDirectory retorna o diretório de trabalho do processo iniciado pelo IIS em vez de o diretório do aplicativo (por exemplo, C:\Windows\System32\inetsrv para w3wp.exe).

Para obter o código de exemplo que define o diretório atual do aplicativo, confira a classe CurrentDirectoryHelpers. Chame o método SetCurrentDirectory . As chamadas seguintes a GetCurrentDirectory fornecem o diretório do aplicativo.
Ao hospedar em processo, AuthenticateAsync não é chamado internamente para inicializar um usuário. Portanto, uma implementação IClaimsTransformation usada para transformar as declarações após cada autenticação não é ativada por padrão. Quando a transformação de declarações com uma implementação IClaimsTransformation, chame AddAuthentication para adicionar serviços de autenticação:
```
public void ConfigureServices(IServiceCollection services)
{
    services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
    services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
}

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

Modelo de hospedagem de fora do processo

Para configurar um aplicativo para hospedagem fora do processo, use qualquer uma das abordagens a seguir no arquivo de projeto:

não especifique a propriedade <AspNetCoreHostingModel>. Se a propriedade <AspNetCoreHostingModel> não estiver presente no arquivo, o valor padrão será OutOfProcess.
Defina o valor da propriedade <AspNetCoreHostingModel> como OutOfProcess (a hospedagem no processo é definida com InProcess):

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

O valor não diferencia maiúsculas de minúsculas, portanto, inprocess e outofprocess são valores válidos.

O servidor Kestrel é usado, em vez do servidor HTTP do IIS (IISHttpServer).

Fora do processo, CreateDefaultBuilder chama UseIISIntegration para:

Configurar a porta e o caminho base nos quais o servidor deve escutar ao ser executado por trás do Módulo do ASP.NET Core.
Configurar o host para capturar erros de inicialização.

Alterações no modelo de hospedagem

Se a configuração hostingModel for alterada no arquivo web.config (explicado na seção Configuração a Web.config), o módulo reciclará o processo de trabalho do IIS.

Nome do processo

Process.GetCurrentProcess().ProcessName relata w3wp/iisexpress (em processo) ou dotnet (fora do processo).

Muitos módulos nativos, como a Autenticação do Windows, permanecem ativos. Para saber mais sobre módulos do IIS ativos com o Módulo do ASP.NET Core, confira Módulos do IIS com o ASP.NET Core.

O Módulo do ASP.NET Core também pode:

Definir variáveis de ambiente para o processo de trabalho.
Registrar a saída StdOut no armazenamento de arquivo para a solução de problemas de inicialização.
Encaminhar tokens de autenticação do Windows.

Como instalar e usar o ANCM (Módulo do ASP.NET Core)

Alterações interruptivas e avisos de segurança são relatados no repositório Comunicados. Os comunicados podem ser limitados a uma versão específica selecionando um filtro Rótulo.

Configuração com web.config

O Módulo do ASP.NET Core está configurado com a seção aspNetCore do nó system.webServer no arquivo web.config do site.

O seguinte arquivo web.config é publicado para uma implantação dependente de estrutura e configura o Módulo do ASP.NET Core para manipular solicitações de site:

<?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>

O seguinte web.config é publicado para uma implantação autossuficiente:

<?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>

A propriedade InheritInChildApplications é definida como false para indicar que as configurações especificadas no elemento <location> não são herdadas por aplicativos que residem em um subdiretório do aplicativo.

Quando um aplicativo é implantado no Serviço de Aplicativo do Azure, o caminho stdoutLogFile é definido para \\?\%home%\LogFiles\stdout. O caminho salva logs de stdout para a pasta LogFiles, que é um local criado automaticamente pelo serviço.

Para obter informações sobre a configuração de subaplicação do IIS, consulte Hospedar o ASP.NET Core no Windows com o IIS.

Atributos do elemento aspNetCore

Atributo	Descrição	Padrão
`arguments`	Atributo de cadeia de caracteres opcional. Argumentos para o executável especificado em `processPath`.
`disableStartUpErrorPage`	Atributo booliano opcional. Se for true, a página 502.5 – Falha do Processo será suprimida e a página de código de status 502, configurada no web.config, terá precedência.	`false`
`forwardWindowsAuthToken`	Atributo booliano opcional. Se for true, o token será encaminhado para o processo filho escutando em %ASPNETCORE_PORT% como um cabeçalho 'MS-ASPNETCORE-WINAUTHTOKEN' por solicitação. É responsabilidade desse processo chamar CloseHandle nesse token por solicitação.	`true`
`hostingModel`	Atributo de cadeia de caracteres opcional. Especifica o modelo de hospedagem como em processo (`InProcess`/`inprocess`) ou de fora do processo (`OutOfProcess`/`outofprocess`).	`OutOfProcess` `outofprocess`
`processesPerApplication`	Atributo inteiro opcional. Especifica o número de instâncias do processo especificado na configuração `processPath` que pode ser ativada por aplicativo. †Para hospedagem em processo, o valor está limitado a `1`. A configuração `processesPerApplication` é desencorajada. Esse atributo será removido em uma versão futura.	Padrão: `1` Mín.: `1` Máx.: `100`†
`processPath`	Atributo de cadeia de caracteres obrigatório. Caminho para o executável que inicia um processo que escuta solicitações HTTP. Caminhos relativos são compatíveis. Se o caminho começa com `.`, o caminho é considerado relativo à raiz do site.
`rapidFailsPerMinute`	Atributo inteiro opcional. Especifica o número de vezes que o processo especificado em `processPath` pode falhar por minuto. Se esse limite for excedido, o módulo interromperá a inicialização do processo pelo restante do minuto. Sem suporte com hospedagem padrão.	Padrão: `10` Mín.: `0` Máx.: `100`
`requestTimeout`	Atributo de intervalo de tempo opcional. Especifica a duração para a qual o Módulo do ASP.NET Core aguarda uma resposta do processo que escuta em %ASPNETCORE_PORT%. Em versões do Módulo do ASP.NET Core que acompanham a versão do ASP.NET Core 2.1 ou posterior, o `requestTimeout` é especificado em horas, minutos e segundos. Não se aplica à hospedagem em processo. Para a hospedagem em processo, o módulo aguarda o aplicativo processar a solicitação. Os valores válidos para segmentos de minutos e segundos da cadeia de caracteres estão no intervalo 0 a 59. O uso de 60 no valor para minutos ou segundos resulta em um 500 - Erro Interno do Servidor.	Padrão: `00:02:00` Mín.: `00:00:00` Máx.: `360:00:00`
`shutdownTimeLimit`	Atributo inteiro opcional. Duração em segundos que o módulo espera para o executável desligar normalmente quando o arquivo `app_offline.htm` é detectado.	Padrão: `10` Mín.: `0` Máx.: `600`
`startupTimeLimit`	Atributo inteiro opcional. Duração em segundos que o módulo espera para o arquivo executável iniciar um processo escutando na porta. Se esse tempo limite é excedido, o módulo encerra o processo. Ao hospedar em processo: o processo não é reiniciado e não usa a configuração `rapidFailsPerMinute`. Ao hospedar de fora do processo: o módulo tentará reiniciar o processo quando ele receber uma nova solicitação e continuará a tentar reiniciar o processo em solicitações subsequentes de entrada, a menos que o aplicativo falhe em iniciar um número de vezes igual a `rapidFailsPerMinute` no último minuto sem interrupção. Um valor de 0 (zero) não é considerado um tempo limite infinito.	Padrão: `120` Mín.: `0` Máx.: `3600`
`stdoutLogEnabled`	Atributo booliano opcional. Se for true, stdout e stderr para o processo especificado em `processPath` serão redirecionados para o arquivo especificado em stdoutLogFile.	`false`
`stdoutLogFile`	Atributo de cadeia de caracteres opcional. Especifica o caminho relativo ou absoluto para o qual `stdout` e `stderr` do processo especificado em `processPath` são registrados em log. Os caminhos relativos são relativos à raiz do site. Qualquer caminho começando com `.` é relativo à raiz do site e todos os outros caminhos são tratados como caminhos absolutos. Todas as pastas fornecidas no caminho são criadas pelo módulo quando o arquivo de log é criado. Usando delimitadores de sublinhado, um carimbo de data/hora, uma ID de processo e a extensão de arquivo (`.log`) são adicionados ao último segmento do caminho `stdoutLogFile`. Se `.\logs\stdout` é fornecido como um valor, um log de exemplo stdout é salvo como `stdout_20180205194132_1934.log` na pasta `logs` quando salvos em 5/2/2018, às 19:41:32, com uma ID de processo de 1934.	`aspnetcore-stdout`

Configurando variáveis de ambiente

O exemplo a seguir define duas variáveis de ambiente. ASPNETCORE_ENVIRONMENT configura o ambiente do aplicativo para Development. Um desenvolvedor pode definir esse valor temporariamente no arquivo web.config para forçar o carregamento da Página de Exceções do Desenvolvedor ao depurar uma exceção de aplicativo. CONFIG_DIR é um exemplo de uma variável de ambiente definida pelo usuário, em que o desenvolvedor escreveu código que lê o valor de inicialização para formar um caminho no qual carregar o arquivo de configuração do aplicativo.

<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>

Observação

Em vez de configurar o ambiente diretamente no web.config, você pode incluir a propriedade <EnvironmentName> no perfil de publicação (.pubxml) ou no perfil de projeto. Esta abordagem define o ambiente no arquivo web.config quando o projeto é publicado:

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

Aviso

Defina a variável de ambiente apenas ASPNETCORE_ENVIRONMENT para Development em servidores de preparo e de teste que não estão acessíveis a redes não confiáveis, tais como a Internet.

app_offline.htm

Ao usar o modelo de hospedagem de fora do processo, talvez o aplicativo não desligue imediatamente se houver uma conexão aberta. Por exemplo, uma conexão websocket pode atrasar o desligamento do aplicativo.

Página de erro de inicialização

A hospedagem em processo e fora do processo produzem páginas de erro personalizadas quando falham ao iniciar o aplicativo.

No caso da hospedagem em processo, se o módulo do ASP.NET Core falhar ao iniciar o aplicativo, uma página de código de status 500.30 – falha ao iniciar será exibida.

Criação de log e redirecionamento

O Módulo do ASP.NET Core redireciona as saídas de console stdout e stderr para o disco se os atributos stdoutLogEnabled e stdoutLogFile do elemento aspNetCore forem definidos. Todas as pastas no caminho stdoutLogFile são criadas pelo módulo quando o arquivo de log é criado. O pool de aplicativos deve ter acesso de gravação ao local em que os logs foram gravados (use IIS AppPool\{APP POOL NAME} para fornecer permissão de gravação, onde o espaço reservado {APP POOL NAME} é o nome do pool de aplicativos).

Logs não sofrem rotação, a menos que ocorra a reciclagem/reinicialização do processo. É responsabilidade do hoster limitar o espaço em disco consumido pelos logs.

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

Para obter mais informações sobre formatos de caminho, consulte Formatos de caminho de arquivo em sistemas Windows.

Logs de diagnóstico avançados

<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>

As pastas no caminho fornecido para o valor <handlerSetting> (logs no exemplo anterior) não são criadas automaticamente pelo módulo e devem existir previamente na implantação. O pool de aplicativos deve ter acesso de gravação ao local em que os logs foram gravados (use IIS AppPool\{APP POOL NAME} para fornecer permissão de gravação, onde o espaço reservado {APP POOL NAME} é o nome do pool de aplicativos).

Os valores do nível de depuração (debugLevel) podem incluir o nível e a localização.

Níveis (na ordem do menos para o mais detalhado):

ERROR
WARNING
INFO
RASTREAMENTO

Locais (vários locais são permitidos):

CONSOLE
EVENTLOG
FILE

As configurações do manipulador também podem ser fornecidas por meio de variáveis de ambiente:

ASPNETCORE_MODULE_DEBUG_FILE: caminho para o arquivo de log de depuração. (padrão: aspnetcore-debug.log)
ASPNETCORE_MODULE_DEBUG: configuração do nível de depuração.

Aviso

Veja Configuração com web.config para obter um exemplo do elemento aspNetCore no arquivo web.config.

A configuração de proxy usa o protocolo HTTP e um token de emparelhamento

Só se aplica à hospedagem de fora do processo.

O proxy criado entre o módulo ASP.NET Core e o Kestrel usa o protocolo HTTP. Não há nenhum risco de interceptação do tráfego entre o módulo e o Kestrel em um local fora do servidor.

Módulo do ASP.NET Core com uma configuração do IIS compartilhada

O instalador do módulo do ASP.NET Core é executado com os privilégios da conta TrustedInstaller. Como a conta do sistema local não tem permissão de modificação para o caminho de compartilhamento usado pela Configuração Compartilhada do IIS, o instalador lança um erro de acesso negado ao tentar definir as configurações do módulo no arquivo applicationHost.config no compartilhamento.

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

Quando o caminho para a configuração compartilhada não está no mesmo computador que a instalação do IIS, siga estas etapas:

Desabilite a configuração compartilhada de IIS.
Execute o instalador.
Exporte o arquivo applicationHost.config atualizado para o compartilhamento.
Reabilite a Configuração Compartilhada do IIS.

Versão do módulo e logs do instalador do pacote de hospedagem

Para determinar a versão do Módulo do ASP.NET Core instalado:

No sistema de hospedagem, acesse %windir%\System32\inetsrv.
Localize o arquivo aspnetcore.dll.
Clique com o botão direito do mouse no arquivo e selecione Propriedades no menu contextual.
Selecione a guia Detalhes. A Versão do arquivo e a Versão do produto representam a versão instalada do módulo.

Os logs de instalador do pacote de hospedagem para o módulo são encontrados em C:\\Users\\%UserName%\\AppData\\Local\\Temp. O arquivo é chamado dd_DotNetCoreWinSvrHosting__\{TIMESTAMP}_000_AspNetCoreModule_x64.log, onde o espaço reservado {TIMESTAMP} é o carimbo de data/hora.

Locais dos arquivos de módulo, de esquema e de configuração

Módulo

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

Esquema

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

Configuração

IIS

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

IIS Express

Visual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.config
CLI do iisexpress.exe: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config

Os arquivos podem ser encontrados pesquisando aspnetcore no arquivo applicationHost.config.

O ANCM (Módulo do ASP.NET Core) é um módulo nativo do IIS que se conecta ao pipeline do IIS para encaminhar solicitações da Web para aplicativos ASP.NET Core de back-end.

Versões do Windows com suporte:

Windows 7 ou posterior
Windows Server 2008 R2 ou posterior

O módulo só funciona com Kestrel. O módulo é incompatível com HTTP.sys.

Como os aplicativos ASP.NET Core são executados em um processo separado do processo de trabalho do IIS, o módulo também realiza o gerenciamento de processos. O módulo inicia o processo para o aplicativo ASP.NET Core quando a primeira solicitação chega e reinicia o aplicativo quando ele falha. Isso é basicamente o mesmo comportamento que o dos aplicativos ASP.NET 4.x que são executados dentro do processo do IIS e são gerenciados pelo WAS (Serviço de Ativação de Processos do Windows).

O diagrama a seguir ilustra a relação entre o IIS, o Módulo do ASP.NET Core e um aplicativo:

Módulo do ASP.NET Core

As solicitações chegam da Web para o driver do HTTP.sys no modo kernel. O driver roteia as solicitações ao IIS na porta configurada do site, normalmente, a 80 (HTTP) ou a 443 (HTTPS). O módulo encaminha as solicitações ao Kestrel em uma porta aleatória do aplicativo, que não seja a porta 80 ou 443.

O módulo especifica a porta por meio de uma variável de ambiente na inicialização e o middleware de integração do IIS configura o servidor para escutar em http://localhost:{port}. Outras verificações são executadas e as solicitações que não se originam do módulo são rejeitadas. O módulo não é compatível com encaminhamento de HTTPS, portanto, as solicitações são encaminhadas por HTTP, mesmo se recebidas pelo IIS por HTTPS.

Depois que o Kestrel coleta a solicitação do módulo, a solicitação é enviada por push ao pipeline do middleware do ASP.NET Core. O pipeline do middleware manipula a solicitação e a passa como uma instância de HttpContext para a lógica do aplicativo. O middleware adicionado pela integração do IIS atualiza o esquema, o IP remoto e pathbase para encaminhar a solicitação para o Kestrel. A resposta do aplicativo é retornada ao IIS, que a retorna por push para o cliente HTTP que iniciou a solicitação.

Muitos módulos nativos, como a Autenticação do Windows, permanecem ativos. Para saber mais sobre módulos do IIS ativos com o Módulo do ASP.NET Core, confira Módulos do IIS com o ASP.NET Core.

O Módulo do ASP.NET Core também pode:

Definir variáveis de ambiente para o processo de trabalho.
Registrar a saída StdOut no armazenamento de arquivo para a solução de problemas de inicialização.
Encaminhar tokens de autenticação do Windows.

Como instalar e usar o ANCM (Módulo do ASP.NET Core)

Para obter instruções de como instalar o Módulo do ASP.NET Core, confira Instalar o Pacote de Hospedagem do .NET Core.

Configuração com web.config

O Módulo do ASP.NET Core está configurado com a seção aspNetCore do nó system.webServer no arquivo web.config do site.

O seguinte arquivo web.config é publicado para uma implantação dependente de estrutura e configura o Módulo do ASP.NET Core para manipular solicitações de site:

<?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>

O seguinte web.config é publicado para uma implantação autossuficiente:

<?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>

Quando um aplicativo é implantado no Serviço de Aplicativo do Azure, o caminho stdoutLogFile é definido para \\?\%home%\LogFiles\stdout. O caminho salva logs de stdout para a pasta LogFiles, que é um local criado automaticamente pelo serviço.

Para obter informações sobre a configuração de subaplicação do IIS, consulte Hospedar o ASP.NET Core no Windows com o IIS.

Atributos do elemento aspNetCore

Atributo	Descrição	Padrão
`arguments`	Atributo de cadeia de caracteres opcional. Argumentos para o executável especificado em processPath.
`disableStartUpErrorPage`	Atributo booliano opcional. Se for true, a página 502.5 – Falha do Processo será suprimida e a página de código de status 502, configurada no web.config, terá precedência.	`false`
`forwardWindowsAuthToken`	Atributo booliano opcional. Se for true, o token será encaminhado para o processo filho escutando em %ASPNETCORE_PORT% como um cabeçalho 'MS-ASPNETCORE-WINAUTHTOKEN' por solicitação. É responsabilidade desse processo chamar CloseHandle nesse token por solicitação.	`true`
`processesPerApplication`	Atributo inteiro opcional. Especifica o número de instâncias do processo especificado na configuração processPath que pode ser ativada por aplicativo. A configuração `processesPerApplication` é desencorajada. Esse atributo será removido em uma versão futura.	Padrão: `1` Mín.: `1` Máx.: `100`
`processPath`	Atributo de cadeia de caracteres obrigatório. Caminho para o executável que inicia um processo que escuta solicitações HTTP. Caminhos relativos são compatíveis. Se o caminho começa com `.`, o caminho é considerado relativo à raiz do site.
`rapidFailsPerMinute`	Atributo inteiro opcional. Especifica o número de vezes que o processo especificado em processPath pode falhar por minuto. Se esse limite for excedido, o módulo interromperá a inicialização do processo pelo restante do minuto.	Padrão: `10` Mín.: `0` Máx.: `100`
`requestTimeout`	Atributo de intervalo de tempo opcional. Especifica a duração para a qual o Módulo do ASP.NET Core aguarda uma resposta do processo que escuta em %ASPNETCORE_PORT%. Em versões do Módulo do ASP.NET Core que acompanham a versão do ASP.NET Core 2.1 ou posterior, o `requestTimeout` é especificado em horas, minutos e segundos.	Padrão: `00:02:00` Mín.: `00:00:00` Máx.: `360:00:00`
`shutdownTimeLimit`	Atributo inteiro opcional. Duração em segundos que o módulo espera para o executável desligar normalmente quando o arquivo `app_offline.htm` é detectado.	Padrão: `10` Mín.: `0` Máx.: `600`
`startupTimeLimit`	Atributo inteiro opcional. Duração em segundos que o módulo espera para o arquivo executável iniciar um processo escutando na porta. Se esse tempo limite é excedido, o módulo encerra o processo. O módulo tentará reiniciar o processo quando ele receber uma nova solicitação e continuará a tentar reiniciar o processo em solicitações subsequentes de entrada, a menos que o aplicativo falhe em iniciar um número de vezes igual a rapidFailsPerMinute no último minuto sem interrupção. Um valor de 0 (zero) não é considerado um tempo limite infinito.	Padrão: `120` Mín.: `0` Máx.: `3600`
`stdoutLogEnabled`	Atributo booliano opcional. Se for true, stdout e stderr para o processo especificado em processPath serão redirecionados para o arquivo especificado em stdoutLogFile.	`false`
`stdoutLogFile`	Atributo de cadeia de caracteres opcional. Especifica o caminho relativo ou absoluto para o qual stdout e stderr do processo especificado em processPath são registrados em log. Os caminhos relativos são relativos à raiz do site. Qualquer caminho começando com `.` é relativo à raiz do site e todos os outros caminhos são tratados como caminhos absolutos. As pastas fornecidas no caminho devem existir para que o módulo crie o arquivo de log. Usando delimitadores de sublinhado, um carimbo de data/hora, uma ID de processo e a extensão de arquivo (.log) são adicionados ao último segmento do caminho stdoutLogFile. Se `.\logs\stdout` é fornecido como um valor, um log de exemplo stdout é salvo como stdout_20180205194132_1934.log na pasta logs quando salvos em 5/2/2018, às 19:41:32, com uma ID de processo de 1934.	`aspnetcore-stdout`

Configurando variáveis de ambiente

Aviso

As variáveis de ambiente definidas nesta seção são conflitantes com as variáveis de ambiente do sistema definidas com o mesmo nome. Quando a variável de ambiente é definida no arquivo web.config e no nível do sistema do Windows, o valor do arquivo web.config fica anexado ao valor da variável de ambiente do sistema (por exemplo, ASPNETCORE_ENVIRONMENT: Development;Development), o que impede a inicialização do aplicativo.

O exemplo a seguir define duas variáveis de ambiente. ASPNETCORE_ENVIRONMENT configura o ambiente do aplicativo para Development. Um desenvolvedor pode definir esse valor temporariamente no arquivo web.config para forçar o carregamento da Página de Exceções do Desenvolvedor ao depurar uma exceção de aplicativo. CONFIG_DIR é um exemplo de uma variável de ambiente definida pelo usuário, em que o desenvolvedor escreveu código que lê o valor de inicialização para formar um caminho no qual carregar o arquivo de configuração do aplicativo.

<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>

Aviso

Defina a variável de ambiente apenas ASPNETCORE_ENVIRONMENT para Development em servidores de preparo e de teste que não estão acessíveis a redes não confiáveis, tais como a Internet.

app_offline.htm

Página de erro de inicialização

Se o Módulo do ASP.NET Core falhar ao iniciar o processo de back-end ou se o processo de back-end iniciar, mas falhar ao escutar na porta configurada, uma página de código de status 502.5 – falha no processo será exibida. Para omitir esta página e reverter para a página de código de status 502 padrão do IIS, use o atributo disableStartUpErrorPage. Para obter mais informações sobre como configurar mensagens de erro personalizadas, veja Erros HTTP <httpErrors>.

Criação de log e redirecionamento

Logs não sofrem rotação, a menos que ocorra a reciclagem/reinicialização do processo. É responsabilidade do hoster limitar o espaço em disco consumido pelos logs.

Uma extensão de arquivo e um carimbo de data/hora são adicionados automaticamente quando o arquivo de log é criado. O nome do arquivo de log é composto por meio do acréscimo do carimbo de data/hora, da ID do processo e da extensão de arquivo (.log) para o último segmento do caminho stdoutLogFile (normalmente stdout), delimitados por sublinhados. Se o caminho stdoutLogFile termina com stdout, um log para um aplicativo com um PID de 1934, criado em 5/2/2018 às 19:42:32, tem o nome de arquivo stdout_20180205194132_1934.log.

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

Para criar regras de filtro de log, confira a seção Aplicar regras de filtro de log no código da documentação de registro em log do ASP.NET Core.

Para obter mais informações sobre formatos de caminho, consulte Formatos de caminho de arquivo em sistemas Windows.

A configuração de proxy usa o protocolo HTTP e um token de emparelhamento

O proxy criado entre o módulo ASP.NET Core e o Kestrel usa o protocolo HTTP. Não há nenhum risco de interceptação do tráfego entre o módulo e o Kestrel em um local fora do servidor.

Módulo do ASP.NET Core com uma configuração do IIS compartilhada

O instalador do módulo do ASP.NET Core é executado com os privilégios da conta de TrustedInstaller. Já que a conta de sistema local não tem permissão para modificar o caminho do compartilhamento usado pela configuração compartilhada de IIS, o instalador gera um erro de acesso negado ao tentar definir as configurações de módulo no arquivo applicationHost.config no compartilhamento.

Ao usar uma configuração compartilhada de IIS, siga estas etapas:

Desabilite a configuração compartilhada de IIS.
Execute o instalador.
Exportar o arquivo applicationHost.config atualizado para o compartilhamento.
Reabilite a Configuração Compartilhada do IIS.

Versão do módulo e logs do instalador do pacote de hospedagem

Para determinar a versão do Módulo do ASP.NET Core instalado:

No sistema de hospedagem, navegue até %windir%\System32\inetsrv.
Localize o arquivo aspnetcore.dll.
Clique com o botão direito do mouse no arquivo e selecione Propriedades no menu contextual.
Selecione a guia Detalhes. A Versão do arquivo e a Versão do produto representam a versão instalada do módulo.

Os logs de instalador do pacote de hospedagem para o módulo são encontrados em C:\Users\%UserName%\AppData\Local\Temp. O arquivo é nomeado dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

Locais dos arquivos de módulo, de esquema e de configuração

Módulo

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

Esquema

IIS

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

IIS Express

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

Configuração

IIS

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

IIS Express

Visual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.config
iisexpress.exe CLI: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config

Os arquivos podem ser encontrados pesquisando por aspnetcore no arquivo applicationHost.config.

Recursos adicionais

Hospedar o ASP.NET Core no Windows com o IIS
Implantar aplicativos ASP.NET Core no Serviço de Aplicativo do Azure
Fonte de referência do Módulo do ASP.NET Core [ramificação padrão (principal)]: use a lista suspensa Ramificação para selecionar uma versão específica (por exemplo, release/3.1).
Módulos do IIS com o ASP.NET Core

Partilhar via

Módulo do ASP.NET Core (ANCM) para IIS

Instalar o ANCM (Módulo do ASP.NET Core)

Modelos de hospedagem

Modelo de hospedagem em processo

Modelo de hospedagem de fora do processo

Alterações no modelo de hospedagem

Nome do processo

Como instalar e usar o ANCM (Módulo do ASP.NET Core)

Configuração com web.config

Atributos do elemento aspNetCore

Definir variáveis de ambiente

app_offline.htm

Página de erro de inicialização

Criação de log e redirecionamento

Logs de diagnóstico avançados

Modificar o tamanho da pilha

A configuração de proxy usa o protocolo HTTP e um token de emparelhamento

Módulo do ASP.NET Core com uma configuração do IIS compartilhada

Versão do módulo e logs do instalador do pacote de hospedagem

Locais dos arquivos de módulo, de esquema e de configuração

Módulo

Esquema

Configuração

Modelos de hospedagem

Modelo de hospedagem em processo

Modelo de hospedagem de fora do processo

Alterações no modelo de hospedagem

Nome do processo

Como instalar e usar o ANCM (Módulo do ASP.NET Core)

Configuração com web.config

Atributos do elemento aspNetCore

Configurando variáveis de ambiente

app_offline.htm

Página de erro de inicialização

Criação de log e redirecionamento

Logs de diagnóstico avançados

A configuração de proxy usa o protocolo HTTP e um token de emparelhamento

Módulo do ASP.NET Core com uma configuração do IIS compartilhada

Versão do módulo e logs do instalador do pacote de hospedagem

Locais dos arquivos de módulo, de esquema e de configuração

Módulo

Esquema

Configuração

Como instalar e usar o ANCM (Módulo do ASP.NET Core)

Configuração com web.config

Atributos do elemento aspNetCore

Configurando variáveis de ambiente

app_offline.htm

Página de erro de inicialização

Criação de log e redirecionamento

A configuração de proxy usa o protocolo HTTP e um token de emparelhamento

Módulo do ASP.NET Core com uma configuração do IIS compartilhada

Versão do módulo e logs do instalador do pacote de hospedagem

Locais dos arquivos de módulo, de esquema e de configuração

Módulo

Esquema

Configuração

Recursos adicionais

Recursos adicionais

`app_offline.htm`