Módulo do ASP.NET CoreASP.NET Core Module

Por Tom Dykstra, Rick Strahl, Chris Ross, Rick Anderson, Sourabh Shirhatti, Justin Kotalik e Luke LathamBy Tom Dykstra, Rick Strahl, Chris Ross, Rick Anderson, Sourabh Shirhatti, Justin Kotalik, and Luke Latham

O módulo do ASP.NET Core é um módulo nativo do IIS que se conecta ao pipeline do IIS para:The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to either:

Versões do Windows compatíveis:Supported Windows versions:

  • Windows 7 ou posteriorWindows 7 or later
  • Windows Server 2008 R2 ou posteriorWindows Server 2008 R2 or later

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).When hosting in-process, the module uses an in-process server implementation for IIS, called IIS HTTP Server (IISHttpServer).

Ao hospedar de fora do processo, o módulo só funciona com o Kestrel.When hosting out-of-process, the module only works with Kestrel. O módulo não funciona com http. sys.The module doesn't function with HTTP.sys.

Modelos de hospedagemHosting models

Modelo de hospedagem em processoIn-process hosting model

ASP.NET Core aplicativos assumem como padrão o modelo de hospedagem em processo.ASP.NET Core apps default to the in-process hosting model.

As seguintes características se aplicam ao hospedar em processo:The following characteristics apply when hosting in-process:

  • O Servidor HTTP do IIS (IISHttpServer) é usado, em vez do servidor Kestrel.IIS HTTP Server (IISHttpServer) is used instead of Kestrel server. Em processo, CreateDefaultBuilder chama UseIIS para:For in-process, CreateDefaultBuilder calls UseIIS to:

    • Registrar o IISHttpServer.Register the 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.Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
    • Configurar o host para capturar erros de inicialização.Configure the host to capture startup errors.
  • O requestTimeout atributo não se aplica à hospedagem em processo.The requestTimeout attribute doesn't apply to in-process hosting.

  • Não há suporte para o compartilhamento do pool de aplicativos entre aplicativos.Sharing an app pool among apps isn't supported. Use um pool de aplicativos por aplicativo.Use one app pool per app.

  • 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.When using Web Deploy or manually placing an app_offline.htm file in the deployment, the app might not shut down immediately if there's an open connection. Por exemplo, uma conexão websocket pode atrasar o desligamento do aplicativo.For example, a websocket connection may delay app shut down.

  • A arquitetura (número de bit) do aplicativo e o tempo de execução instalado (x64 ou x86) devem corresponder à arquitetura do pool de aplicativos.The architecture (bitness) of the app and installed runtime (x64 or x86) must match the architecture of the app pool.

  • As desconexões do cliente são detectadas.Client disconnects are detected. O token de cancelamento HttpContext.RequestAborted é cancelado quando o cliente se desconecta.The HttpContext.RequestAborted cancellation token is cancelled when the client disconnects.

  • 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).In ASP.NET Core 2.2.1 or earlier, GetCurrentDirectory returns the worker directory of the process started by IIS rather than the app's directory (for example, C:\Windows\System32\inetsrv for w3wp.exe).

    Para obter o código de exemplo que define o diretório atual do aplicativo, confira a classe CurrentDirectoryHelpers.For sample code that sets the app's current directory, see the CurrentDirectoryHelpers class. Chame o método SetCurrentDirectory.Call the SetCurrentDirectory method. As chamadas seguintes a GetCurrentDirectory fornecem o diretório do aplicativo.Subsequent calls to GetCurrentDirectory provide the app's directory.

  • Ao hospedar em processo, AuthenticateAsync não é chamado internamente para inicializar um usuário.When hosting in-process, AuthenticateAsync isn't called internally to initialize a user. Portanto, uma implementação IClaimsTransformation usada para transformar as declarações após cada autenticação não é ativada por padrão.Therefore, an IClaimsTransformation implementation used to transform claims after every authentication isn't activated by default. Quando a transformação de declarações com uma implementação IClaimsTransformation, chame AddAuthentication para adicionar serviços de autenticação:When transforming claims with an IClaimsTransformation implementation, call AddAuthentication to add authentication services:

    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 processoOut-of-process hosting model

Para configurar um aplicativo para hospedagem fora do processo, defina o valor da propriedade <AspNetCoreHostingModel> como OutOfProcess no arquivo de projeto ( . csproj):To configure an app for out-of-process hosting, set the value of the <AspNetCoreHostingModel> property to OutOfProcess in the project file (.csproj):

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

A hospedagem em processo é definida com InProcess, que é o valor padrão.In-process hosting is set with InProcess, which is the default value.

O servidor Kestrel é usado, em vez do servidor HTTP do IIS (IISHttpServer).Kestrel server is used instead of IIS HTTP Server (IISHttpServer).

Fora do processo, CreateDefaultBuilder chama UseIISIntegration para:For out-of-process, CreateDefaultBuilder calls UseIISIntegration to:

  • 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.Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
  • Configurar o host para capturar erros de inicialização.Configure the host to capture startup errors.

Alterações no modelo de hospedagemHosting model changes

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.If the hostingModel setting is changed in the web.config file (explained in the Configuration with web.config section), the module recycles the worker process for 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.For IIS Express, the module doesn't recycle the worker process but instead triggers a graceful shutdown of the current IIS Express process. A próxima solicitação para o aplicativo gera um novo processo do IIS Express.The next request to the app spawns a new IIS Express process.

Nome do processoProcess name

Process.GetCurrentProcess().ProcessName relata w3wp/iisexpress (em processo) ou dotnet (fora do processo).Process.GetCurrentProcess().ProcessName reports w3wp/iisexpress (in-process) or dotnet (out-of-process).

Muitos módulos nativos, como a Autenticação do Windows, permanecem ativos.Many native modules, such as Windows Authentication, remain active. 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.To learn more about IIS modules active with the ASP.NET Core Module, see Módulos do IIS com o ASP.NET Core.

O Módulo do ASP.NET Core também pode:The ASP.NET Core Module can also:

  • Definir variáveis de ambiente para o processo de trabalho.Set environment variables for the worker process.
  • Registrar a saída StdOut no armazenamento de arquivo para a solução de problemas de inicialização.Log stdout output to file storage for troubleshooting startup issues.
  • Encaminhar tokens de autenticação do Windows.Forward Windows authentication tokens.

Como instalar e usar o Módulo do ASP.NET CoreHow to install and use the ASP.NET Core Module

Para obter instruções de como instalar o Módulo do ASP.NET Core, confira Instalar o Pacote de Hospedagem do .NET Core.For instructions on how to install the ASP.NET Core Module, see Install the .NET Core Hosting Bundle.

Configuração com web.configConfiguration with 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.The ASP.NET Core Module is configured with the aspNetCore section of the system.webServer node in the site's web.config file.

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:The following web.config file is published for a framework-dependent deployment and configures the ASP.NET Core Module to handle site requests:

<?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:The following web.config is published for a self-contained deployment:

<?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.The InheritInChildApplications property is set to false to indicate that the settings specified within the <location> element aren't inherited by apps that reside in a subdirectory of the app.

Quando um aplicativo é implantado no Serviço de Aplicativo do Azure, o caminho stdoutLogFile é definido para \\?\%home%\LogFiles\stdout.When an app is deployed to Azure App Service, the stdoutLogFile path is set to \\?\%home%\LogFiles\stdout. O caminho salva logs de stdout para a pasta LogFiles, que é um local criado automaticamente pelo serviço.The path saves stdout logs to the LogFiles folder, which is a location automatically created by the service.

Para saber mais sobre a configuração de subaplicativos do IIS, confira Hospedar o ASP.NET Core no Windows com o IIS.For information on IIS sub-application configuration, see Hospedar o ASP.NET Core no Windows com o IIS.

Atributos do elemento aspNetCoreAttributes of the aspNetCore element

AtributoAttribute DescriçãoDescription PadrãoDefault
arguments

Atributo de cadeia de caracteres opcional.Optional string attribute.

Argumentos para o executável especificado em processPath.Arguments to the executable specified in processPath.

disableStartUpErrorPage

Atributo booliano opcional.Optional Boolean attribute.

Se for true, a página 502.5 – Falha do Processo será suprimida e a página de código de status 502, configurada no web.config, terá precedência.If true, the 502.5 - Process Failure page is suppressed, and the 502 status code page configured in the web.config takes precedence.

false
forwardWindowsAuthToken

Atributo booliano opcional.Optional Boolean attribute.

Se for true, o token será encaminhado para o processo filho escutando em %ASPNETCORE_PORT% como um cabeçalho 'MS-ASPNETCORE-WINAUTHTOKEN' por solicitação.If true, the token is forwarded to the child process listening on %ASPNETCORE_PORT% as a header 'MS-ASPNETCORE-WINAUTHTOKEN' per request. É responsabilidade desse processo chamar CloseHandle nesse token por solicitação.It's the responsibility of that process to call CloseHandle on this token per request.

true
hostingModel

Atributo de cadeia de caracteres opcional.Optional string attribute.

Especifica o modelo de hospedagem como em processo (InProcess) ou de fora do processo (OutOfProcess).Specifies the hosting model as in-process (InProcess) or out-of-process (OutOfProcess).

InProcess
processesPerApplication

Atributo inteiro opcional.Optional integer attribute.

Especifica o número de instâncias do processo especificado na configuração processPath que pode ser ativada por aplicativo.Specifies the number of instances of the process specified in the processPath setting that can be spun up per app.

†Para hospedagem em processo, o valor está limitado a 1.†For in-process hosting, the value is limited to 1.

A configuração processesPerApplication é desencorajada.Setting processesPerApplication is discouraged. Esse atributo será removido em uma versão futura.This attribute will be removed in a future release.

