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

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

Há compensações entre cada um dos modelos 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:

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

O ANCM (Módulo ASP.NET Core) é instalado com o Runtime do .NET Core do Pacote de Hospedagem do .NET Core. O módulo ASP.NET Core é compatível com versões de LTS do .NET.

Alterações interruptivas e avisos de segurança são relatados no repositório Comunicados. Os anúncios podem ser limitados a uma versão específica selecionando um filtro de 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, consulte o Pacote de Hospedagem.

Para obter 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 ASP.NET Core) é um módulo nativo do IIS que se conecta ao pipeline do IIS para:

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 fora do processo, o módulo só funciona com Kestrel. O módulo não funciona com HTTP.sys.

Modelos de hospedagem

Modelo de hospedagem em processo

ASP.NET Core aplicativos padrão para 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 Kestrel servidor. 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 colocar manualmente um app_offline.htm arquivo na implantação, o aplicativo poderá não desligar 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 HttpContext.RequestAborted token de cancelamento é 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 do diretório do aplicativo (por exemplo, C:\Windows\System32\inetsrv para w3wp.exe).

    Para obter um código de exemplo que define o diretório atual do aplicativo, consulte a CurrentDirectoryHelpers classe. 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, defina o valor da <AspNetCoreHostingModel> propriedade para 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> diferencia maiúsculas de minúsculas e inprocessoutofprocess valores válidos.

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

