Arquivo web.config

  • Artigo

O web.config é um arquivo lido pelo IIS e pelo Módulo ASP.NET Core para configurar um aplicativo hospedado com o IIS.

Local do arquivo web.config

Para configurar o Módulo do ASP.NET Core corretamente, o arquivo web.config deve estar presente no caminho raiz do conteúdo (geralmente, o aplicativo base do caminho) do aplicativo implantado. Esse é o mesmo local que o caminho físico do site fornecido ao IIS. O arquivo web.config é necessário na raiz do aplicativo para habilitar a publicação de vários aplicativos usando a Implantação da Web.

Existem arquivos confidenciais no caminho físico do aplicativo, como {ASSEMBLY}.runtimeconfig.json, {ASSEMBLY}.xml (comentários da Documentação XML) e {ASSEMBLY}.deps.json, onde o espaço reservado {ASSEMBLY} é o nome do assembly. Quando o arquivo web.config estiver presente e o site for iniciado normalmente, o IIS não fornecerá esses arquivos confidenciais se eles forem solicitados. Se o arquivo web.config estiver ausente, for nomeado incorretamente ou se não for possível configurar o site para inicialização normal, o IIS poderá servir arquivos confidenciais publicamente.

O arquivo web.config deve estar presente na implantação em todos os momentos, nomeado corretamente e ser capaz de configurar o site para inicialização normal. Nunca remova o arquivo web.config de uma implantação de produção.

Se um arquivo web.config não estiver presente no projeto, ele será criado com o processPath e o arguments corretos para configurar o Módulo do ASP.NET Core e será transferido para o resultado publicado.

Se um arquivo web.config estiver presente no projeto, ele será transformado com o processPath e o arguments para configurar o Módulo do ASP.NET Core e será transferido para o resultado publicado. A transformação não altera as definições de configuração do IIS no arquivo.

O arquivo web.config pode fornecer configurações adicionais do IIS que controlam módulos ativos do IIS. Para saber mais sobre os módulos do IIS que podem processar solicitações com aplicativos do ASP.NET Core, veja o tópico Módulos do IIS.

A criação, a transformação e a publicação do arquivo web.config são tratadas por um destino do MSBuild (_TransformWebConfig) quando o projeto é publicado. Este destino está presente nos destinos do SDK da Web (Microsoft.NET.Sdk.Web). O SDK é definido na parte superior do arquivo de projeto:

<Project Sdk="Microsoft.NET.Sdk.Web">

Para impedir que o SDK Web transforme o arquivo web.config, use a propriedade <IsTransformWebConfigDisabled> no arquivo do projeto:

<PropertyGroup>
  <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
</PropertyGroup>

Ao impedir que o SDK Web transforme o arquivo, o processPath e o argumentsdevem ser definidos manualmente pelo desenvolvedor. Para obter mais informações, confira Módulo do ASP.NET Core (ANCM) para o IIS.

Configuração do Módulo ASP.NET Core com web.config

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

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

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet"
                  arguments=".\MyApp.dll"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

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

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath=".\MyApp.exe"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

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

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

Para saber mais sobre a configuração de subaplicativos do IIS, consulte Configuração avançada.

Atributos do elemento aspNetCore

Atributo Descrição Padrão
arguments

Atributo de cadeia de caracteres opcional.

Argumentos para o executável especificado em processPath.
disableStartUpErrorPage

Atributo booliano opcional.

Se for true, a página 502.5 - Falha do Processo será suprimida e a página de código de status 502, configurada no web.config, terá precedência.

 false
forwardWindowsAuthToken

Atributo booliano opcional.

Se for true, o token será encaminhado para o processo filho escutando em %ASPNETCORE_PORT% como um cabeçalho 'MS-ASPNETCORE-WINAUTHTOKEN' por solicitação. É responsabilidade desse processo chamar CloseHandle nesse token por solicitação.

 true
hostingModel

Atributo de cadeia de caracteres opcional.

Especifica o modelo de hospedagem como em processo (InProcess/inprocess) ou fora do processo (OutOfProcess/outofprocess).

 OutOfProcess/outofprocess quando não está presente
processesPerApplication

Atributo inteiro opcional.

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

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

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

 Padrão: 1
Mín.: 1
Máx.: 100†
processPath

Atributo de cadeia de caracteres obrigatório.

Caminho para o executável que inicia um processo que escuta solicitações HTTP. Caminhos relativos são compatíveis. Se o caminho começa com ., o caminho é considerado relativo à raiz do site.
rapidFailsPerMinute

