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

Observação

Esta não é a versão mais recente deste artigo. Para a versão atual, consulte a versão .NET 10 deste artigo.

Advertência

Esta versão do ASP.NET Core não é mais suportada. Para obter mais informações, consulte a Política de suporte do .NET e do .NET Core. Para a versão atual, consulte a versão .NET 9 deste artigo.

O ASP.NET Core Module (ANCM) é um módulo nativo do IIS que se liga ao pipeline do IIS, permitindo que ASP.NET aplicações do Core trabalhem com o IIS. Executar apps ASP.NET Core com IIS de duas maneiras:

Alojar uma aplicação ASP.NET Core dentro do processo de trabalho do IIS (w3wp.exe), chamado modelo de alojamento em processo.
Redirigir pedidos web para uma aplicação backend ASP.NET Core que está a correr no servidor Kestrel, conhecido como o modelo de alojamento fora do processo.

Existem compensações entre cada um dos modelos anfitriões. Por padrão, o modelo de alojamento em processo é utilizado devido ao melhor desempenho e diagnóstico.

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

Implementações de servidores web no ASP.NET Core

Instalar ASP.NET Módulo Núcleo (ANCM)

O ASP.NET Core Module (ANCM) é instalado com o .NET Core Runtime do .NET Core Hosting Bundle. O módulo ASP.NET Core é retroativamente e proativamente compatível com versões suportadas de .NET.

Alterações urgentes e avisos de segurança são reportados no repositório de Anúncios. Os anúncios podem ser limitados a uma versão específica selecionando um filtro de Rótulos .

Descarregue o instalador usando o seguinte link:

Instalador atual do .NET Core Hosting Bundle (download direto)

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

Para uma experiência tutorial sobre como publicar uma aplicação ASP.NET Core num servidor IIS, consulte Publicar uma aplicação ASP.NET Core para IIS.

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

Aloja uma aplicação ASP.NET Core dentro do processo worker IIS (w3wp.exe), chamada modelo de alojamento em processo.
Encaminhe os pedidos web para uma aplicação ASP.NET Core de backend que executa no servidor Kestrel, denominado o modelo de alojamento fora do processo.

Versões suportadas do Windows:

Windows 7 ou posterior
Windows Server 2012 R2 ou posterior

Quando hospedado em processo, o módulo utiliza uma implementação de servidor em processo para IIS, chamada IIS HTTP Server (IISHttpServer).

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

As aplicações do ASP.NET Core adotam por padrão o modelo de alojamento em processo.

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

O servidor HTTP IIS (IISHttpServer) é usado em vez de Kestrel servidor. Para o processo em andamento, CreateDefaultBuilder chama UseIIS para:
- Registe o IISHttpServer.
- Configura a porta e o caminho base onde o servidor deve escutar quando estiver a correr atrás do Módulo ASP.NET Core.
- Configure o host para captar erros de arranque.
O atributo requestTimeout não se aplica ao alojamento em processo.
Partilhar um conjunto de aplicações entre aplicações não é suportado. Use um pool de aplicações por aplicação.
Ao usar o Web Deploy ou colocar manualmente um app_offline.htm ficheiro na implementação, a aplicação pode não desligar imediatamente se houver uma ligação aberta. Por exemplo, uma ligação WebSocket pode atrasar o encerramento da aplicação.
A arquitetura (bitness) da aplicação e o runtime instalado (x64 ou x86) devem corresponder à arquitetura do pool de aplicações.
São detetadas desconexões do cliente. O HttpContext.RequestAborted token de cancelamento é cancelado quando o cliente se desliga.
Em ASP.NET Core 2.2.1 ou anterior, GetCurrentDirectory devolve o diretório worker do processo iniciado pelo IIS em vez do diretório da aplicação (por exemplo, C:\Windows\System32\inetsrv para w3wp.exe).