Padrão: 1Default: 1
Mín.: 1Min: 1
Máx.: 100Max: 100
processPath

Atributo de cadeia de caracteres obrigatório.Required string attribute.

Caminho para o executável que inicia um processo que escuta solicitações HTTP.Path to the executable that launches a process listening for HTTP requests. Caminhos relativos são compatíveis.Relative paths are supported. Se o caminho começa com ., o caminho é considerado relativo à raiz do site.If the path begins with ., the path is considered to be relative to the site root.

rapidFailsPerMinute

Atributo inteiro opcional.Optional integer attribute.

Especifica o número de vezes que o processo especificado em processPath pode falhar por minuto.Specifies the number of times the process specified in processPath is allowed to crash per minute. Se esse limite for excedido, o módulo interromperá a inicialização do processo pelo restante do minuto.If this limit is exceeded, the module stops launching the process for the remainder of the minute.

Sem suporte com hospedagem padrão.Not supported with in-process hosting.

Padrão: 10Default: 10
Mín.: 0Min: 0
Máx.: 100Max: 100
requestTimeout

Atributo de intervalo de tempo opcional.Optional timespan attribute.

Especifica a duração para a qual o Módulo do ASP.NET Core aguarda uma resposta do processo que escuta em %ASPNETCORE_PORT%.Specifies the duration for which the ASP.NET Core Module waits for a response from the process listening on %ASPNETCORE_PORT%.

Em versões do Módulo do ASP.NET Core que acompanham a versão do ASP.NET Core 2.1 ou posterior, o requestTimeout é especificado em horas, minutos e segundos.In versions of the ASP.NET Core Module that shipped with the release of ASP.NET Core 2.1 or later, the requestTimeout is specified in hours, minutes, and seconds.

Não se aplica à hospedagem em processo.Doesn't apply to in-process hosting. Para a hospedagem em processo, o módulo aguarda o aplicativo processar a solicitação.For in-process hosting, the module waits for the app to process the request.

Os valores válidos para segmentos de minutos e segundos da cadeia de caracteres estão no intervalo 0 a 59.Valid values for minutes and seconds segments of the string are in the range 0-59. O uso de 60 no valor para minutos ou segundos resulta em um 500 - Erro Interno do Servidor.Use of 60 in the value for minutes or seconds results in a 500 - Internal Server Error.

Padrão: 00:02:00Default: 00:02:00
Mín.: 00:00:00Min: 00:00:00
Máx.: 360:00:00Max: 360:00:00
shutdownTimeLimit

Atributo inteiro opcional.Optional integer attribute.

Duração em segundos que o módulo espera para o executável desligar normalmente quando o arquivo app_offline.htm é detectado.Duration in seconds that the module waits for the executable to gracefully shutdown when the app_offline.htm file is detected.

Padrão: 10Default: 10
Mín.: 0Min: 0
Máx.: 600Max: 600
startupTimeLimit

Atributo inteiro opcional.Optional integer attribute.

Duração em segundos que o módulo espera para o arquivo executável iniciar um processo escutando na porta.Duration in seconds that the module waits for the executable to start a process listening on the port. Se esse tempo limite é excedido, o módulo encerra o processo.If this time limit is exceeded, the module kills the process. O módulo tentará reiniciar o processo quando ele receber uma nova solicitação e continuará a tentar reiniciar o processo em solicitações subsequentes de entrada, a menos que o aplicativo falhe em iniciar um número de vezes igual a rapidFailsPerMinute no último minuto sem interrupção.The module attempts to relaunch the process when it receives a new request and continues to attempt to restart the process on subsequent incoming requests unless the app fails to start rapidFailsPerMinute number of times in the last rolling minute.

Um valor de 0 (zero) não é considerado um tempo limite infinito.A value of 0 (zero) is not considered an infinite timeout.

Padrão: 120Default: 120
Mín.: 0Min: 0
Máx.: 3600Max: 3600
stdoutLogEnabled

Atributo booliano opcional.Optional Boolean attribute.

Se for true, stdout e stderr para o processo especificado em processPath serão redirecionados para o arquivo especificado em stdoutLogFile.If true, stdout and stderr for the process specified in processPath are redirected to the file specified in stdoutLogFile.

false
stdoutLogFile

Atributo de cadeia de caracteres opcional.Optional string attribute.

Especifica o caminho relativo ou absoluto para o qual stdout e stderr do processo especificado em processPath são registrados em log.Specifies the relative or absolute file path for which stdout and stderr from the process specified in processPath are logged. Os caminhos relativos são relativos à raiz do site.Relative paths are relative to the root of the site. Qualquer caminho começando com . é relativo à raiz do site e todos os outros caminhos são tratados como caminhos absolutos.Any path starting with . are relative to the site root and all other paths are treated as absolute paths. Todas as pastas fornecidas no caminho são criadas pelo módulo quando o arquivo de log é criado.Any folders provided in the path are created by the module when the log file is created. Usando delimitadores de sublinhado, um carimbo de data/hora, uma ID de processo e a extensão de arquivo ( .log) são adicionados ao último segmento do caminho stdoutLogFile.Using underscore delimiters, a timestamp, process ID, and file extension (.log) are added to the last segment of the stdoutLogFile path. Se .\logs\stdout é fornecido como um valor, um log de exemplo stdout é salvo como stdout_20180205194132_1934.log na pasta logs quando salvos em 5/2/2018, às 19:41:32, com uma ID de processo de 1934.If .\logs\stdout is supplied as a value, an example stdout log is saved as stdout_20180205194132_1934.log in the logs folder when saved on 2/5/2018 at 19:41:32 with a process ID of 1934.

aspnetcore-stdout

Definir variáveis de ambienteSet environment variables

Variáveis de ambiente podem ser especificadas para o processo no atributo processPath.Environment variables can be specified for the process in the processPath attribute. Especificar uma variável de ambiente com o elemento filho <environmentVariable> de um elemento de coleção <environmentVariables>.Specify an environment variable with the <environmentVariable> child element of an <environmentVariables> collection element. Variáveis de ambiente definidas nesta seção têm precedência sobre variáveis de ambiente do sistema.Environment variables set in this section take precedence over system environment variables.

O exemplo a seguir define duas variáveis de ambiente em Web. config. ASPNETCORE_ENVIRONMENT configura o ambiente do aplicativo para Development.The following example sets two environment variables in web.config. ASPNETCORE_ENVIRONMENT configures the app's environment to 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.A developer may temporarily set this value in the web.config file in order to force the Developer Exception Page to load when debugging an app exception. 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.CONFIG_DIR is an example of a user-defined environment variable, where the developer has written code that reads the value on startup to form a path for loading the app's configuration file.

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

Observação

Em vez de configurar o ambiente diretamente no web.config, você pode incluir a propriedade <EnvironmentName> no perfil de publicação ( .pubxml) ou no perfil de projeto.An alternative to setting the environment directly in web.config is to include the <EnvironmentName> property in the publish profile (.pubxml) or project file. Esta abordagem define o ambiente no arquivo web.config quando o projeto é publicado:This approach sets the environment in web.config when the project is published:

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

Aviso

Defina a variável de ambiente apenas ASPNETCORE_ENVIRONMENT para Development em servidores de preparo e de teste que não estão acessíveis a redes não confiáveis, tais como a Internet.Only set the ASPNETCORE_ENVIRONMENT environment variable to Development on staging and testing servers that aren't accessible to untrusted networks, such as the Internet.

app_offline.htmapp_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.If a file with the name app_offline.htm is detected in the root directory of an app, the ASP.NET Core Module attempts to gracefully shutdown the app and stop processing incoming requests. 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.If the app is still running after the number of seconds defined in shutdownTimeLimit, the ASP.NET Core Module kills the running process.

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.While the app_offline.htm file is present, the ASP.NET Core Module responds to requests by sending back the contents of the app_offline.htm file. Quando o arquivo app_offline.htm é removido, a próxima solicitação inicia o aplicativo.When the app_offline.htm file is removed, the next request starts the app.

Ao usar o modelo de hospedagem de fora do processo, talvez o aplicativo não desligue imediatamente se houver uma conexão aberta.When using the out-of-process hosting model, the app might not shut down immediately if there's an open connection. Por exemplo, uma conexão websocket pode atrasar o desligamento do aplicativo.For example, a websocket connection may delay app shut down.

Página de erro de inicializaçãoStart-up error page

A hospedagem em processo e fora do processo produzem páginas de erro personalizadas quando falham ao iniciar o aplicativo.Both in-process and out-of-process hosting produce custom error pages when they fail to start the app.

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.If the ASP.NET Core Module fails to find either the in-process or out-of-process request handler, a 500.0 - In-Process/Out-Of-Process Handler Load Failure status code page appears.

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.For in-process hosting if the ASP.NET Core Module fails to start the app, a 500.30 - Start Failure status code page appears.

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.For out-of-process hosting if the ASP.NET Core Module fails to launch the backend process or the backend process starts but fails to listen on the configured port, a 502.5 - Process Failure status code page appears.

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.To suppress this page and revert to the default IIS 5xx status code page, use the disableStartUpErrorPage attribute. Para obter mais informações sobre como configurar mensagens de erro personalizadas, veja Erros HTTP <httpErrors>.For more information on configuring custom error messages, see HTTP Errors <httpErrors>.

Criação de log e redirecionamentoLog creation and redirection

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.The ASP.NET Core Module redirects stdout and stderr console output to disk if the stdoutLogEnabled and stdoutLogFile attributes of the aspNetCore element are set. Todas as pastas no caminho stdoutLogFile são criadas pelo módulo quando o arquivo de log é criado.Any folders in the stdoutLogFile path are created by the module when the log file is created. 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).The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

