Módulo do 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 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

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>

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

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.

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:

1. Desabilite a configuração compartilhada de IIS.
2. Execute o instalador.
3. Exporte 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, acesse %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 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.

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

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

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

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

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

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.

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.

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

1. Desabilite a configuração compartilhada de IIS.
2. Execute o instalador.
3. Exporte 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, acesse %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 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:

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

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

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>

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.

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

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.

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">
</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, 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.

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