Atributo inteiro opcional.

Especifica o número de vezes que o processo especificado em processPath pode falhar por minuto. Se esse limite for excedido, o módulo interromperá a inicialização do processo pelo restante do minuto.

Sem suporte com hospedagem padrão.

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

Atributo de intervalo de tempo opcional.

Especifica a duração para a qual o Módulo do ASP.NET Core aguarda uma resposta do processo que escuta em %ASPNETCORE_PORT%.

Em versões do Módulo do ASP.NET Core que acompanham a versão do ASP.NET Core 2.1 ou posterior, o requestTimeout é especificado em horas, minutos e segundos.

Não se aplica à hospedagem em processo. Para a hospedagem em processo, o módulo aguarda o aplicativo processar a solicitação.

Os valores válidos para segmentos de minutos e segundos da cadeia de caracteres estão no intervalo 0 a 59. O uso de 60 no valor para minutos ou segundos resulta em um 500 - Erro Interno do Servidor.

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

Atributo inteiro opcional.

Duração em segundos que o módulo espera para o executável desligar normalmente quando o arquivo app_offline.htm é detectado.

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

Atributo inteiro opcional.

Duração em segundos que o módulo espera para o arquivo executável iniciar um processo escutando na porta. Se esse tempo limite é excedido, o módulo encerra o processo.

Ao hospedar em processo: o processo não é reiniciado e não usa a configuração rapidFailsPerMinute.

Ao hospedar de fora do processo: o módulo tentará reiniciar o processo quando ele receber uma nova solicitação e continuará a tentar reiniciar o processo em solicitações subsequentes de entrada, a menos que o aplicativo falhe em iniciar um número de vezes igual a rapidFailsPerMinute no último minuto sem interrupção.

Um valor de 0 (zero) não é considerado um tempo limite infinito.

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

Atributo booliano opcional.

Se for true, stdout e stderr para o processo especificado em processPath serão redirecionados para o arquivo especificado em stdoutLogFile.

 false
stdoutLogFile

Atributo de cadeia de caracteres opcional.

Especifica o caminho relativo ou absoluto para o qual stdout e stderr do processo especificado em processPath são registrados em log. Os caminhos relativos são relativos à raiz do site. Qualquer caminho começando com . é relativo à raiz do site e todos os outros caminhos são tratados como caminhos absolutos. Todas as pastas fornecidas no caminho são criadas pelo módulo quando o arquivo de log é criado. Usando delimitadores de sublinhado, um carimbo de data/hora, uma ID de processo e a extensão de arquivo (.log) são adicionados ao último segmento do caminho stdoutLogFile. Se .\logs\stdout é fornecido como um valor, um log de exemplo stdout é salvo como stdout_20180205194132_1934.log na pasta logs quando salvos em 5 de fevereiro de 2018, às 19:41:32, com uma ID de processo de 1934.

 aspnetcore-stdout

Definir variáveis de ambiente

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

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

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

Observação

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

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

Aviso

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

Configuração do IIS com web.config

A configuração do IIS é influenciada pela seção <system.webServer> do web.config para cenários do IIS que são funcionais para aplicativos ASP.NET Core com o Módulo do ASP.NET Core. Por exemplo, a configuração do IIS é funcional para a compactação dinâmica. Se o IIS for configurado no nível do servidor para usar a compactação dinâmica, o elemento <urlCompression> no arquivo web.config do aplicativo pode desabilitá-la para um aplicativo do ASP.NET Core.

Para obter mais informações, consulte estes tópicos:

Para definir variáveis de ambiente para aplicativos individuais executados em pools de aplicativos isolados (compatível com o IIS 10.0 ou posterior), veja a seção AppCmd.exe comando do tópico Variáveis de ambiente <environmentVariables> na documentação de referência do IIS.

Seções de configuração do web.config

As seções de configuração de aplicativos ASP.NET 4.x em web.config não são usadas por aplicativos ASP.NET Core para configuração:

  • <system.web>
  • <appSettings>
  • <connectionStrings>
  • <location>

Aplicativos ASP.NET Core são configurados para usar outros provedores de configuração. Para obter mais informações, confira Configuração.

Transformação do Web.config

Se você precisar transformar web.config na publicação, consulte Transformar web.config. Talvez seja necessário transformar web.config na publicação para definir variáveis de ambiente com base na configuração, no perfil ou no ambiente.

Recursos adicionais