Logs não sofrem rotação, a menos que ocorra a reciclagem/reinicialização do processo.Logs aren't rotated, unless process recycling/restart occurs. É responsabilidade do hoster limitar o espaço em disco consumido pelos logs.It's the responsibility of the hoster to limit the disk space the logs consume.

Usar o log de stdout é recomendado apenas para solucionar problemas de inicialização do aplicativo.Using the stdout log is only recommended for troubleshooting app startup issues. Não use o log de stdout para fins gerais de registro em log do aplicativo.Don't use the stdout log for general app logging purposes. 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.For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. Para obter mais informações, veja provedores de log de terceiros.For more information, see third-party logging providers.

Uma extensão de arquivo e um carimbo de data/hora são adicionados automaticamente quando o arquivo de log é criado.A timestamp and file extension are added automatically when the log file is created. 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.The log file name is composed by appending the timestamp, process ID, and file extension (.log) to the last segment of the stdoutLogFile path (typically stdout) delimited by underscores. 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.If the stdoutLogFile path ends with stdout, a log for an app with a PID of 1934 created on 2/5/2018 at 19:42:32 has the file name 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.If stdoutLogEnabled is false, errors that occur on app startup are captured and emitted to the event log up to 30 KB. Após a inicialização, todos os logs adicionais são descartados.After startup, all additional logs are discarded.

O seguinte exemplo de elemento aspNetCore em um arquivo Web. config configura o log de stdout para um aplicativo hospedado no serviço Azure app.The following sample aspNetCore element in a web.config file configures stdout logging for an app hosted in Azure App Service. Um caminho local ou um caminho de compartilhamento de rede é aceitável para o registro em log local.A local path or network share path is acceptable for local logging. Confirme se a identidade do usuário AppPool tem permissão para gravar no caminho fornecido.Confirm that the AppPool user identity has permission to write to the path provided.

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="true"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="InProcess">
</aspNetCore>

Logs de diagnóstico avançadosEnhanced diagnostic logs

O Módulo do ASP.NET Core é configurável para fornecer logs de diagnóstico avançados.The ASP.NET Core Module is configurable to provide enhanced diagnostics logs. Adicione o elemento <handlerSettings> ao elemento <aspNetCore> no web.config. A definição de debugLevel como TRACE expõe uma fidelidade maior de informações de diagnóstico:Add the <handlerSettings> element to the <aspNetCore> element in web.config. Setting the debugLevel to TRACE exposes a higher fidelity of diagnostic information:

<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.Any folders in the path (logs in the preceding example) are created by the module when the log file is created. 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).The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

Os valores do nível de depuração (debugLevel) podem incluir o nível e a localização.Debug level (debugLevel) values can include both the level and the location.

Níveis (na ordem do menos para o mais detalhado):Levels (in order from least to most verbose):

  • ERRORERROR
  • WARNINGWARNING
  • INFOINFO
  • TRACETRACE

Locais (vários locais são permitidos):Locations (multiple locations are permitted):

  • CONSOLECONSOLE
  • EVENTLOGEVENTLOG
  • FILEFILE

As configurações do manipulador também podem ser fornecidas por meio de variáveis de ambiente:The handler settings can also be provided via environment variables:

  • ASPNETCORE_MODULE_DEBUG_FILE – caminho para o arquivo de log de depuração.ASPNETCORE_MODULE_DEBUG_FILE – Path to the debug log file. (Padrão: aspnetcore-debug.log)(Default: aspnetcore-debug.log)
  • ASPNETCORE_MODULE_DEBUG – configuração do nível de depuração.ASPNETCORE_MODULE_DEBUG – Debug level setting.

Aviso

Não deixe o log de depuração habilitado na implantação por mais tempo que o necessário para solucionar um problema.Do not leave debug logging enabled in the deployment for longer than required to troubleshoot an issue. O tamanho do log não é limitado.The size of the log isn't limited. Deixar o log de depuração habilitado pode esgotar o espaço em disco disponível e causar falha no servidor ou no serviço de aplicativo.Leaving the debug log enabled can exhaust the available disk space and crash the server or app service.

Veja Configuração com web.config para obter um exemplo do elemento aspNetCore no arquivo web.config.See Configuration with web.config for an example of the aspNetCore element in the web.config file.

Modificar o tamanho da pilhaModify the stack size

Aplica-se somente ao usar o modelo de hospedagem em processo.Only applies when using the in-process hosting model.

Configure o tamanho da pilha gerenciada usando a configuração stackSize em bytes em Web. config. O tamanho padrão é de 1048576 bytes (1 MB).Configure the managed stack size using the stackSize setting in bytes in web.config. The default size is 1048576 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 emparelhamentoProxy configuration uses HTTP protocol and a pairing token

Só se aplica à hospedagem de fora do processo.Only applies to out-of-process hosting.

O proxy criado entre o Módulo do ASP.NET Core e o Kestrel usa o protocolo HTTP.The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. Não há nenhum risco de interceptação do tráfego entre o módulo e o Kestrel em um local fora do servidor.There's no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server.

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.A pairing token is used to guarantee that the requests received by Kestrel were proxied by IIS and didn't come from some other source. O token de emparelhamento é criado e definido em uma variável de ambiente (ASPNETCORE_TOKEN) pelo módulo.The pairing token is created and set into an environment variable (ASPNETCORE_TOKEN) by the module. O token de emparelhamento também é definido em um cabeçalho (MS-ASPNETCORE-TOKEN) em cada solicitação com proxy.The pairing token is also set into a header (MS-ASPNETCORE-TOKEN) on every proxied request. 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.IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. Se os valores do token forem incompatíveis, a solicitação será registrada em log e rejeitada.If the token values are mismatched, the request is logged and rejected. 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.The pairing token environment variable and the traffic between the module and Kestrel aren't accessible from a location off of the server. Sem saber o valor do token de emparelhamento, um invasor não pode enviar solicitações que ignoram a verificação no Middleware do IIS.Without knowing the pairing token value, an attacker can't submit requests that bypass the check in the IIS Middleware.

Módulo do ASP.NET Core com uma configuração do IIS compartilhadaASP.NET Core Module with an IIS Shared Configuration

O instalador do módulo do ASP.NET Core é executado com os privilégios da conta de TrustedInstaller.The ASP.NET Core Module installer runs with the privileges of the TrustedInstaller account. 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.Because the local system account doesn't have modify permission for the share path used by the IIS Shared Configuration, the installer throws an access denied error when attempting to configure the module settings in the applicationHost.config file on the share.

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:When using an IIS Shared Configuration on the same machine as the IIS installation, run the ASP.NET Core Hosting Bundle installer with the OPT_NO_SHARED_CONFIG_CHECK parameter set to 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:When the path to the shared configuration isn't on the same machine as the IIS installation, follow these steps:

  1. Desabilite a configuração compartilhada de IIS.Disable the IIS Shared Configuration.
  2. Execute o instalador.Run the installer.
  3. Exportar o arquivo applicationHost.config atualizado para o compartilhamento.Export the updated applicationHost.config file to the share.
  4. Reabilite a Configuração Compartilhada do IIS.Re-enable the IIS Shared Configuration.

Versão do módulo e logs do instalador do pacote de hospedagemModule version and Hosting Bundle installer logs

Para determinar a versão do Módulo do ASP.NET Core instalado:To determine the version of the installed ASP.NET Core Module:

  1. No sistema de hospedagem, navegue até %windir%\System32\inetsrv.On the hosting system, navigate to %windir%\System32\inetsrv.
  2. Localize o arquivo aspnetcore.dll.Locate the aspnetcore.dll file.
  3. Clique com o botão direito do mouse no arquivo e selecione Propriedades no menu contextual.Right-click the file and select Properties from the contextual menu.
  4. Selecione a guia Detalhes. A Versão do arquivo e a Versão do produto representam a versão instalada do módulo.Select the Details tab. The File version and Product version represent the installed version of the module.

Os logs de instalador do pacote de hospedagem para o módulo são encontrados em C:\Usuários\%UserName%\AppData\Local\Temp. O arquivo é nomeado dd_DotNetCoreWinSvrHosting__<carimbo de data/hora>_000_AspNetCoreModule_x64.log.The Hosting Bundle installer logs for the module are found at C:\Users\%UserName%\AppData\Local\Temp. The file is named dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

Locais dos arquivos de módulo, de esquema e de configuraçãoModule, schema, and configuration file locations

MóduloModule

IIS (x86/amd64):IIS (x86/amd64):

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

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

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

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

IIS Express (x86/amd64):IIS Express (x86/amd64):

  • %ProgramFiles%\IIS Express\aspnetcore.dll%ProgramFiles%\IIS Express\aspnetcore.dll

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

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

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

EsquemaSchema

IISIIS

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

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

IIS ExpressIIS Express

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

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

ConfiguraçãoConfiguration

IISIIS

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

IIS ExpressIIS Express

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

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

Os arquivos podem ser encontrados pesquisando por aspnetcore no arquivo applicationHost.config.The files can be found by searching for aspnetcore in the applicationHost.config file.

O módulo do ASP.NET Core é um módulo nativo do IIS que se conecta ao pipeline do IIS para:The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to either:

Versões do Windows compatíveis:Supported Windows versions:

  • Windows 7 ou posteriorWindows 7 or later
  • Windows Server 2008 R2 ou posteriorWindows Server 2008 R2 or later

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).When hosting in-process, the module uses an in-process server implementation for IIS, called IIS HTTP Server (IISHttpServer).

Ao hospedar de fora do processo, o módulo só funciona com o Kestrel.When hosting out-of-process, the module only works with Kestrel. O módulo não funciona com http. sys.The module doesn't function with HTTP.sys.