Para fora do processo, CreateDefaultBuilder chamadas 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 hostingModel configuração for alterada no web.config arquivo (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 ASP.NET Core, consulte módulos do IIS com 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 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 ASP.NET Core é compatível com versões de LTS do .NET.

Alterações interruptivas e avisos de segurança são relatados no repositório Comunicados. Os anúncios podem ser limitados a uma versão específica selecionando um filtro de 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 arquivo a seguir web.config é publicado para uma implantação dependente de estrutura e configura o Módulo ASP.NET Core para lidar com 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 InheritInChildApplications propriedade está definida para false indicar que as configurações especificadas dentro do <location> elemento 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 stdout na LogFiles pasta, que é um local criado automaticamente pelo serviço.

Para obter informações sobre a configuração de subaplicação do IIS, consulte Host 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 %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 fora de 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 é limitado a 1.

A configuração processesPerApplication é desencorajada. Esse atributo será removido em uma versão futura.

Padrão: 1
Mín.: 1
Máximo: 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 em que o módulo aguarda o executável ser desligado normalmente quando o app_offline.htm arquivo é 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 fora do processo: o módulo tenta relançar o processo quando recebe uma nova solicitação e continua tentando reiniciar o processo em solicitações de entrada subsequentes, a menos que o aplicativo não inicie o número de vezes rapidFailsPerMinute no último minuto de rolagem.

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 sublinhados, um carimbo de data/hora, uma ID de processo e uma extensão de arquivo (.log) são adicionados ao último segmento do caminho stdoutLogFile . Se .\logs\stdout for fornecido como um valor, um log stdout de exemplo será salvo como stdout_20180205194132_1934.log na pasta quando salvo em logs 5/02/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 temporariamente esse valor no web.config arquivo para forçar a Página de Exceção do Desenvolvedor a ser carregada 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

Uma alternativa para definir o ambiente diretamente web.config é incluir a <EnvironmentName> propriedade no perfil de publicação (.pubxml) ou no arquivo de projeto. Essa abordagem define o ambiente quando web.config 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 for detectado no diretório raiz de um aplicativo, o Módulo ASP.NET Core tentará desligar normalmente o aplicativo e parar de processar 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 app_offline.htm arquivo está presente, o Módulo ASP.NET Core responde às solicitações enviando de volta o conteúdo do app_offline.htm arquivo. Quando o app_offline.htm arquivo é 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 do 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 acrescentando o carimbo de data/hora, a ID do processo e a extensão de arquivo (.log) ao último segmento do stdoutLogFile caminho (normalmente stdout) delimitado por sublinhados. Se o stdoutLogFile caminho terminar, stdoutum log para um aplicativo com um PID de 1934 criado em 5/02/2018 às 19:42:32 terá o nome stdout_20180205194132_1934.logdo arquivo.

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 .\log\relativo. Confirme se a identidade do usuário AppPool 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 Serviço de Aplicativo do Azure implantação, o SDK da Web define o stdoutLogFile valor como \\?\%home%\LogFiles\stdout. A %home variável de ambiente é predefinida para aplicativos hospedados por Serviço de Aplicativo do Azure.

Para criar regras de filtro de log, consulte as regras aplicar filtro de log na seção de código da documentação de log do ASP.NET Core.

Para obter mais informações sobre formatos de caminho, consulte 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 o <handlerSettings> elemento ao <aspNetCore> elemento em 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 são 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 de 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.

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

Modificar o tamanho da pilha

Só se aplica ao usar o modelo de hospedagem em processo.

Configure o tamanho da pilha gerenciada usando a stackSize configuração em bytes em web.config. O tamanho padrão é 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 Kestrel usa o protocolo HTTP. Não há risco de escutar o tráfego entre o módulo e Kestrel de um local fora do servidor.

Um token de emparelhamento é usado para garantir que as solicitações recebidas pelo Kestrel IIS foram proxiedas pelo IIS e não vieram de alguma 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 de token de emparelhamento e o tráfego entre o módulo e Kestrel não estão acessíveis a partir de um local fora do servidor. Sem saber o valor do token de emparelhamento, um invasor 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 applicationHost.config arquivo 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:

  1. Desabilite a configuração compartilhada de IIS.
  2. Execute o instalador.
  3. Exporte o arquivo atualizado applicationHost.config para o compartilhamento.
  4. 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:

  1. No sistema de hospedagem, navegue até %windir%\System32\inetsrv.
  2. Localize o aspnetcore.dll arquivo.
  3. Clique com o botão direito do mouse no arquivo e selecione Propriedades no menu contextual.
  4. 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 do 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

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

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

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

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 fora do processo, o módulo só funciona com 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> diferencia maiúsculas de minúsculas e inprocessoutofprocess 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 Kestrel servidor. 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 e inprocessoutofprocess valores válidos.

Kestrel o servidor é 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.

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 ASP.NET Core, consulte módulos do IIS com 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 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 ASP.NET Core é compatível com versões de LTS do .NET.

Alterações interruptivas e avisos de segurança são relatados no repositório Comunicados. Os anúncios podem ser limitados a uma versão específica selecionando um filtro de 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 InheritInChildApplications propriedade está definida para false indicar que as configurações especificadas dentro do <elemento de localização> 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 Host 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 fora do processo (OutOfProcess/outofprocess).

OutOfProcess
outofprocess
processesPerApplication

Atributo inteiro opcional.

Especifica o número de instâncias do processo especificado na processPath configuração que podem ser ativadas por aplicativo.

†Para hospedagem em processo, o valor é limitado a 1.

A configuração processesPerApplication é desencorajada. Esse atributo será removido em uma versão futura.

Padrão: 1
Mín.: 1
Máximo: 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 em processPath que o processo especificado 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 aguarda o desligamento normal do executável quando o app_offline.htm arquivo é 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 rapidFailsPerMinute configuração.

Ao hospedar fora do processo: o módulo tenta relançar o processo quando recebe uma nova solicitação e continua tentando reiniciar o processo em solicitações de entrada subsequentes, a menos que o aplicativo não inicie rapidFailsPerMinute o número de vezes no último minuto de rolagem.

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 true, stdout e stderr para o processo especificado são processPath redirecionados para o arquivo especificado em stdoutLogFile.

false
stdoutLogFile

Atributo de cadeia de caracteres opcional.

Especifica o caminho de arquivo relativo ou absoluto para o qual stdout e stderr do processo especificado processPath são registrados. 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 sublinhados, um carimbo de data/hora, uma ID do processo e uma extensão de arquivo (.log) são adicionados ao último segmento do stdoutLogFile caminho. Se .\logs\stdout for fornecido como um valor, um log stdout de exemplo será salvo como stdout_20180205194132_1934.log na pasta quando salvo em logs 5/02/2018 às 19:41:32 com uma ID de processo de 1934.

aspnetcore-stdout

Configurando 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. ASPNETCORE_ENVIRONMENT configura o ambiente do aplicativo para Development. Um desenvolvedor pode definir temporariamente esse valor no web.config arquivo para forçar a Página de Exceção do Desenvolvedor a ser carregada 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

Uma alternativa para definir o ambiente diretamente web.config é incluir a <EnvironmentName> propriedade no perfil de publicação (.pubxml) ou no arquivo de projeto. Essa abordagem define o ambiente quando web.config 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 for detectado no diretório raiz de um aplicativo, o Módulo ASP.NET Core tentará desligar normalmente o aplicativo e parar de processar 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 app_offline.htm arquivo está presente, o Módulo ASP.NET Core responde às solicitações enviando de volta o conteúdo do app_offline.htm arquivo. Quando o app_offline.htm arquivo é 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, consulte HTTP Errors <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 são gravados (use IIS AppPool\{APP POOL NAME} para fornecer permissão de gravação, em que 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.

O uso do log stdout só é recomendado para solucionar problemas de inicialização do 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 acrescentando o carimbo de data/hora, a ID do processo e a extensão de arquivo (.log) ao último segmento do stdoutLogFile caminho (normalmente stdout) delimitado por sublinhados. Se o stdoutLogFile caminho terminar, stdoutum log para um aplicativo com um PID de 1934 criado em 5/02/2018 às 19:42:32 terá o nome stdout_20180205194132_1934.logdo arquivo.

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 .\log\relativo. Confirme se a identidade 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 Serviço de Aplicativo do Azure implantação, o SDK da Web define o stdoutLogFile valor como \\?\%home%\LogFiles\stdout. A %home variável de ambiente é predefinida para aplicativos hospedados por Serviço de Aplicativo do Azure.

Para obter mais informações sobre formatos de caminho, consulte 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 o <handlerSettings> elemento ao <aspNetCore> elemento em 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>

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

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

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 Kestrel usa o protocolo HTTP. Não há risco de escutar o tráfego entre o módulo e Kestrel de um local fora do servidor.

Um token de emparelhamento é usado para garantir que as solicitações recebidas pelo Kestrel IIS foram proxies e não vieram de alguma 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 de token de emparelhamento e o tráfego entre o módulo e Kestrel não podem ser acessados a partir de um local fora do servidor. Sem saber o valor do token de emparelhamento, um invasor 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 ASP.NET Core é executado com os privilégios da TrustedInstaller conta. 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 gera um erro negado de acesso ao tentar definir as configurações do applicationHost.config módulo no arquivo 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:

  1. Desabilite a configuração compartilhada de IIS.
  2. Execute o instalador.
  3. Exporte o arquivo atualizado applicationHost.config para o compartilhamento.
  4. 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:

  1. No sistema de hospedagem, navegue até %windir%\System32\inetsrv.
  2. Localize o aspnetcore.dll arquivo.
  3. Clique com o botão direito do mouse no arquivo e selecione Propriedades no menu contextual.
  4. 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 do 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, 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

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

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

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

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 para Kestrel uma porta aleatória para o aplicativo, que não é 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 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 Kestrel de obter a solicitação do módulo, a solicitação será enviada por push para o pipeline de middleware 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 a base de caminho para levar em conta o encaminhamento da solicitação para 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 ASP.NET Core, consulte módulos do IIS com 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 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 Host 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 aguarda o desligamento normal do executável quando o app_offline.htm arquivo é 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

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

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

Se um arquivo com o nome app_offline.htm for detectado no diretório raiz de um aplicativo, o módulo ASP.NET Core tentará desligar normalmente o aplicativo e parar de processar 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 app_offline.htm arquivo está presente, o Módulo ASP.NET Core responde às solicitações enviando de volta o conteúdo do app_offline.htm arquivo. Quando o app_offline.htm arquivo é removido, a próxima solicitação inicia o aplicativo.

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, consulte HTTP Errors <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 do 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.

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

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

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

Para criar regras de filtro de log, consulte a seção Aplicar regras de filtro de log na seção de código da documentação de 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 Kestrel usa o protocolo HTTP. Não há risco de escutar o tráfego entre o módulo e Kestrel de um local fora do servidor.

Um token de emparelhamento é usado para garantir que as solicitações recebidas pelo Kestrel IIS foram proxiedas pelo IIS e não vieram de alguma 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 de token de emparelhamento e o tráfego entre o módulo e Kestrel não estão acessíveis a partir de um local fora do servidor. Sem saber o valor do token de emparelhamento, um invasor 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. 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:

  1. Desabilite a configuração compartilhada de IIS.
  2. Execute o instalador.
  3. Exportar o arquivo applicationHost.config atualizado para o compartilhamento.
  4. 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:

  1. No sistema de hospedagem, navegue até %windir%\System32\inetsrv.
  2. Localize o arquivo aspnetcore.dll.
  3. Clique com o botão direito do mouse no arquivo e selecione Propriedades no menu contextual.
  4. 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 do 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