Para código de exemplo que define o diretório atual da aplicação, veja a CurrentDirectoryHelpers classe. Chame o método SetCurrentDirectory. Chamadas subsequentes para GetCurrentDirectory fornecem o diretório do aplicativo.
Quando o alojamento está em processo, AuthenticateAsync não é chamado internamente para inicializar um utilizador. Portanto, uma implementação de IClaimsTransformation usada para transformar declarações após cada autenticação não é ativada por padrão. Ao transformar reivindicações com uma IClaimsTransformation implementação, 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();
}
```
- Implementações de Pacotes Web (em ficheiro único) não são suportadas.

Modelo de alojamento fora de processo

Para configurar uma aplicação para alojamento fora do processo, defina o valor da <AspNetCoreHostingModel> propriedade para OutOfProcess no ficheiro do projeto (.csproj):

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

A hospedagem em processo é estabelecida com InProcess, que é o valor predefinido.

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

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

Para operações fora do processo, são feitas chamadas de CreateDefaultBuilder para UseIISIntegration.

Configura a porta e o caminho base onde o servidor deve escutar quando estiver a correr atrás do Módulo ASP.NET Core.
Configure o host para captar erros de arranque.

Alterações no modelo de alojamento

Se a hostingModel configuração for alterada no web.config ficheiro (explicado na secção Configuração com web.config), o módulo recicla o processo de trabalho para o IIS.

No IIS Express, o módulo não recicla o processo de trabalho, mas sim desencadeia um desligamento gradual do processo atual do IIS Express. O pedido seguinte à aplicação gera um novo processo IIS Express.

Nome do processo

Process.GetCurrentProcess().ProcessName reporta w3wp/iisexpress (em processo) ou dotnet (fora de processo).

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

O Módulo Núcleo ASP.NET também pode:

Defina variáveis de ambiente para o processo do trabalhador.
Registar a saída de stdout no armazenamento de ficheiros para solução de problemas de arranque.
Encaminhar tokens de autenticação do Windows.

Como instalar e utilizar o ASP.NET Core Module (ANCM)

Para instruções sobre como instalar o ASP.NET Core Module, consulte Instalar o .NET Core Hosting Bundle. O módulo ASP.NET Core é retroativamente e proativamente compatível com versões suportadas de .NET.

Alterações urgentes e avisos de segurança são reportados no repositório de Anúncios. Os anúncios podem ser limitados a uma versão específica selecionando um filtro de Rótulos .

Configuração com web.config

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

O ficheiro seguinte web.config é publicado para uma implementação dependente do framework e configura o ASP.NET Core Module para lidar com pedidos 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 seguinteweb.config é publicado para uma implementação autónoma:

<?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 definições especificadas dentro do elemento <location> não são herdadas por aplicações que residem num subdiretório da aplicação.

Quando uma aplicação é implementada no Azure App Service, o stdoutLogFile caminho é definido como \\?\%home%\LogFiles\stdout. O caminho guarda os registos stdout na LogFiles pasta, que é uma localização criada automaticamente pelo serviço.

Para informações sobre a configuração de subaplicações IIS, veja Host ASP.NET Core no Windows com IIS.

Atributos do elemento aspNetCore

Attribute	Description	Predefinido
`arguments`	Atributo de texto opcional. Argumentos para o executável especificados em processPath.
`disableStartUpErrorPage`	Atributo booleano opcional. Se for verdadeiro, a página 502.5 - Falha de Processo é suprimida, e a página de código de estado 502 configurada no web.config tem prioridade.	`false`
`forwardWindowsAuthToken`	Atributo booleano opcional. Se for verdade, o token é encaminhado para o processo filho que ouve `%ASPNETCORE_PORT%` como um cabeçalho `'MS-ASPNETCORE-WINAUTHTOKEN'` por pedido. É responsabilidade desse processo chamar o CloseHandle neste token por solicitação.	`true`
`hostingModel`	Atributo de texto opcional. Especifica o modelo de alojamento 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 especificadas na definição processPath que podem ser ativadas por aplicação. †Para alojamento em processo, o valor está limitado a `1`. A configuração `processesPerApplication` é desencorajada. Este atributo será removido numa versão futura.	Predefinição: `1` Min: `1` Max: `100`†
`processPath`	Atributo de string obrigatório. Caminho para o executável que lança um processo que escuta pedidos HTTP. Caminhos relativos são suportados. Se o caminho começar com `.`, o caminho é considerado relativo à raiz do sítio.
`rapidFailsPerMinute`	Atributo inteiro opcional. Especifica o número de vezes que o processo especificado em processPath pode falhar por minuto. Se este limite for ultrapassado, o módulo deixa de iniciar o processo pelo resto do minuto. Não é suportado para alojamento dentro do processo.	Predefinição: `10` Min: `0` Max: `100`
`requestTimeout`	Atributo opcional de intervalo temporal. Especifica a duração durante a qual o ASP.NET Módulo Núcleo espera uma resposta do processo que ouve em %ASPNETCORE_PORT%. Nas versões do Módulo ASP.NET Core lançadas com o ASP.NET Core 2.1 ou posterior, o `requestTimeout` é especificado em horas, minutos e segundos. Não se aplica a alojamentos que estão em processo. Para alojamento em processo, o módulo espera que a aplicação processe o pedido. Os valores válidos para segmentos de minutos e segundos da sequência situam-se no intervalo de 0 a 59. A utilização de 60 no valor durante minutos ou segundos resulta num erro de 500 - Servidor Interno.	Predefinição: `00:02:00` Min: `00:00:00` Max: `360:00:00`
`shutdownTimeLimit`	Atributo inteiro opcional. Duração em segundos em que o módulo espera que o executável se desligue graciosamente quando o `app_offline.htm` ficheiro é detetado.	Predefinição: `10` Min: `0` Max: `600`
`startupTimeLimit`	Atributo inteiro opcional. A duração em segundos que o módulo espera até que o executável inicie um processo que escuta na porta. Se este limite de tempo for ultrapassado, o módulo interrompe o processo. Quando se aloja em processo: O processo não é reiniciado e não utiliza a definição rapidFailsPerMinute. Quando hospedado fora do processo: O módulo tenta reiniciar o processo quando recebe um novo pedido e continua a tentar reiniciar o processo em pedidos recebidos subsequentes, a menos que a aplicação não inicie o rapidFailsPerMinute várias vezes no último minuto rolante. Um valor de 0 (zero) não é considerado um tempo limite infinito.	Predefinição: `120` Min: `0` Max: `3600`
`stdoutLogEnabled`	Atributo booleano opcional. Se for verdade, stdout e stderr para o processo especificado no processoPath são redirecionados para o ficheiro especificado no stdoutLogFile.	`false`
`stdoutLogFile`	Atributo de texto opcional. Especifica o caminho relativo ou absoluto do ficheiro para o qual stdout e stderr do processo especificado em processPath são registados. Os caminhos relativos são relativos à raiz do sítio. Qualquer caminho que comece com `.` é relativo à raiz do sítio e todos os outros caminhos são tratados como caminhos absolutos. Quaisquer pastas fornecidas no caminho são criadas pelo módulo quando o ficheiro de registo é criado. Usando delimitadores de sublinhado, um carimbo temporal, ID de processo e extensão de ficheiro (`.log`) são adicionados ao último segmento do caminho stdoutLogFile . Se `.\logs\stdout` for fornecido como valor, um registo stdout de exemplo é guardado como `stdout_20180205194132_1934.log` na `logs` pasta quando guardado a 5/2/2018 às 19:41:32 com ID de processo de 1934.	`aspnetcore-stdout`

Definir variáveis de ambiente

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

O exemplo seguinte estabelece duas variáveis de ambiente em web.config. ASPNETCORE_ENVIRONMENT Configura o ambiente da aplicação para Development. Um programador pode definir temporariamente este valor no web.config ficheiro para forçar o carregamento da Página de Exceção do Desenvolvedor ao depurar uma exceção de aplicação. CONFIG_DIR é um exemplo de variável de ambiente definida pelo utilizador, onde o programador escreveu código que lê o valor no arranque para formar um caminho para carregar o ficheiro de configuração da aplicação.

<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 à definição direta do ambiente em web.config é incluir a propriedade <EnvironmentName> no perfil de publicação (.pubxml) ou no ficheiro de projeto. Esta abordagem define o ambiente web.config quando o projeto é publicado:

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

Advertência

Define apenas a ASPNETCORE_ENVIRONMENT variável de ambiente para Development nos servidores de staging e testes que não são acessíveis a redes não confiáveis, como a Internet.

`app_offline.htm`

Se um ficheiro com esse nome app_offline.htm for detetado no diretório raiz de uma aplicação, o Módulo Núcleo ASP.NET tenta desligar a aplicação de forma gradual e parar de processar pedidos recebidos. Se a aplicação continuar a correr após o número de segundos definidos em shutdownTimeLimit, o ASP.NET Módulo Núcleo interrompe o processo em execução.

Enquanto o app_offline.htm ficheiro está presente, o ASP.NET Módulo Núcleo responde aos pedidos enviando de volta o conteúdo do app_offline.htm ficheiro. Quando o app_offline.htm ficheiro é removido, o próximo pedido inicia a aplicação.

Ao usar o modelo de alojamento fora de processo, a aplicação pode não desligar imediatamente se houver uma ligação aberta. Por exemplo, uma ligação WebSocket pode atrasar o encerramento da aplicação.

Página de erro de arranque

Tanto o alojamento em execução como o fora de execução produzem páginas de erro personalizadas quando falham ao iniciar a aplicação.

Se o Módulo ASP.NET Core não encontrar o manipulador de pedidos em processo ou fora de processo, aparece uma página de código de estado 500.0 - Falha ao Carregar o Manipulador Em Processo/Fora de Processo.

Para alojamento em processo, se o Módulo ASP.NET Core falhar ao iniciar a aplicação, uma página de código de estado 500.30 - Falha de Início aparece.

Para alojamento fora do processo, se o ASP.NET Core Module falhar em iniciar o processo backend ou se o processo backend iniciar mas não ouvir na porta configurada, aparece uma página com o código de status 502.5 - Falha de Processo.

Para suprimir esta página e reverter para a página padrão do código de estado do IIS 5xx, use o disableStartUpErrorPage atributo. Para mais informações sobre a configuração de mensagens de erro personalizadas, consulte Erros <httpErrors>HTTP .

Criação e redirecionamento de registos

O Módulo ASP.NET Core redireciona a saída da consola stdout e stderr para o disco, se os atributos stdoutLogEnabled e stdoutLogFile do elemento aspNetCore estiverem definidos. Quaisquer pastas no stdoutLogFile caminho são criadas pelo módulo quando o ficheiro de registo é criado. O pool de aplicações deve ter acesso de escrita ao local onde os registos são escritos (usar IIS AppPool\<app_pool_name> para fornecer permissão de escrita).

Os registos não são rotacionados, a menos que haja reciclagem/reinício de processos. É responsabilidade do hoster limitar o espaço em disco que os registos consomem.

Usar o registo stdout é apenas recomendado para resolver problemas de arranque de aplicações ao hospedar no IIS ou ao usar suporte em tempo de desenvolvimento para IIS com o Visual Studio, não durante a depuração local e a execução da aplicação com o IIS Express.

Não uses o log STDOUT para o registo geral de aplicações. Para registos rotineiros numa aplicação ASP.NET Core, use uma biblioteca de registos que limite o tamanho dos ficheiros de registo e rode os registos. Para mais informações, consulte provedores de registo de terceiros.

Um carimbo temporal e uma extensão do ficheiro são adicionados automaticamente quando o ficheiro de registo é criado. O nome do ficheiro de registo é composto pela adição do timestamp, ID do processo e extensão do ficheiro (.log) ao último segmento do caminho stdoutLogFile (tipicamente stdout) delimitado por sublinhados. Se o stdoutLogFile caminho terminar em stdout, um registo para uma aplicação com PID de 1934 criada a 05/02/2018 às 19:42:32 tem o nome de ficheiro stdout_20180205194132_1934.log.

Se stdoutLogEnabled for falso, os erros que ocorrem no arranque da aplicação são capturados e registados no log de eventos até ao limite de 30 KB. Após o arranque, todos os registos adicionais são descartados.

O seguinte elemento de exemplo aspNetCore configura o registo stdout no caminho relativo .\log\. Confirme que a identidade do utilizador do AppPool tem permissão para escrever no caminho fornecido.

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

Ao publicar uma aplicação para implementação do Azure App Service, o Web SDK define o stdoutLogFile valor para \\?\%home%\LogFiles\stdout. A %home variável de ambiente é pré-definida para aplicações alojadas no Azure App Service.

Para criar regras de filtro de registo, consulte a secção Aplicar regras de filtro de registo no código da documentação do registo do ASP.NET Core.

Para mais informações sobre formatos de caminho, veja Formatos de caminho de ficheiro em sistemas Windows.

Registos de diagnóstico melhorados

O Módulo Núcleo ASP.NET é configurável para fornecer registos de diagnóstico aprimorados. Adicione o <handlerSettings> elemento ao <aspNetCore> elemento em web.config. Ao definir o debugLevel como TRACE, expõe uma maior fidelidade da informação 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>

Quaisquer pastas no caminho (logs no exemplo anterior) são criadas pelo módulo quando o ficheiro de registo é criado. O pool de aplicações deve ter acesso de escrita ao local onde os registos são escritos (use IIS AppPool\{APP POOL NAME}, onde o marcador {APP POOL NAME} de posição é o nome do pool de aplicações, para fornecer permissão de escrita).

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

Níveis (por ordem do menor ao mais prolixo):

ERROR
ADVERTÊNCIA
INFORMAÇÃO
RASTREIO

Localizações (são permitidas várias localizações):

CONSOLA
REGISTO DE EVENTOS
FILE

As definições do handler também podem ser fornecidas através de variáveis de ambiente:

ASPNETCORE_MODULE_DEBUG_FILE: Caminho para o ficheiro de registo de depuração. (Padrão: aspnetcore-debug.log)
ASPNETCORE_MODULE_DEBUG: Debugar a definição do nível.

Advertência

Não deixe o registo de depuração ativado na implementação por mais tempo do que o necessário para resolver um problema. O tamanho do log não é limitado. Deixar o registo de depuração ativado pode esgotar o espaço disponível em disco e fazer com que o servidor ou serviço de aplicação colapse.

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

Modificar o tamanho da pilha

Só se aplica quando se utiliza o modelo de alojamento em processo.

Configure o tamanho gerido da pilha usando a stackSize definiçã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 do proxy utiliza o protocolo HTTP e um token de emparelhamento

Aplica-se apenas a alojamento fora do processo.

O proxy criado entre o ASP.NET Módulo Core e Kestrel utiliza o protocolo HTTP. Não há risco de escutar o tráfego entre o módulo e Kestrel a partir de um local fora do servidor.

Um token de emparelhamento é usado para garantir que as solicitações recebidas por Kestrel foram encaminhadas por proxy pelo IIS e não provenientes de outra fonte. O token de emparelhamento é criado e definido numa variável de ambiente (ASPNETCORE_TOKEN) pelo módulo. O token de emparelhamento também é definido num cabeçalho (MS-ASPNETCORE-TOKEN) em cada pedido proxy. O Middleware IIS verifica cada pedido que recebe para confirmar se o valor do cabeçalho do token de emparelhamento corresponde ao valor da variável ambiental. Se os valores dos tokens forem incompatíveis, o pedido é registado e rejeitado. A variável de ambiente do 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 conhecer o valor do token de emparelhamento, um ciberatacante não pode submeter pedidos que contornem a verificação no Middleware IIS.

Módulo ASP.NET Core com uma Configuração Partilhada do IIS

O instalador ASP.NET Core Module funciona 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 partilha usado pela Configuração Partilhada IIS, o instalador gera um erro de acesso negado ao tentar configurar as definições do módulo no applicationHost.config ficheiro da partilha.

Ao usar uma Configuração Compartilhada do IIS na mesma máquina da instalação do IIS, execute o instalador do ASP.NET Core Hosting Bundle com o OPT_NO_SHARED_CONFIG_CHECK parâmetro definido para 1:

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

Quando o caminho para a configuração partilhada não estiver na mesma máquina que a instalação do IIS, siga estes passos:

Desative a configuração partilhada do IIS.
Executar o instalador.
Exporta o ficheiro atualizado applicationHost.config para a partilha.
Reative a Configuração Partilhada IIS.

Registos de instalação da versão do módulo e do Pacote de Hospedagem

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

No sistema de alojamento, navegue até %windir%\System32\inetsrv.
Localiza o aspnetcore.dll ficheiro.
Clique com o botão direito no ficheiro e selecione Propriedades no menu contextual.
Selecione o separador Detalhes . A versão do ficheiro e a versão do produto representam a versão instalada do módulo.

Os registos do instalador do Hosting Bundle para o módulo encontram-se em C:\Users\%UserName%\AppData\Local\Temp. O arquivo é chamado dd_DotNetCoreWinSvrHosting__{TIMESTAMP}_000_AspNetCoreModule_x64.log.

Localizações de módulos, esquemas e ficheiros 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

Schema

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 ficheiros podem ser encontrados pesquisando aspnetcore dentro do applicationHost.config ficheiro.

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

Aloja uma aplicação ASP.NET Core dentro do processo worker IIS (w3wp.exe), chamada modelo de alojamento em processo.
Encaminhe os pedidos web para uma aplicação ASP.NET Core de backend que executa no servidor Kestrel, denominado o modelo de alojamento fora do processo.

Versões suportadas do Windows:

Windows 7 ou posterior
Windows Server 2008 R2 ou posterior

Quando hospedado em processo, o módulo utiliza uma implementação de servidor em processo para IIS, chamada IIS HTTP Server (IISHttpServer).

Quando hospedado 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 uma aplicação para alojamento em processo, adicione a <AspNetCoreHostingModel> propriedade ao ficheiro do projeto da aplicação com o valor de InProcess (o alojamento fora do processo é definido com OutOfProcess):

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

O modelo de alojamento em processo não é suportado em aplicações ASP.NET Core que visam o .NET Framework.

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

Se a <AspNetCoreHostingModel> propriedade não estiver presente no ficheiro, o valor padrão é OutOfProcess.

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

O servidor HTTP IIS (IISHttpServer) é usado em vez de Kestrel servidor. Para o processo em andamento, CreateDefaultBuilder chama UseIIS para:
- Registe o IISHttpServer.
- Configura a porta e o caminho base onde o servidor deve escutar quando estiver a correr atrás do Módulo ASP.NET Core.
- Configure o host para captar erros de arranque.
O atributo requestTimeout não se aplica ao alojamento em processo.
Partilhar um conjunto de aplicações entre aplicações não é suportado. Use um pool de aplicações por aplicação.
Ao usar Web Deploy ou colocar manualmente um ficheiro app_offline.htm na implementação, a aplicação pode não desligar imediatamente se houver uma ligação aberta. Por exemplo, uma ligação websocket pode atrasar o encerramento da aplicação.
A arquitetura (bitness) da aplicação e o runtime instalado (x64 ou x86) devem corresponder à arquitetura do pool de aplicações.
São detetadas desconexões do cliente. O token de cancelamento HttpContext.RequestAborted é cancelado quando o cliente se desliga.
No ASP.NET Core 2.2.1 ou anterior, GetCurrentDirectory devolve o diretório worker do processo iniciado pelo IIS em vez do diretório da aplicação (por exemplo, C:\Windows\System32\inetsrv para w3wp.exe).

Para código de exemplo que define o diretório atual da aplicação, veja a classe CurrentDirectoryHelpers. Chame o método SetCurrentDirectory. Chamadas subsequentes para GetCurrentDirectory fornecem o diretório do aplicativo.
Quando o alojamento está em processo, AuthenticateAsync não é chamado internamente para inicializar um utilizador. Portanto, uma implementação de IClaimsTransformation usada para transformar declarações após cada autenticação não é ativada por padrão. Ao transformar reivindicações com uma IClaimsTransformation implementação, 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 alojamento fora de processo

Para configurar uma aplicação para alojamento fora do processo, utilize uma das seguintes abordagens no ficheiro do projeto:

Não especificar a propriedade <AspNetCoreHostingModel>. Se a <AspNetCoreHostingModel> propriedade não estiver presente no ficheiro, o valor padrão é OutOfProcess.
Defina o valor da <AspNetCoreHostingModel> propriedade para OutOfProcess (o alojamento em processo é definido com InProcess):

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

O valor é insensível a maiúsculas, assim inprocess e outofprocess são valores válidos.

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

Para fora de processo, o CreateDefaultBuilder chama UseIISIntegration para:

Configura a porta e o caminho base onde o servidor deve escutar quando estiver a correr atrás do Módulo ASP.NET Core.
Configure o host para captar erros de arranque.

Alterações no modelo de alojamento

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

Nome do processo

Process.GetCurrentProcess().ProcessName reporta w3wp/iisexpress (em processo) ou dotnet (fora de processo).

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

O Módulo Núcleo ASP.NET também pode:

Defina variáveis de ambiente para o processo do trabalhador.
Registar a saída de stdout no armazenamento de ficheiros para solução de problemas de arranque.
Encaminhar tokens de autenticação do Windows.

Como instalar e utilizar o ASP.NET Core Module (ANCM)

Alterações urgentes e avisos de segurança são reportados no repositório de Anúncios. Os anúncios podem ser limitados a uma versão específica selecionando um filtro de Rótulos .

Configuração com web.config

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

O ficheiro web.config seguinte é publicado para uma implementação dependente do framework e configura o Módulo ASP.NET Core para lidar com os pedidos do 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 seguinteweb.config é publicado para uma implementação autónoma:

<?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 está configurada como false para indicar que as definições especificadas no elemento <localização> não são herdadas por aplicações que residem num subdiretório da aplicação principal.

Quando uma aplicação é implementada no Azure App Service, o stdoutLogFile caminho é definido como \\?\%home%\LogFiles\stdout. O caminho guarda os registos stdout na pasta LogFiles , que é uma localização criada automaticamente pelo serviço.

Para informações sobre a configuração de subaplicações IIS, veja Host ASP.NET Core no Windows com IIS.

Atributos do elemento aspNetCore

Attribute	Description	Predefinido
`arguments`	Atributo de texto opcional. Argumentos para o executável especificados em `processPath`.
`disableStartUpErrorPage`	Atributo booleano opcional. Se for verdadeiro, a página 502.5 - Falha de Processo é suprimida, e a página de código de estado 502 configurada no web.config tem prioridade.	`false`
`forwardWindowsAuthToken`	Atributo booleano opcional. Se for verdade, o token é encaminhado para o processo filho que ouve em %ASPNETCORE_PORT% como um cabeçalho 'MS-ASPNETCORE-WINAUTHTOKEN' por pedido. É responsabilidade desse processo chamar o CloseHandle neste token por solicitação.	`true`
`hostingModel`	Atributo de texto opcional. Especifica o modelo de alojamento como em processo (`InProcess`/`inprocess`) ou fora de processo ().`OutOfProcess`/`outofprocess`	`OutOfProcess` `outofprocess`
`processesPerApplication`	Atributo inteiro opcional. Especifica o número de instâncias do processo especificadas na `processPath` definição que podem ser ativadas por aplicação. †Para alojamento em processo, o valor está limitado a `1`. A configuração `processesPerApplication` é desencorajada. Este atributo será removido numa versão futura.	Predefinição: `1` Min: `1` Max: `100`†
`processPath`	Atributo de string obrigatório. Caminho para o executável que lança um processo que escuta pedidos HTTP. Caminhos relativos são suportados. Se o caminho começar com `.`, o caminho é considerado relativo à raiz do sítio.
`rapidFailsPerMinute`	Atributo inteiro opcional. Especifica o número de vezes que o processo especificado em `processPath` pode crashar por minuto. Se este limite for ultrapassado, o módulo deixa de iniciar o processo pelo resto do minuto. Não é suportado para alojamento dentro do processo.	Predefinição: `10` Min: `0` Max: `100`
`requestTimeout`	Atributo opcional de intervalo temporal. Especifica a duração durante a qual o ASP.NET Módulo Núcleo espera uma resposta do processo que ouve em %ASPNETCORE_PORT%. Nas versões do Módulo ASP.NET Core lançadas com o ASP.NET Core 2.1 ou posterior, o `requestTimeout` é especificado em horas, minutos e segundos. Não se aplica a alojamentos que estão em processo. Para alojamento em processo, o módulo espera que a aplicação processe o pedido. Os valores válidos para segmentos de minutos e segundos da sequência situam-se no intervalo de 0 a 59. A utilização de 60 no valor durante minutos ou segundos resulta num erro de 500 - Servidor Interno.	Predefinição: `00:02:00` Min: `00:00:00` Max: `360:00:00`
`shutdownTimeLimit`	Atributo inteiro opcional. Duração em segundos em que o módulo espera que o executável se desligue graciosamente quando o `app_offline.htm` ficheiro é detetado.	Predefinição: `10` Min: `0` Max: `600`
`startupTimeLimit`	Atributo inteiro opcional. A duração em segundos que o módulo espera até que o executável inicie um processo que escuta na porta. Se este limite de tempo for ultrapassado, o módulo interrompe o processo. Durante o alojamento em processo: O processo não é reiniciado nem utiliza a configuração. Quando hospedado fora do processo: O módulo tenta reiniciar o processo quando recebe um novo pedido e continua a tentar reiniciar o processo em pedidos recebidos, a menos que a aplicação não inicie `rapidFailsPerMinute` várias vezes no último minuto móvel. Um valor de 0 (zero) não é considerado um tempo limite infinito.	Predefinição: `120` Min: `0` Max: `3600`
`stdoutLogEnabled`	Atributo booleano opcional. Se for verdade, stdout e stderr para o processo especificado em `processPath` são redirecionados para o ficheiro especificado em stdoutLogFile.	`false`
`stdoutLogFile`	Atributo de texto opcional. Especifica o caminho relativo ou absoluto do ficheiro em que `stdout` e `stderr` do processo especificado em `processPath` são registados. Os caminhos relativos são relativos à raiz do sítio. Qualquer caminho que comece com `.` é relativo à raiz do sítio e todos os outros caminhos são tratados como caminhos absolutos. Quaisquer pastas fornecidas no caminho são criadas pelo módulo quando o ficheiro de registo é criado. Usando delimitadores de sublinhado, são adicionados um carimbo temporal, ID de processo e extensão de ficheiro (`.log`) ao último segmento do `stdoutLogFile` caminho. Se `.\logs\stdout` for fornecido como valor, um registo stdout de exemplo é guardado como `stdout_20180205194132_1934.log` na `logs` pasta quando guardado a 5/2/2018 às 19:41:32 com ID de processo de 1934.	`aspnetcore-stdout`

Definindo variáveis de ambiente

O exemplo seguinte estabelece duas variáveis de ambiente. ASPNETCORE_ENVIRONMENT Configura o ambiente da aplicação para Development. Um programador pode definir temporariamente este valor no web.config ficheiro para forçar o carregamento da Página de Exceção do Desenvolvedor ao depurar uma exceção de aplicação. CONFIG_DIR é um exemplo de variável de ambiente definida pelo utilizador, onde o programador escreveu código que lê o valor no arranque para formar um caminho para carregar o ficheiro de configuração da aplicação.

<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 a definir o ambiente diretamente web.config é incluir a propriedade <EnvironmentName> no perfil de publicação (.pubxml) ou no ficheiro de projeto. Esta abordagem define o ambiente web.config quando o projeto é publicado:

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

Advertência

Define apenas a ASPNETCORE_ENVIRONMENT variável de ambiente para Development nos servidores de staging e testes que não são acessíveis a redes não confiáveis, como a Internet.

app_offline.htm

Ao usar o modelo de alojamento fora de processo, a aplicação pode não desligar imediatamente se houver uma ligação aberta. Por exemplo, uma ligação websocket pode atrasar o encerramento da aplicação.

Página de erro de arranque

Tanto o alojamento em execução como o fora de execução produzem páginas de erro personalizadas quando falham ao iniciar a aplicação.

Para alojamento em processo, se o Módulo ASP.NET Core falhar ao iniciar a aplicação, uma página de código de estado 500.30 - Falha de Início aparece.

Criação e redirecionamento de registos

O Módulo ASP.NET Core redireciona a saída da consola stdout e stderr para o disco, se os atributos stdoutLogEnabled e stdoutLogFile do elemento aspNetCore estiverem definidos. Quaisquer pastas no stdoutLogFile caminho são criadas pelo módulo quando o ficheiro de registo é criado. O app pool deve ter acesso de escrita ao local onde os registos são escritos (usar IIS AppPool\{APP POOL NAME} para fornecer permissão de escrita, onde {APP POOL NAME} é substituído pelo nome do app pool).

Os registos não são rotacionados, a menos que haja reciclagem/reinício de processos. É responsabilidade do hoster limitar o espaço em disco que os registos consomem.

O seguinte elemento de exemplo aspNetCore configura o registo stdout no caminho relativo .\log\. Confirme que a identidade do utilizador do pool de aplicações tem permissão para escrever no caminho fornecido.

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

Para mais informações sobre formatos de caminho, veja Formatos de caminho de ficheiro em sistemas Windows.

Registos de diagnóstico melhorados

<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 automaticamente pelo módulo e devem pré-existir na implementação. O app pool deve ter acesso de escrita ao local onde os registos são escritos (usar IIS AppPool\{APP POOL NAME} para fornecer permissão de escrita, onde {APP POOL NAME} é substituído pelo nome do app pool).

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

Níveis (por ordem do menor ao mais prolixo):

ERROR
ADVERTÊNCIA
INFORMAÇÃO
RASTREIO

Localizações (são permitidas várias localizações):

CONSOLA
REGISTO DE EVENTOS
FILE

As definições do handler também podem ser fornecidas através de variáveis de ambiente:

ASPNETCORE_MODULE_DEBUG_FILE: Caminho para o ficheiro de registo de depuração. (Padrão: aspnetcore-debug.log)
ASPNETCORE_MODULE_DEBUG: Debugar a definição do nível.

Advertência

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

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

Aplica-se apenas a alojamento fora do processo.

O proxy criado entre o ASP.NET Módulo Core e Kestrel utiliza o protocolo HTTP. Não há risco de escutar o tráfego entre o módulo e Kestrel a partir de um local fora do servidor.

Módulo ASP.NET Core com uma Configuração Partilhada do IIS

O instalador ASP.NET Core Module funciona 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 partilha usado pela Configuração Partilhada IIS, o instalador gera um erro de acesso negado ao tentar configurar as definições do módulo no applicationHost.config ficheiro da partilha.

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

Quando o caminho para a configuração partilhada não estiver na mesma máquina que a instalação do IIS, siga estes passos:

Desative a configuração partilhada do IIS.
Executar o instalador.
Exporta o ficheiro atualizado applicationHost.config para a partilha.
Reative a Configuração Partilhada IIS.

Registos de instalação da versão do módulo e do Pacote de Hospedagem

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

No sistema de alojamento, navegue até %windir%\System32\inetsrv.
Localiza o aspnetcore.dll ficheiro.
Clique com o botão direito no ficheiro e selecione Propriedades no menu contextual.
Selecione o separador Detalhes . A versão do ficheiro e a versão do produto representam a versão instalada do módulo.

Os registos do instalador do Hosting Bundle para o módulo encontram-se em C:\\Users\\%UserName%\\AppData\\Local\\Temp. O ficheiro chama-se dd_DotNetCoreWinSvrHosting__\{TIMESTAMP}_000_AspNetCoreModule_x64.log, onde o marcador de posição {TIMESTAMP} é a data/hora.

Localizações de módulos, esquemas e ficheiros 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

Schema

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 ficheiros podem ser encontrados pesquisando aspnetcore dentro do applicationHost.config ficheiro.

O módulo ASP.NET Core (ANCM) é um módulo nativo do IIS que se integra ao pipeline do IIS para direcionar requisições web para aplicações ASP.NET Core de backend.

Versões suportadas do Windows:

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 ASP.NET aplicações Core correm num processo separado do processo worker do IIS, o módulo também trata da gestão de processos. O módulo inicia o processo da aplicação ASP.NET Core quando chega a primeira solicitação e reinicia a aplicação se esta falhar. Este é essencialmente o mesmo comportamento visto com ASP.NET aplicações 4.x que correm em processo no IIS e que são geridas pelo Serviço de Ativação de Processos do Windows (WAS).

O diagrama seguinte ilustra a relação entre o IIS, o Módulo Núcleo ASP.NET e uma aplicação:

ASP.NET Módulo Núcleo

Os pedidos chegam da web para o driver em modo kernel HTTP.sys. O driver encaminha os pedidos para o IIS na porta configurada do site, normalmente 80 (HTTP) ou 443 (HTTPS). O módulo encaminha os pedidos para Kestrel uma porta aleatória da app, que não é a porta 80 ou 443.

O módulo especifica a porta através de uma variável de ambiente no arranque, e o Middleware de Integração IIS configura o servidor para ouvir em http://localhost:{port}. São realizadas verificações adicionais e pedidos que não têm origem no módulo são rejeitados. O módulo não suporta encaminhamento HTTPS, por isso os pedidos são encaminhados via HTTP mesmo que sejam recebidos por IIS via HTTPS.

Depois Kestrel de recolher o pedido do módulo, este é empurrado para o pipeline de middleware ASP.NET Core. O pipeline de middleware processa o pedido e passa-o como uma instância HttpContext para a lógica da aplicação. Middleware adicionado pela integração IIS atualiza o esquema, o IP remoto e a base de caminhos para ter em conta o encaminhamento do pedido para Kestrel. A resposta da aplicação é encaminhada de volta para o IIS, que a envia de volta para o cliente HTTP que iniciou o pedido.

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

O Módulo Núcleo ASP.NET também pode:

Defina variáveis de ambiente para o processo do trabalhador.
Registar a saída de stdout no armazenamento de ficheiros para solução de problemas de arranque.
Encaminhar tokens de autenticação do Windows.

Como instalar e utilizar o ASP.NET Core Module (ANCM)

Para instruções sobre como instalar o ASP.NET Core Module, consulte Instalar o .NET Core Hosting Bundle.

Configuração com web.config

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

O ficheiro web.config seguinte é publicado para uma implementação dependente do framework e configura o Módulo ASP.NET Core para lidar com os pedidos do 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 seguinteweb.config é publicado para uma implementação autónoma:

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

Para informações sobre a configuração de subaplicações IIS, veja Host ASP.NET Core no Windows com IIS.

Atributos do elemento aspNetCore

Attribute	Description	Predefinido
`arguments`	Atributo de texto opcional. Argumentos para o executável especificados em processPath.
`disableStartUpErrorPage`	Atributo booleano opcional. Se for verdadeiro, a página 502.5 - Falha de Processo é suprimida, e a página de código de estado 502 configurada no web.config tem prioridade.	`false`
`forwardWindowsAuthToken`	Atributo booleano opcional. Se for verdade, o token é encaminhado para o processo filho que ouve em %ASPNETCORE_PORT% como um cabeçalho 'MS-ASPNETCORE-WINAUTHTOKEN' por pedido. É responsabilidade desse processo chamar o CloseHandle neste token por solicitação.	`true`
`processesPerApplication`	Atributo inteiro opcional. Especifica o número de instâncias do processo especificadas na definição processPath que podem ser ativadas por aplicação. A configuração `processesPerApplication` é desencorajada. Este atributo será removido numa versão futura.	Predefinição: `1` Min: `1` Max: `100`
`processPath`	Atributo de string obrigatório. Caminho para o executável que lança um processo que escuta pedidos HTTP. Caminhos relativos são suportados. Se o caminho começar com `.`, o caminho é considerado relativo à raiz do sítio.
`rapidFailsPerMinute`	Atributo inteiro opcional. Especifica o número de vezes que o processo especificado em processPath pode falhar por minuto. Se este limite for ultrapassado, o módulo deixa de iniciar o processo pelo resto do minuto.	Predefinição: `10` Min: `0` Max: `100`
`requestTimeout`	Atributo opcional de intervalo temporal. Especifica a duração durante a qual o ASP.NET Módulo Núcleo espera uma resposta do processo que ouve em %ASPNETCORE_PORT%. Nas versões do Módulo ASP.NET Core lançadas com o ASP.NET Core 2.1 ou posterior, o `requestTimeout` é especificado em horas, minutos e segundos.	Predefinição: `00:02:00` Min: `00:00:00` Max: `360:00:00`
`shutdownTimeLimit`	Atributo inteiro opcional. Duração em segundos em que o módulo espera que o executável se desligue graciosamente quando o `app_offline.htm` ficheiro é detetado.	Predefinição: `10` Min: `0` Max: `600`
`startupTimeLimit`	Atributo inteiro opcional. A duração em segundos que o módulo espera até que o executável inicie um processo que escuta na porta. Se este limite de tempo for ultrapassado, o módulo interrompe o processo. O módulo tenta reiniciar o processo quando recebe um novo pedido e, de novo, continua a tentar reiniciar o processo em solicitações subsequentes, a menos que a aplicação falhe ao iniciar rapidFailsPerMinute várias vezes no último minuto contínuo. Um valor de 0 (zero) não é considerado um tempo limite infinito.	Predefinição: `120` Min: `0` Max: `3600`
`stdoutLogEnabled`	Atributo booleano opcional. Se for verdade, stdout e stderr para o processo especificado no processoPath são redirecionados para o ficheiro especificado no stdoutLogFile.	`false`
`stdoutLogFile`	Atributo de texto opcional. Especifica o caminho relativo ou absoluto do ficheiro para o qual stdout e stderr do processo especificado em processPath são registados. Os caminhos relativos são relativos à raiz do sítio. Qualquer caminho que comece com `.` é relativo à raiz do sítio e todos os outros caminhos são tratados como caminhos absolutos. Quaisquer pastas fornecidas no caminho devem existir para que o módulo crie o ficheiro de registo. Usando delimitadores de sublinhado, um carimbo temporal, ID do processo e extensão de ficheiro (.log) são adicionados ao último segmento do caminho stdoutLogFile . Se `.\logs\stdout` for fornecido como valor, um registo stdout de exemplo é guardado como stdout_20180205194132_1934.log na pasta de registos quando guardado a 5/02/2018 às 19:41:32 com um ID de processo de 1934.	`aspnetcore-stdout`

Definindo variáveis de ambiente

Advertência

As variáveis de ambiente definidas nesta secção entram em conflito com as variáveis de ambiente do sistema com o mesmo nome. Se uma variável de ambiente for definida tanto no ficheiroweb.config como ao nível do sistema no Windows, o valor do ficheiroweb.config é adicionado ao valor da variável de ambiente do sistema (por exemplo, ASPNETCORE_ENVIRONMENT: Development;Development), o que impede a aplicação de arrancar.

O exemplo seguinte estabelece duas variáveis de ambiente. ASPNETCORE_ENVIRONMENT Configura o ambiente da aplicação para Development. Um programador pode definir temporariamente este valor no ficheiroweb.config para forçar o carregamento da Página de Exceção do Desenvolvedor ao depurar uma exceção de aplicação. CONFIG_DIR é um exemplo de variável de ambiente definida pelo utilizador, onde o programador escreveu código que lê o valor no arranque para formar um caminho para carregar o ficheiro de configuração da aplicação.

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

Advertência

Define apenas a ASPNETCORE_ENVIRONMENT variável de ambiente para Development nos servidores de staging e testes que não são acessíveis a redes não confiáveis, como a Internet.

app_offline.htm

Página de erro de arranque

Se o Módulo do ASP.NET Core falhar em lançar o processo de backend ou se o processo de backend iniciar mas não conseguir ouvir à porta configurada, aparece uma página com o código de estado 502.5 - Falha de Processo. Para suprimir esta página e reverter à página padrão de código de estado IIS 502, use o disableStartUpErrorPage atributo. Para mais informações sobre a configuração de mensagens de erro personalizadas, consulte HTTP Errors <httpErrors>.

Criação e redirecionamento de registos

Os registos não são rotacionados, a menos que haja reciclagem/reinício de processos. É responsabilidade do hoster limitar o espaço em disco que os registos consomem.

Um carimbo temporal e uma extensão do ficheiro são adicionados automaticamente quando o ficheiro de registo é criado. O nome do ficheiro de registo é composto pela adição do carimbo temporal, ID do processo e extensão do ficheiro (.log) ao último segmento do stdoutLogFile caminho ( tipicamente stdout) delimitado por sublinhatões. Se o stdoutLogFile caminho terminar com stdout, um registo de uma aplicação com um PID de 1934 criado a 5/02/2018 às 19:42:32 tem o nome do ficheiro stdout_20180205194132_1934.log.

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

Para criar regras de filtro de registo, consulte a secção Aplicar regras de filtro de registo no código da documentação do registo do ASP.NET Core.

Para mais informações sobre formatos de caminho, veja Formatos de caminho de ficheiro em sistemas Windows.

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

O proxy criado entre o ASP.NET Módulo Core e Kestrel utiliza o protocolo HTTP. Não há risco de escutar o tráfego entre o módulo e Kestrel a partir de um local fora do servidor.

Módulo ASP.NET Core com uma Configuração Partilhada do IIS

O instalador ASP.NET Core Module funciona 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 partilha usado pela Configuração Partilhada IIS, o instalador lança um erro de acesso negado ao tentar configurar as definições do módulo no ficheiroapplicationHost.config da partilha.

Ao usar uma Configuração Partilhada IIS, siga estes passos:

Desative a configuração partilhada do IIS.
Executar o instalador.
Exporta o ficheiro atualizado applicationHost.config para o share.
Reative a Configuração Partilhada IIS.

Registos de instalação da versão do módulo e do Pacote de Hospedagem

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

No sistema de alojamento, navegue até %windir%\System32\inetsrv.
Localiza o ficheiro aspnetcore.dll.
Clique com o botão direito no ficheiro e selecione Propriedades no menu contextual.
Selecione o separador Detalhes . A versão do ficheiro e a versão do produto representam a versão instalada do módulo.

Os registos de instalação do Hosting Bundle para o módulo encontram-se em C:\Users\%UserName%\AppData\Local\Temp. O ficheiro chama-se dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

Localizações de módulos, esquemas e ficheiros 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

Schema

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 ficheiros podem ser encontrados ao pesquisar aspnetcore no ficheiro applicationHost.config.

Recursos adicionais

Alojar o ASP.NET Core no Windows com o IIS
Implantar aplicativos ASP.NET Core no Serviço de Aplicativo do Azure
ASP.NET Core Módulo fonte de referência [ramo padrão (main)]: Use a lista suspensa Branch para selecionar uma versão específica (por exemplo, release/3.1).
Módulos IIS com ASP.NET Core

Comentários

Esta página foi útil?

Last updated on 2025-11-19

Partilhar via

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

Instalar ASP.NET Módulo Núcleo (ANCM)

Modelos de hospedagem

Modelo de hospedagem em processo

Modelo de alojamento fora de processo

Alterações no modelo de alojamento

Nome do processo

Como instalar e utilizar o ASP.NET Core Module (ANCM)

Configuração com web.config

Atributos do elemento aspNetCore

Definir variáveis de ambiente

app_offline.htm

Página de erro de arranque

Criação e redirecionamento de registos

Registos de diagnóstico melhorados

Modificar o tamanho da pilha

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

Módulo ASP.NET Core com uma Configuração Partilhada do IIS

Registos de instalação da versão do módulo e do Pacote de Hospedagem

Localizações de módulos, esquemas e ficheiros de configuração

Módulo

Schema

Configuração

Modelos de hospedagem

Modelo de hospedagem em processo

Modelo de alojamento fora de processo

Alterações no modelo de alojamento

Nome do processo

Como instalar e utilizar o ASP.NET Core Module (ANCM)

Configuração com web.config

Atributos do elemento aspNetCore

Definindo variáveis de ambiente

app_offline.htm

Página de erro de arranque

Criação e redirecionamento de registos

Registos de diagnóstico melhorados

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

Módulo ASP.NET Core com uma Configuração Partilhada do IIS

Registos de instalação da versão do módulo e do Pacote de Hospedagem

Localizações de módulos, esquemas e ficheiros de configuração

Módulo

Schema

Configuração

Como instalar e utilizar o ASP.NET Core Module (ANCM)

Configuração com web.config

Atributos do elemento aspNetCore

Definindo variáveis de ambiente

app_offline.htm

Página de erro de arranque

Criação e redirecionamento de registos

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

Módulo ASP.NET Core com uma Configuração Partilhada do IIS

Registos de instalação da versão do módulo e do Pacote de Hospedagem

Localizações de módulos, esquemas e ficheiros de configuração

Módulo

Schema

Configuração

Recursos adicionais

Comentários

Recursos adicionais

`app_offline.htm`