Modelos de hospedagemHosting models

Modelo de hospedagem em processoIn-process hosting model

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):To configure an app for in-process hosting, add the <AspNetCoreHostingModel> property to the app's project file with a value of InProcess (out-of-process hosting is set with 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.The in-process hosting model isn't supported for ASP.NET Core apps that target the .NET Framework.

Se a propriedade <AspNetCoreHostingModel> não estiver presente no arquivo, o valor padrão será OutOfProcess.If the <AspNetCoreHostingModel> property isn't present in the file, the default value is OutOfProcess.

As seguintes características se aplicam ao hospedar em processo:The following characteristics apply when hosting in-process:

  • O Servidor HTTP do IIS (IISHttpServer) é usado, em vez do servidor Kestrel.IIS HTTP Server (IISHttpServer) is used instead of Kestrel server. Em processo, CreateDefaultBuilder chama UseIIS para:For in-process, CreateDefaultBuilder calls UseIIS to:

    • Registrar o IISHttpServer.Register the 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.Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
    • Configurar o host para capturar erros de inicialização.Configure the host to capture startup errors.
  • O requestTimeout atributo não se aplica à hospedagem em processo.The requestTimeout attribute doesn't apply to in-process hosting.

  • Não há suporte para o compartilhamento do pool de aplicativos entre aplicativos.Sharing an app pool among apps isn't supported. Use um pool de aplicativos por aplicativo.Use one app pool per app.

  • 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.When using Web Deploy or manually placing an app_offline.htm file in the deployment, the app might not shut down immediately if there's an open connection. Por exemplo, uma conexão websocket pode atrasar o desligamento do aplicativo.For example, a websocket connection may delay app shut down.

  • A arquitetura (número de bit) do aplicativo e o tempo de execução instalado (x64 ou x86) devem corresponder à arquitetura do pool de aplicativos.The architecture (bitness) of the app and installed runtime (x64 or x86) must match the architecture of the app pool.

  • As desconexões do cliente são detectadas.Client disconnects are detected. O token de cancelamento HttpContext.RequestAborted é cancelado quando o cliente se desconecta.The HttpContext.RequestAborted cancellation token is cancelled when the client disconnects.

  • 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).In ASP.NET Core 2.2.1 or earlier, GetCurrentDirectory returns the worker directory of the process started by IIS rather than the app's directory (for example, C:\Windows\System32\inetsrv for w3wp.exe).

    Para obter o código de exemplo que define o diretório atual do aplicativo, confira a classe CurrentDirectoryHelpers.For sample code that sets the app's current directory, see the CurrentDirectoryHelpers class. Chame o método SetCurrentDirectory.Call the SetCurrentDirectory method. As chamadas seguintes a GetCurrentDirectory fornecem o diretório do aplicativo.Subsequent calls to GetCurrentDirectory provide the app's directory.

  • Ao hospedar em processo, AuthenticateAsync não é chamado internamente para inicializar um usuário.When hosting in-process, AuthenticateAsync isn't called internally to initialize a user. Portanto, uma implementação IClaimsTransformation usada para transformar as declarações após cada autenticação não é ativada por padrão.Therefore, an IClaimsTransformation implementation used to transform claims after every authentication isn't activated by default. Quando a transformação de declarações com uma implementação IClaimsTransformation, chame AddAuthentication para adicionar serviços de autenticação:When transforming claims with an IClaimsTransformation implementation, call AddAuthentication to add authentication services:

    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 processoOut-of-process hosting model

Para configurar um aplicativo para hospedagem fora do processo, use qualquer uma das abordagens a seguir no arquivo de projeto:To configure an app for out-of-process hosting, use either of the following approaches in the project file:

  • não especifique a propriedade <AspNetCoreHostingModel>.Don't specify the <AspNetCoreHostingModel> property. Se a propriedade <AspNetCoreHostingModel> não estiver presente no arquivo, o valor padrão será OutOfProcess.If the <AspNetCoreHostingModel> property isn't present in the file, the default value is OutOfProcess.
  • Defina o valor da propriedade <AspNetCoreHostingModel> como OutOfProcess (a hospedagem no processo é definida com InProcess):Set the value of the <AspNetCoreHostingModel> property to OutOfProcess (in-process hosting is set with InProcess):
<PropertyGroup>
  <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>

O servidor Kestrel é usado, em vez do servidor HTTP do IIS (IISHttpServer).Kestrel server is used instead of IIS HTTP Server (IISHttpServer).

Fora do processo, CreateDefaultBuilder chama UseIISIntegration para:For out-of-process, CreateDefaultBuilder calls UseIISIntegration to:

  • 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.Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
  • Configurar o host para capturar erros de inicialização.Configure the host to capture startup errors.

Alterações no modelo de hospedagemHosting model changes

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.If the hostingModel setting is changed in the web.config file (explained in the Configuration with web.config section), the module recycles the worker process for 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.For IIS Express, the module doesn't recycle the worker process but instead triggers a graceful shutdown of the current IIS Express process. A próxima solicitação para o aplicativo gera um novo processo do IIS Express.The next request to the app spawns a new IIS Express process.

Nome do processoProcess name

Process.GetCurrentProcess().ProcessName relata w3wp/iisexpress (em processo) ou dotnet (fora do processo).Process.GetCurrentProcess().ProcessName reports w3wp/iisexpress (in-process) or dotnet (out-of-process).

Muitos módulos nativos, como a Autenticação do Windows, permanecem ativos.Many native modules, such as Windows Authentication, remain active. 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.To learn more about IIS modules active with the ASP.NET Core Module, see Módulos do IIS com o ASP.NET Core.

O Módulo do ASP.NET Core também pode:The ASP.NET Core Module can also:

  • Definir variáveis de ambiente para o processo de trabalho.Set environment variables for the worker process.
  • Registrar a saída StdOut no armazenamento de arquivo para a solução de problemas de inicialização.Log stdout output to file storage for troubleshooting startup issues.
  • Encaminhar tokens de autenticação do Windows.Forward Windows authentication tokens.

Como instalar e usar o Módulo do ASP.NET CoreHow to install and use the ASP.NET Core Module

Para obter instruções de como instalar o Módulo do ASP.NET Core, confira Instalar o Pacote de Hospedagem do .NET Core.For instructions on how to install the ASP.NET Core Module, see Install the .NET Core Hosting Bundle.

Configuração com web.configConfiguration with 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.The ASP.NET Core Module is configured with the aspNetCore section of the system.webServer node in the site's web.config file.

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:The following web.config file is published for a framework-dependent deployment and configures the ASP.NET Core Module to handle site requests:

<?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:The following web.config is published for a self-contained deployment:

<?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.The InheritInChildApplications property is set to false to indicate that the settings specified within the <location> element aren't inherited by apps that reside in a subdirectory of the app.

Quando um aplicativo é implantado no Serviço de Aplicativo do Azure, o caminho stdoutLogFile é definido para \\?\%home%\LogFiles\stdout.When an app is deployed to Azure App Service, the stdoutLogFile path is set to \\?\%home%\LogFiles\stdout. O caminho salva logs de stdout para a pasta LogFiles, que é um local criado automaticamente pelo serviço.The path saves stdout logs to the LogFiles folder, which is a location automatically created by the service.

Para saber mais sobre a configuração de subaplicativos do IIS, confira Hospedar o ASP.NET Core no Windows com o IIS.For information on IIS sub-application configuration, see Hospedar o ASP.NET Core no Windows com o IIS.

Atributos do elemento aspNetCoreAttributes of the aspNetCore element

AtributoAttribute DescriçãoDescription PadrãoDefault
arguments

Atributo de cadeia de caracteres opcional.Optional string attribute.

Argumentos para o executável especificado em processPath.Arguments to the executable specified in processPath.

disableStartUpErrorPage

Atributo booliano opcional.Optional Boolean attribute.

Se for true, a página 502.5 – Falha do Processo será suprimida e a página de código de status 502, configurada no web.config, terá precedência.If true, the 502.5 - Process Failure page is suppressed, and the 502 status code page configured in the web.config takes precedence.

false
forwardWindowsAuthToken

Atributo booliano opcional.Optional Boolean attribute.

Se for true, o token será encaminhado para o processo filho escutando em %ASPNETCORE_PORT% como um cabeçalho 'MS-ASPNETCORE-WINAUTHTOKEN' por solicitação.If true, the token is forwarded to the child process listening on %ASPNETCORE_PORT% as a header 'MS-ASPNETCORE-WINAUTHTOKEN' per request. É responsabilidade desse processo chamar CloseHandle nesse token por solicitação.It's the responsibility of that process to call CloseHandle on this token per request.

true
hostingModel

Atributo de cadeia de caracteres opcional.Optional string attribute.

Especifica o modelo de hospedagem como em processo (InProcess) ou de fora do processo (OutOfProcess).Specifies the hosting model as in-process (InProcess) or out-of-process (OutOfProcess).

OutOfProcess
processesPerApplication

Atributo inteiro opcional.Optional integer attribute.

Especifica o número de instâncias do processo especificado na configuração processPath que pode ser ativada por aplicativo.Specifies the number of instances of the process specified in the processPath setting that can be spun up per app.

†Para hospedagem em processo, o valor está limitado a 1.†For in-process hosting, the value is limited to 1.

A configuração processesPerApplication é desencorajada.Setting processesPerApplication is discouraged. Esse atributo será removido em uma versão futura.This attribute will be removed in a future release.

Padrão: 1Default: 1
Mín.: 1Min: 1
Máx.: 100Max: 100
processPath

Atributo de cadeia de caracteres obrigatório.Required string attribute.

Caminho para o executável que inicia um processo que escuta solicitações HTTP.Path to the executable that launches a process listening for HTTP requests. Caminhos relativos são compatíveis.Relative paths are supported. Se o caminho começa com ., o caminho é considerado relativo à raiz do site.If the path begins with ., the path is considered to be relative to the site root.

rapidFailsPerMinute

Atributo inteiro opcional.Optional integer attribute.

Especifica o número de vezes que o processo especificado em processPath pode falhar por minuto.Specifies the number of times the process specified in processPath is allowed to crash per minute. Se esse limite for excedido, o módulo interromperá a inicialização do processo pelo restante do minuto.If this limit is exceeded, the module stops launching the process for the remainder of the minute.

Sem suporte com hospedagem padrão.Not supported with in-process hosting.

Padrão: 10Default: 10
Mín.: 0Min: 0
Máx.: 100Max: 100
requestTimeout

Atributo de intervalo de tempo opcional.Optional timespan attribute.

Especifica a duração para a qual o Módulo do ASP.NET Core aguarda uma resposta do processo que escuta em %ASPNETCORE_PORT%.Specifies the duration for which the ASP.NET Core Module waits for a response from the process listening on %ASPNETCORE_PORT%.

Em versões do Módulo do ASP.NET Core que acompanham a versão do ASP.NET Core 2.1 ou posterior, o requestTimeout é especificado em horas, minutos e segundos.In versions of the ASP.NET Core Module that shipped with the release of ASP.NET Core 2.1 or later, the requestTimeout is specified in hours, minutes, and seconds.

Não se aplica à hospedagem em processo.Doesn't apply to in-process hosting. Para a hospedagem em processo, o módulo aguarda o aplicativo processar a solicitação.For in-process hosting, the module waits for the app to process the request.

Os valores válidos para segmentos de minutos e segundos da cadeia de caracteres estão no intervalo 0 a 59.Valid values for minutes and seconds segments of the string are in the range 0-59. O uso de 60 no valor para minutos ou segundos resulta em um 500 - Erro Interno do Servidor.Use of 60 in the value for minutes or seconds results in a 500 - Internal Server Error.

Padrão: 00:02:00Default: 00:02:00
Mín.: 00:00:00Min: 00:00:00
Máx.: 360:00:00Max: 360:00:00
shutdownTimeLimit

Atributo inteiro opcional.Optional integer attribute.

Duração em segundos que o módulo espera para o executável desligar normalmente quando o arquivo app_offline.htm é detectado.Duration in seconds that the module waits for the executable to gracefully shutdown when the app_offline.htm file is detected.

Padrão: 10Default: 10
Mín.: 0Min: 0
Máx.: 600Max: 600
startupTimeLimit

Atributo inteiro opcional.Optional integer attribute.

Duração em segundos que o módulo espera para o arquivo executável iniciar um processo escutando na porta.Duration in seconds that the module waits for the executable to start a process listening on the port. Se esse tempo limite é excedido, o módulo encerra o processo.If this time limit is exceeded, the module kills the process. O módulo tentará reiniciar o processo quando ele receber uma nova solicitação e continuará a tentar reiniciar o processo em solicitações subsequentes de entrada, a menos que o aplicativo falhe em iniciar um número de vezes igual a rapidFailsPerMinute no último minuto sem interrupção.The module attempts to relaunch the process when it receives a new request and continues to attempt to restart the process on subsequent incoming requests unless the app fails to start rapidFailsPerMinute number of times in the last rolling minute.

Um valor de 0 (zero) não é considerado um tempo limite infinito.A value of 0 (zero) is not considered an infinite timeout.

Padrão: 120Default: 120
Mín.: 0Min: 0
Máx.: 3600Max: 3600
stdoutLogEnabled

Atributo booliano opcional.Optional Boolean attribute.

Se for true, stdout e stderr para o processo especificado em processPath serão redirecionados para o arquivo especificado em stdoutLogFile.If true, stdout and stderr for the process specified in processPath are redirected to the file specified in stdoutLogFile.

false
stdoutLogFile

Atributo de cadeia de caracteres opcional.Optional string attribute.

Especifica o caminho relativo ou absoluto para o qual stdout e stderr do processo especificado em processPath são registrados em log.Specifies the relative or absolute file path for which stdout and stderr from the process specified in processPath are logged. Os caminhos relativos são relativos à raiz do site.Relative paths are relative to the root of the site. Qualquer caminho começando com . é relativo à raiz do site e todos os outros caminhos são tratados como caminhos absolutos.Any path starting with . are relative to the site root and all other paths are treated as absolute paths. Todas as pastas fornecidas no caminho são criadas pelo módulo quando o arquivo de log é criado.Any folders provided in the path are created by the module when the log file is created. Usando delimitadores de sublinhado, um carimbo de data/hora, uma ID de processo e a extensão de arquivo ( .log) são adicionados ao último segmento do caminho stdoutLogFile.Using underscore delimiters, a timestamp, process ID, and file extension (.log) are added to the last segment of the stdoutLogFile path. Se .\logs\stdout é fornecido como um valor, um log de exemplo stdout é salvo como stdout_20180205194132_1934.log na pasta logs quando salvos em 5/2/2018, às 19:41:32, com uma ID de processo de 1934.If .\logs\stdout is supplied as a value, an example stdout log is saved as stdout_20180205194132_1934.log in the logs folder when saved on 2/5/2018 at 19:41:32 with a process ID of 1934.

aspnetcore-stdout

Definindo variáveis de ambienteSetting environment variables

Variáveis de ambiente podem ser especificadas para o processo no atributo processPath.Environment variables can be specified for the process in the processPath attribute. Especificar uma variável de ambiente com o elemento filho <environmentVariable> de um elemento de coleção <environmentVariables>.Specify an environment variable with the <environmentVariable> child element of an <environmentVariables> collection element. Variáveis de ambiente definidas nesta seção têm precedência sobre variáveis de ambiente do sistema.Environment variables set in this section take precedence over system environment variables.

O exemplo a seguir define duas variáveis de ambiente.The following example sets two environment variables. ASPNETCORE_ENVIRONMENT configura o ambiente do aplicativo para Development.ASPNETCORE_ENVIRONMENT configures the app's environment to 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.A developer may temporarily set this value in the web.config file in order to force the Developer Exception Page to load when debugging an app exception. 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.CONFIG_DIR is an example of a user-defined environment variable, where the developer has written code that reads the value on startup to form a path for loading the app's configuration file.

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

Observação

Em vez de configurar o ambiente diretamente no web.config, você pode incluir a propriedade <EnvironmentName> no perfil de publicação ( .pubxml) ou no perfil de projeto.An alternative to setting the environment directly in web.config is to include the <EnvironmentName> property in the publish profile (.pubxml) or project file. Esta abordagem define o ambiente no arquivo web.config quando o projeto é publicado:This approach sets the environment in web.config when the project is published:

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

Aviso

Defina a variável de ambiente apenas ASPNETCORE_ENVIRONMENT para Development em servidores de preparo e de teste que não estão acessíveis a redes não confiáveis, tais como a Internet.Only set the ASPNETCORE_ENVIRONMENT environment variable to Development on staging and testing servers that aren't accessible to untrusted networks, such as the Internet.

app_offline.htmapp_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.If a file with the name app_offline.htm is detected in the root directory of an app, the ASP.NET Core Module attempts to gracefully shutdown the app and stop processing incoming requests. 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.If the app is still running after the number of seconds defined in shutdownTimeLimit, the ASP.NET Core Module kills the running process.

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.While the app_offline.htm file is present, the ASP.NET Core Module responds to requests by sending back the contents of the app_offline.htm file. Quando o arquivo app_offline.htm é removido, a próxima solicitação inicia o aplicativo.When the app_offline.htm file is removed, the next request starts the app.

Ao usar o modelo de hospedagem de fora do processo, talvez o aplicativo não desligue imediatamente se houver uma conexão aberta.When using the out-of-process hosting model, the app might not shut down immediately if there's an open connection. Por exemplo, uma conexão websocket pode atrasar o desligamento do aplicativo.For example, a websocket connection may delay app shut down.

Página de erro de inicializaçãoStart-up error page

A hospedagem em processo e fora do processo produzem páginas de erro personalizadas quando falham ao iniciar o aplicativo.Both in-process and out-of-process hosting produce custom error pages when they fail to start the app.

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.If the ASP.NET Core Module fails to find either the in-process or out-of-process request handler, a 500.0 - In-Process/Out-Of-Process Handler Load Failure status code page appears.

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.For in-process hosting if the ASP.NET Core Module fails to start the app, a 500.30 - Start Failure status code page appears.

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.For out-of-process hosting if the ASP.NET Core Module fails to launch the backend process or the backend process starts but fails to listen on the configured port, a 502.5 - Process Failure status code page appears.

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.To suppress this page and revert to the default IIS 5xx status code page, use the disableStartUpErrorPage attribute. Para obter mais informações sobre como configurar mensagens de erro personalizadas, veja Erros HTTP <httpErrors>.For more information on configuring custom error messages, see HTTP Errors <httpErrors>.

Criação de log e redirecionamentoLog creation and redirection

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.The ASP.NET Core Module redirects stdout and stderr console output to disk if the stdoutLogEnabled and stdoutLogFile attributes of the aspNetCore element are set. Todas as pastas no caminho stdoutLogFile são criadas pelo módulo quando o arquivo de log é criado.Any folders in the stdoutLogFile path are created by the module when the log file is created. 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).The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

Logs não sofrem rotação, a menos que ocorra a reciclagem/reinicialização do processo.Logs aren't rotated, unless process recycling/restart occurs. É responsabilidade do hoster limitar o espaço em disco consumido pelos logs.It's the responsibility of the hoster to limit the disk space the logs consume.

Usar o log de stdout é recomendado apenas para solucionar problemas de inicialização do aplicativo.Using the stdout log is only recommended for troubleshooting app startup issues. Não use o log de stdout para fins gerais de registro em log do aplicativo.Don't use the stdout log for general app logging purposes. 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.For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. Para obter mais informações, veja provedores de log de terceiros.For more information, see third-party logging providers.

Uma extensão de arquivo e um carimbo de data/hora são adicionados automaticamente quando o arquivo de log é criado.A timestamp and file extension are added automatically when the log file is created. 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.The log file name is composed by appending the timestamp, process ID, and file extension (.log) to the last segment of the stdoutLogFile path (typically stdout) delimited by underscores. 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.If the stdoutLogFile path ends with stdout, a log for an app with a PID of 1934 created on 2/5/2018 at 19:42:32 has the file name 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.If stdoutLogEnabled is false, errors that occur on app startup are captured and emitted to the event log up to 30 KB. Após a inicialização, todos os logs adicionais são descartados.After startup, all additional logs are discarded.

O elemento aspNetCore de exemplo a seguir configura o registro em log de stdout para um aplicativo hospedado no Serviço de Aplicativo do Azure.The following sample aspNetCore element configures stdout logging for an app hosted in Azure App Service. Um caminho local ou um caminho de compartilhamento de rede é aceitável para o registro em log local.A local path or network share path is acceptable for local logging. Confirme se a identidade do usuário AppPool tem permissão para gravar no caminho fornecido.Confirm that the AppPool user identity has permission to write to the path provided.

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="true"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="InProcess">
</aspNetCore>

Logs de diagnóstico avançadosEnhanced diagnostic logs

O Módulo do ASP.NET Core é configurável para fornecer logs de diagnóstico avançados.The ASP.NET Core Module is configurable to provide enhanced diagnostics logs. Adicione o elemento <handlerSettings> ao elemento <aspNetCore> no web.config. A definição de debugLevel como TRACE expõe uma fidelidade maior de informações de diagnóstico:Add the <handlerSettings> element to the <aspNetCore> element in web.config. Setting the debugLevel to TRACE exposes a higher fidelity of diagnostic information:

<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.Folders in the path provided to the <handlerSetting> value (logs in the preceding example) aren't created by the module automatically and should pre-exist in the deployment. 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).The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

Os valores do nível de depuração (debugLevel) podem incluir o nível e a localização.Debug level (debugLevel) values can include both the level and the location.

Níveis (na ordem do menos para o mais detalhado):Levels (in order from least to most verbose):

  • ERRORERROR
  • WARNINGWARNING
  • INFOINFO
  • TRACETRACE

Locais (vários locais são permitidos):Locations (multiple locations are permitted):

  • CONSOLECONSOLE
  • EVENTLOGEVENTLOG
  • FILEFILE

As configurações do manipulador também podem ser fornecidas por meio de variáveis de ambiente:The handler settings can also be provided via environment variables:

  • ASPNETCORE_MODULE_DEBUG_FILE – caminho para o arquivo de log de depuração.ASPNETCORE_MODULE_DEBUG_FILE – Path to the debug log file. (Padrão: aspnetcore-debug.log)(Default: aspnetcore-debug.log)
  • ASPNETCORE_MODULE_DEBUG – configuração do nível de depuração.ASPNETCORE_MODULE_DEBUG – Debug level setting.

Aviso

Não deixe o log de depuração habilitado na implantação por mais tempo que o necessário para solucionar um problema.Do not leave debug logging enabled in the deployment for longer than required to troubleshoot an issue. O tamanho do log não é limitado.The size of the log isn't limited. Deixar o log de depuração habilitado pode esgotar o espaço em disco disponível e causar falha no servidor ou no serviço de aplicativo.Leaving the debug log enabled can exhaust the available disk space and crash the server or app service.

Veja Configuração com web.config para obter um exemplo do elemento aspNetCore no arquivo web.config.See Configuration with web.config for an example of the aspNetCore element in the web.config file.

A configuração de proxy usa o protocolo HTTP e um token de emparelhamentoProxy configuration uses HTTP protocol and a pairing token

Só se aplica à hospedagem de fora do processo.Only applies to out-of-process hosting.

O proxy criado entre o Módulo do ASP.NET Core e o Kestrel usa o protocolo HTTP.The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. Não há nenhum risco de interceptação do tráfego entre o módulo e o Kestrel em um local fora do servidor.There's no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server.

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.A pairing token is used to guarantee that the requests received by Kestrel were proxied by IIS and didn't come from some other source. O token de emparelhamento é criado e definido em uma variável de ambiente (ASPNETCORE_TOKEN) pelo módulo.The pairing token is created and set into an environment variable (ASPNETCORE_TOKEN) by the module. O token de emparelhamento também é definido em um cabeçalho (MS-ASPNETCORE-TOKEN) em cada solicitação com proxy.The pairing token is also set into a header (MS-ASPNETCORE-TOKEN) on every proxied request. 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.IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. Se os valores do token forem incompatíveis, a solicitação será registrada em log e rejeitada.If the token values are mismatched, the request is logged and rejected. 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.The pairing token environment variable and the traffic between the module and Kestrel aren't accessible from a location off of the server. Sem saber o valor do token de emparelhamento, um invasor não pode enviar solicitações que ignoram a verificação no Middleware do IIS.Without knowing the pairing token value, an attacker can't submit requests that bypass the check in the IIS Middleware.

Módulo do ASP.NET Core com uma configuração do IIS compartilhadaASP.NET Core Module with an IIS Shared Configuration

O instalador do módulo do ASP.NET Core é executado com os privilégios da conta de TrustedInstaller.The ASP.NET Core Module installer runs with the privileges of the TrustedInstaller account. 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.Because the local system account doesn't have modify permission for the share path used by the IIS Shared Configuration, the installer throws an access denied error when attempting to configure the module settings in the applicationHost.config file on the share.

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:When using an IIS Shared Configuration on the same machine as the IIS installation, run the ASP.NET Core Hosting Bundle installer with the OPT_NO_SHARED_CONFIG_CHECK parameter set to 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:When the path to the shared configuration isn't on the same machine as the IIS installation, follow these steps:

  1. Desabilite a configuração compartilhada de IIS.Disable the IIS Shared Configuration.
  2. Execute o instalador.Run the installer.
  3. Exportar o arquivo applicationHost.config atualizado para o compartilhamento.Export the updated applicationHost.config file to the share.
  4. Reabilite a Configuração Compartilhada do IIS.Re-enable the IIS Shared Configuration.

Versão do módulo e logs do instalador do pacote de hospedagemModule version and Hosting Bundle installer logs

Para determinar a versão do Módulo do ASP.NET Core instalado:To determine the version of the installed ASP.NET Core Module:

  1. No sistema de hospedagem, navegue até %windir%\System32\inetsrv.On the hosting system, navigate to %windir%\System32\inetsrv.
  2. Localize o arquivo aspnetcore.dll.Locate the aspnetcore.dll file.
  3. Clique com o botão direito do mouse no arquivo e selecione Propriedades no menu contextual.Right-click the file and select Properties from the contextual menu.
  4. Selecione a guia Detalhes. A Versão do arquivo e a Versão do produto representam a versão instalada do módulo.Select the Details tab. The File version and Product version represent the installed version of the module.

Os logs de instalador do pacote de hospedagem para o módulo são encontrados em C:\Usuários\%UserName%\AppData\Local\Temp. O arquivo é nomeado dd_DotNetCoreWinSvrHosting__<carimbo de data/hora>_000_AspNetCoreModule_x64.log.The Hosting Bundle installer logs for the module are found at C:\Users\%UserName%\AppData\Local\Temp. The file is named dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

Locais dos arquivos de módulo, de esquema e de configuraçãoModule, schema, and configuration file locations

MóduloModule

IIS (x86/amd64):IIS (x86/amd64):

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

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

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

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

IIS Express (x86/amd64):IIS Express (x86/amd64):

  • %ProgramFiles%\IIS Express\aspnetcore.dll%ProgramFiles%\IIS Express\aspnetcore.dll

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

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

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

EsquemaSchema

IISIIS

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

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

IIS ExpressIIS Express

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

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

ConfiguraçãoConfiguration

IISIIS

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

IIS ExpressIIS Express

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

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

Os arquivos podem ser encontrados pesquisando por aspnetcore no arquivo applicationHost.config.The files can be found by searching for aspnetcore in the applicationHost.config file.

O 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.The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to forward web requests to backend ASP.NET Core apps.

Versões do Windows compatíveis:Supported Windows versions:

  • Windows 7 ou posteriorWindows 7 or later
  • Windows Server 2008 R2 ou posteriorWindows Server 2008 R2 or later

O módulo só funciona com o Kestrel.The module only works with Kestrel. O módulo é incompatível com HTTP.sys.The module is incompatible with 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.Because ASP.NET Core apps run in a process separate from the IIS worker process, the module also handles process management. 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.The module starts the process for the ASP.NET Core app when the first request arrives and restarts the app if it crashes. 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).This is essentially the same behavior as seen with ASP.NET 4.x apps that run in-process in IIS that are managed by the Windows Process Activation Service (WAS).

O diagrama a seguir ilustra a relação entre o IIS, o Módulo do ASP.NET Core e um aplicativo:The following diagram illustrates the relationship between IIS, the ASP.NET Core Module, and an app:

Módulo do ASP.NET Core

As solicitações chegam da Web para o driver do HTTP.sys no modo kernel.Requests arrive from the web to the kernel-mode HTTP.sys driver. O driver roteia as solicitações ao IIS na porta configurada do site, normalmente, a 80 (HTTP) ou a 443 (HTTPS).The driver routes the requests to IIS on the website's configured port, usually 80 (HTTP) or 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.The module forwards the requests to Kestrel on a random port for the app, which isn't port 80 or 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}.The module specifies the port via an environment variable at startup, and the IIS Integration Middleware configures the server to listen on http://localhost:{port}. Outras verificações são executadas e as solicitações que não se originam do módulo são rejeitadas.Additional checks are performed, and requests that don't originate from the module are rejected. 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.The module doesn't support HTTPS forwarding, so requests are forwarded over HTTP even if received by IIS over 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.After Kestrel picks up the request from the module, the request is pushed into the ASP.NET Core middleware pipeline. O pipeline do middleware manipula a solicitação e a passa como uma instância de HttpContext para a lógica do aplicativo.The middleware pipeline handles the request and passes it on as an HttpContext instance to the app's logic. O middleware adicionado pela integração do IIS atualiza o esquema, o IP remoto e pathbase para encaminhar a solicitação para o Kestrel.Middleware added by IIS Integration updates the scheme, remote IP, and pathbase to account for forwarding the request to Kestrel. A resposta do aplicativo é retornada ao IIS, que a retorna por push para o cliente HTTP que iniciou a solicitação.The app's response is passed back to IIS, which pushes it back out to the HTTP client that initiated the request.

Muitos módulos nativos, como a Autenticação do Windows, permanecem ativos.Many native modules, such as Windows Authentication, remain active. 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.To learn more about IIS modules active with the ASP.NET Core Module, see Módulos do IIS com o ASP.NET Core.

O Módulo do ASP.NET Core também pode:The ASP.NET Core Module can also:

  • Definir variáveis de ambiente para o processo de trabalho.Set environment variables for the worker process.
  • Registrar a saída StdOut no armazenamento de arquivo para a solução de problemas de inicialização.Log stdout output to file storage for troubleshooting startup issues.
  • Encaminhar tokens de autenticação do Windows.Forward Windows authentication tokens.

Como instalar e usar o Módulo do ASP.NET CoreHow to install and use the ASP.NET Core Module

Para obter instruções de como instalar o Módulo do ASP.NET Core, confira Instalar o Pacote de Hospedagem do .NET Core.For instructions on how to install the ASP.NET Core Module, see Install the .NET Core Hosting Bundle.

Configuração com web.configConfiguration with 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.The ASP.NET Core Module is configured with the aspNetCore section of the system.webServer node in the site's web.config file.

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:The following web.config file is published for a framework-dependent deployment and configures the ASP.NET Core Module to handle site requests:

<?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:The following web.config is published for a self-contained deployment:

<?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.When an app is deployed to Azure App Service, the stdoutLogFile path is set to \\?\%home%\LogFiles\stdout. O caminho salva logs de stdout para a pasta LogFiles, que é um local criado automaticamente pelo serviço.The path saves stdout logs to the LogFiles folder, which is a location automatically created by the service.

Para saber mais sobre a configuração de subaplicativos do IIS, confira Hospedar o ASP.NET Core no Windows com o IIS.For information on IIS sub-application configuration, see Hospedar o ASP.NET Core no Windows com o IIS.

Atributos do elemento aspNetCoreAttributes of the aspNetCore element

AtributoAttribute DescriçãoDescription PadrãoDefault
arguments

Atributo de cadeia de caracteres opcional.Optional string attribute.

Argumentos para o executável especificado em processPath.Arguments to the executable specified in processPath.

disableStartUpErrorPage

Atributo booliano opcional.Optional Boolean attribute.

Se for true, a página 502.5 – Falha do Processo será suprimida e a página de código de status 502, configurada no web.config, terá precedência.If true, the 502.5 - Process Failure page is suppressed, and the 502 status code page configured in the web.config takes precedence.

false
forwardWindowsAuthToken

Atributo booliano opcional.Optional Boolean attribute.

Se for true, o token será encaminhado para o processo filho escutando em %ASPNETCORE_PORT% como um cabeçalho 'MS-ASPNETCORE-WINAUTHTOKEN' por solicitação.If true, the token is forwarded to the child process listening on %ASPNETCORE_PORT% as a header 'MS-ASPNETCORE-WINAUTHTOKEN' per request. É responsabilidade desse processo chamar CloseHandle nesse token por solicitação.It's the responsibility of that process to call CloseHandle on this token per request.

true
processesPerApplication

Atributo inteiro opcional.Optional integer attribute.

Especifica o número de instâncias do processo especificado na configuração processPath que pode ser ativada por aplicativo.Specifies the number of instances of the process specified in the processPath setting that can be spun up per app.

A configuração processesPerApplication é desencorajada.Setting processesPerApplication is discouraged. Esse atributo será removido em uma versão futura.This attribute will be removed in a future release.

Padrão: 1Default: 1
Mín.: 1Min: 1
Máx.: 100Max: 100
processPath

Atributo de cadeia de caracteres obrigatório.Required string attribute.

Caminho para o executável que inicia um processo que escuta solicitações HTTP.Path to the executable that launches a process listening for HTTP requests. Caminhos relativos são compatíveis.Relative paths are supported. Se o caminho começa com ., o caminho é considerado relativo à raiz do site.If the path begins with ., the path is considered to be relative to the site root.

rapidFailsPerMinute

Atributo inteiro opcional.Optional integer attribute.

Especifica o número de vezes que o processo especificado em processPath pode falhar por minuto.Specifies the number of times the process specified in processPath is allowed to crash per minute. Se esse limite for excedido, o módulo interromperá a inicialização do processo pelo restante do minuto.If this limit is exceeded, the module stops launching the process for the remainder of the minute.

Padrão: 10Default: 10
Mín.: 0Min: 0
Máx.: 100Max: 100
requestTimeout

Atributo de intervalo de tempo opcional.Optional timespan attribute.

Especifica a duração para a qual o Módulo do ASP.NET Core aguarda uma resposta do processo que escuta em %ASPNETCORE_PORT%.Specifies the duration for which the ASP.NET Core Module waits for a response from the process listening on %ASPNETCORE_PORT%.

Em versões do Módulo do ASP.NET Core que acompanham a versão do ASP.NET Core 2.1 ou posterior, o requestTimeout é especificado em horas, minutos e segundos.In versions of the ASP.NET Core Module that shipped with the release of ASP.NET Core 2.1 or later, the requestTimeout is specified in hours, minutes, and seconds.

Padrão: 00:02:00Default: 00:02:00
Mín.: 00:00:00Min: 00:00:00
Máx.: 360:00:00Max: 360:00:00
shutdownTimeLimit

Atributo inteiro opcional.Optional integer attribute.

Duração em segundos que o módulo espera para o executável desligar normalmente quando o arquivo app_offline.htm é detectado.Duration in seconds that the module waits for the executable to gracefully shutdown when the app_offline.htm file is detected.

Padrão: 10Default: 10
Mín.: 0Min: 0
Máx.: 600Max: 600
startupTimeLimit

Atributo inteiro opcional.Optional integer attribute.

Duração em segundos que o módulo espera para o arquivo executável iniciar um processo escutando na porta.Duration in seconds that the module waits for the executable to start a process listening on the port. Se esse tempo limite é excedido, o módulo encerra o processo.If this time limit is exceeded, the module kills the process. O módulo tentará reiniciar o processo quando ele receber uma nova solicitação e continuará a tentar reiniciar o processo em solicitações subsequentes de entrada, a menos que o aplicativo falhe em iniciar um número de vezes igual a rapidFailsPerMinute no último minuto sem interrupção.The module attempts to relaunch the process when it receives a new request and continues to attempt to restart the process on subsequent incoming requests unless the app fails to start rapidFailsPerMinute number of times in the last rolling minute.

Um valor de 0 (zero) não é considerado um tempo limite infinito.A value of 0 (zero) is not considered an infinite timeout.

Padrão: 120Default: 120
Mín.: 0Min: 0
Máx.: 3600Max: 3600
stdoutLogEnabled

Atributo booliano opcional.Optional Boolean attribute.

Se for true, stdout e stderr para o processo especificado em processPath serão redirecionados para o arquivo especificado em stdoutLogFile.If true, stdout and stderr for the process specified in processPath are redirected to the file specified in stdoutLogFile.

false
stdoutLogFile

Atributo de cadeia de caracteres opcional.Optional string attribute.

Especifica o caminho relativo ou absoluto para o qual stdout e stderr do processo especificado em processPath são registrados em log.Specifies the relative or absolute file path for which stdout and stderr from the process specified in processPath are logged. Os caminhos relativos são relativos à raiz do site.Relative paths are relative to the root of the site. Qualquer caminho começando com . é relativo à raiz do site e todos os outros caminhos são tratados como caminhos absolutos.Any path starting with . are relative to the site root and all other paths are treated as absolute paths. As pastas fornecidas no caminho devem existir para que o módulo crie o arquivo de log.Any folders provided in the path must exist in order for the module to create the log file. Usando delimitadores de sublinhado, um carimbo de data/hora, uma ID de processo e a extensão de arquivo ( .log) são adicionados ao último segmento do caminho stdoutLogFile.Using underscore delimiters, a timestamp, process ID, and file extension (.log) are added to the last segment of the stdoutLogFile path. Se .\logs\stdout é fornecido como um valor, um log de exemplo stdout é salvo como stdout_20180205194132_1934.log na pasta logs quando salvos em 5/2/2018, às 19:41:32, com uma ID de processo de 1934.If .\logs\stdout is supplied as a value, an example stdout log is saved as stdout_20180205194132_1934.log in the logs folder when saved on 2/5/2018 at 19:41:32 with a process ID of 1934.

aspnetcore-stdout

Definindo variáveis de ambienteSetting environment variables

Variáveis de ambiente podem ser especificadas para o processo no atributo processPath.Environment variables can be specified for the process in the processPath attribute. Especificar uma variável de ambiente com o elemento filho <environmentVariable> de um elemento de coleção <environmentVariables>.Specify an environment variable with the <environmentVariable> child element of an <environmentVariables> collection element.

Aviso

As variáveis de ambiente definidas nesta seção são conflitantes com as variáveis de ambiente do sistema definidas com o mesmo nome.Environment variables set in this section conflict with system environment variables set with the same name. Quando a variável de ambiente é definida no arquivo web.config e no nível do sistema do Windows, o valor do arquivo web.config fica anexado ao valor da variável de ambiente do sistema (por exemplo, ASPNETCORE_ENVIRONMENT: Development;Development), o que impede a inicialização do aplicativo.If an environment variable is set in both the web.config file and at the system level in Windows, the value from the web.config file becomes appended to the system environment variable value (for example, ASPNETCORE_ENVIRONMENT: Development;Development), which prevents the app from starting.

O exemplo a seguir define duas variáveis de ambiente.The following example sets two environment variables. ASPNETCORE_ENVIRONMENT configura o ambiente do aplicativo para Development.ASPNETCORE_ENVIRONMENT configures the app's environment to 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.A developer may temporarily set this value in the web.config file in order to force the Developer Exception Page to load when debugging an app exception. 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.CONFIG_DIR is an example of a user-defined environment variable, where the developer has written code that reads the value on startup to form a path for loading the app's configuration file.

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

Aviso

Defina a variável de ambiente apenas ASPNETCORE_ENVIRONMENT para Development em servidores de preparo e de teste que não estão acessíveis a redes não confiáveis, tais como a Internet.Only set the ASPNETCORE_ENVIRONMENT environment variable to Development on staging and testing servers that aren't accessible to untrusted networks, such as the Internet.

app_offline.htmapp_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.If a file with the name app_offline.htm is detected in the root directory of an app, the ASP.NET Core Module attempts to gracefully shutdown the app and stop processing incoming requests. 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.If the app is still running after the number of seconds defined in shutdownTimeLimit, the ASP.NET Core Module kills the running process.

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.While the app_offline.htm file is present, the ASP.NET Core Module responds to requests by sending back the contents of the app_offline.htm file. Quando o arquivo app_offline.htm é removido, a próxima solicitação inicia o aplicativo.When the app_offline.htm file is removed, the next request starts the app.

Página de erro de inicializaçãoStart-up error page

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.If the ASP.NET Core Module fails to launch the backend process or the backend process starts but fails to listen on the configured port, a 502.5 - Process Failure status code page appears. 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.To suppress this page and revert to the default IIS 502 status code page, use the disableStartUpErrorPage attribute. Para obter mais informações sobre como configurar mensagens de erro personalizadas, veja Erros HTTP <httpErrors>.For more information on configuring custom error messages, see HTTP Errors <httpErrors>.

Página de código de status 502.5 – Falha do Processo

Criação de log e redirecionamentoLog creation and redirection

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.The ASP.NET Core Module redirects stdout and stderr console output to disk if the stdoutLogEnabled and stdoutLogFile attributes of the aspNetCore element are set. Todas as pastas no caminho stdoutLogFile são criadas pelo módulo quando o arquivo de log é criado.Any folders in the stdoutLogFile path are created by the module when the log file is created. 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).The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

Logs não sofrem rotação, a menos que ocorra a reciclagem/reinicialização do processo.Logs aren't rotated, unless process recycling/restart occurs. É responsabilidade do hoster limitar o espaço em disco consumido pelos logs.It's the responsibility of the hoster to limit the disk space the logs consume.

Usar o log de stdout é recomendado apenas para solucionar problemas de inicialização do aplicativo.Using the stdout log is only recommended for troubleshooting app startup issues. Não use o log de stdout para fins gerais de registro em log do aplicativo.Don't use the stdout log for general app logging purposes. 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.For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. Para obter mais informações, veja provedores de log de terceiros.For more information, see third-party logging providers.

Uma extensão de arquivo e um carimbo de data/hora são adicionados automaticamente quando o arquivo de log é criado.A timestamp and file extension are added automatically when the log file is created. 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.The log file name is composed by appending the timestamp, process ID, and file extension (.log) to the last segment of the stdoutLogFile path (typically stdout) delimited by underscores. 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.If the stdoutLogFile path ends with stdout, a log for an app with a PID of 1934 created on 2/5/2018 at 19:42:32 has the file name stdout_20180205194132_1934.log.

O elemento aspNetCore de exemplo a seguir configura o registro em log de stdout para um aplicativo hospedado no Serviço de Aplicativo do Azure.The following sample aspNetCore element configures stdout logging for an app hosted in Azure App Service. Um caminho local ou um caminho de compartilhamento de rede é aceitável para o registro em log local.A local path or network share path is acceptable for local logging. Confirme se a identidade do usuário AppPool tem permissão para gravar no caminho fornecido.Confirm that the AppPool user identity has permission to write to the path provided.

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="true"
    stdoutLogFile="\\?\%home%\LogFiles\stdout">
</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.Folders in the path provided to the <handlerSetting> value (logs in the preceding example) aren't created by the module automatically and should pre-exist in the deployment. 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).The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

Veja Configuração com web.config para obter um exemplo do elemento aspNetCore no arquivo web.config.See Configuration with web.config for an example of the aspNetCore element in the web.config file.

A configuração de proxy usa o protocolo HTTP e um token de emparelhamentoProxy configuration uses HTTP protocol and a pairing token

O proxy criado entre o Módulo do ASP.NET Core e o Kestrel usa o protocolo HTTP.The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. Não há nenhum risco de interceptação do tráfego entre o módulo e o Kestrel em um local fora do servidor.There's no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server.

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.A pairing token is used to guarantee that the requests received by Kestrel were proxied by IIS and didn't come from some other source. O token de emparelhamento é criado e definido em uma variável de ambiente (ASPNETCORE_TOKEN) pelo módulo.The pairing token is created and set into an environment variable (ASPNETCORE_TOKEN) by the module. O token de emparelhamento também é definido em um cabeçalho (MS-ASPNETCORE-TOKEN) em cada solicitação com proxy.The pairing token is also set into a header (MS-ASPNETCORE-TOKEN) on every proxied request. 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.IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. Se os valores do token forem incompatíveis, a solicitação será registrada em log e rejeitada.If the token values are mismatched, the request is logged and rejected. 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.The pairing token environment variable and the traffic between the module and Kestrel aren't accessible from a location off of the server. Sem saber o valor do token de emparelhamento, um invasor não pode enviar solicitações que ignoram a verificação no Middleware do IIS.Without knowing the pairing token value, an attacker can't submit requests that bypass the check in the IIS Middleware.

Módulo do ASP.NET Core com uma configuração do IIS compartilhadaASP.NET Core Module with an IIS Shared Configuration

O instalador do módulo do ASP.NET Core é executado com os privilégios da conta de TrustedInstaller.The ASP.NET Core Module installer runs with the privileges of the TrustedInstaller account. 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.Because the local system account doesn't have modify permission for the share path used by the IIS Shared Configuration, the installer throws an access denied error when attempting to configure the module settings in the applicationHost.config file on the share.

Ao usar uma configuração compartilhada de IIS, siga estas etapas:When using an IIS Shared Configuration, follow these steps:

  1. Desabilite a configuração compartilhada de IIS.Disable the IIS Shared Configuration.
  2. Execute o instalador.Run the installer.
  3. Exportar o arquivo applicationHost.config atualizado para o compartilhamento.Export the updated applicationHost.config file to the share.
  4. Reabilite a Configuração Compartilhada do IIS.Re-enable the IIS Shared Configuration.

Versão do módulo e logs do instalador do pacote de hospedagemModule version and Hosting Bundle installer logs

Para determinar a versão do Módulo do ASP.NET Core instalado:To determine the version of the installed ASP.NET Core Module:

  1. No sistema de hospedagem, navegue até %windir%\System32\inetsrv.On the hosting system, navigate to %windir%\System32\inetsrv.
  2. Localize o arquivo aspnetcore.dll.Locate the aspnetcore.dll file.
  3. Clique com o botão direito do mouse no arquivo e selecione Propriedades no menu contextual.Right-click the file and select Properties from the contextual menu.
  4. Selecione a guia Detalhes. A Versão do arquivo e a Versão do produto representam a versão instalada do módulo.Select the Details tab. The File version and Product version represent the installed version of the module.

Os logs de instalador do pacote de hospedagem para o módulo são encontrados em C:\Usuários\%UserName%\AppData\Local\Temp. O arquivo é nomeado dd_DotNetCoreWinSvrHosting__<carimbo de data/hora>_000_AspNetCoreModule_x64.log.The Hosting Bundle installer logs for the module are found at C:\Users\%UserName%\AppData\Local\Temp. The file is named dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

Locais dos arquivos de módulo, de esquema e de configuraçãoModule, schema, and configuration file locations

MóduloModule

IIS (x86/amd64):IIS (x86/amd64):

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

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

IIS Express (x86/amd64):IIS Express (x86/amd64):

  • %ProgramFiles%\IIS Express\aspnetcore.dll%ProgramFiles%\IIS Express\aspnetcore.dll

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

EsquemaSchema

IISIIS

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

IIS ExpressIIS Express

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

ConfiguraçãoConfiguration

IISIIS

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

IIS ExpressIIS Express

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

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

Os arquivos podem ser encontrados pesquisando por aspnetcore no arquivo applicationHost.config.The files can be found by searching for aspnetcore in the applicationHost.config file.

Recursos adicionaisAdditional resources