Archivo web.config

  • Artículo

web.config es un archivo que IIS y el módulo de ASP.NET Core leen para configurar una aplicación hospedada en IIS.

Ubicación del archivo web.config

Para configurar el módulo ASP.NET correctamente, el archivo web.config debe estar presente en la ruta raíz de contenido (normalmente la ruta de acceso base de la aplicación) de la aplicación implementada. Se trata de la misma ubicación que la ruta de acceso física del sitio web proporcionada a IIS. El archivo web.config debe estar en la raíz de la aplicación para habilitar la publicación de varias aplicaciones mediante Web Deploy.

Los archivos confidenciales están en la ruta de acceso física de la aplicación, como {ASSEMBLY}.runtimeconfig.json, {ASSEMBLY}.xml (comentarios de documentación XML), y {ASSEMBLY}.deps.json, donde el marcador de posición {ASSEMBLY} es el nombre del ensamblado. Si el archivo web.config está presente y el sitio se inicia normalmente, IIS no facilita estos archivos confidenciales, en el caso de que se soliciten. Si el archivo web.config no está presente, se le asignó un nombre incorrecto o no se puede configurar el sitio para un inicio normal, IIS puede servir archivos confidenciales públicamente.

El archivo web.config debe estar presente en la implementación en todo momento, se le debe asignar un nombre correcto y debe ser capaz de configurar el sitio para el inicio normal. Nunca quite el archivo web.config de una implementación de producción.

Si el proyecto no incluye un archivo web.config, el archivo se crea con los elementos processPath y arguments correctos para configurar el módulo ASP.NET Core y se mueve a la salida publicada.

Si el proyecto incluye un archivo web.config, el archivo se transforma con los elementos processPath y arguments correctos para configurar el módulo ASP.NET Core y se mueve a la salida publicada. La transformación no modifica los valores de configuración de IIS del archivo.

El archivo web.config puede proporcionar valores de configuración de IIS adicionales que controlan los módulos activos de IIS. Para información sobre los módulos de IIS que son capaces de procesar las solicitudes con aplicaciones ASP.NET Core, vea el tema Módulos IIS.

La creación, transformación y publicación del archivo web.config se controla por medio de un destino de MSBuild (_TransformWebConfig) cuando el proyecto se publica. Este destino está incluido entre los destinos del SDK web (Microsoft.NET.Sdk.Web). El SDK se establece al inicio del archivo del proyecto:

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

Para evitar que el SDK web transforme el archivo web.config, use la propiedad <IsTransformWebConfigDisabled> en el archivo del proyecto:

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

Al deshabilitar el SDK web para la transformación del archivo, el desarrollador debe establecer el elemento processPath y los arguments manualmente. Para obtener más información vea Módulo de ASP.NET Core (ANCM) para IIS.

Configuración del módulo de ASP.NET Core con web.config

El módulo ASP.NET Core se configura con la sección aspNetCore del nodo system.webServer del archivo web.config del sitio.

El siguiente archivo web.config se publica para una implementación dependiente del marco y configura el módulo ASP.NET Core para controlar las solicitudes de sitios:

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

El siguiente archivo web.config se publica para una implementación independiente:

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

La propiedad InheritInChildApplications está establecida en false para indicar que las aplicaciones que residen en un subdirectorio de la aplicación no heredan la configuración especificada en el elemento <location>.

Cuando se implementa una aplicación en Azure App Service, la ruta de acceso de stdoutLogFile se establece en \\?\%home%\LogFiles\stdout. La ruta de acceso guarda los registros de stdout en la carpeta LogFiles, que es una ubicación que el servicio crea automáticamente.

Para obtener información sobre la configuración de aplicaciones secundarias de IIS, vea Configuración avanzada.

Atributos del elemento aspNetCore

Atributo Descripción Default
arguments

Atributo de cadena opcional.

Argumentos para el archivo ejecutable especificado en processPath.
disableStartUpErrorPage

Atributo Boolean opcional.

Si es true, la página 502.5 - Error en el proceso se suprime, y tiene prioridad la página de código de estado 502 configurada en web.config.

 false
forwardWindowsAuthToken

Atributo Boolean opcional.

Si es "true", el token se reenvía al proceso secundario que escucha en %ASPNETCORE_PORT% como un encabezado "MS-ASPNETCORE-WINAUTHTOKEN" por solicitud. Es responsabilidad de dicho proceso llamar a CloseHandle en este token por solicitud.

 true
hostingModel

Atributo de cadena opcional.

Especifica el modelo de hospedaje como en proceso (InProcess/inprocess) o fuera de proceso (OutOfProcess/outofprocess).

 OutOfProcess/outofprocess cuando no está presente
processesPerApplication

Atributo integer opcional.

Especifica el número de instancias del proceso especificado en el valor processPath que pueden rotarse por aplicación.

†En el hospedaje en proceso, el valor está limitado a 1.

No se recomienda establecer processesPerApplication. Este atributo se quitará en futuras versiones.

 Valor predeterminado: 1
Mínimo: 1
Máximo: 100†
processPath

Atributo de cadena necesario.

Ruta de acceso al archivo ejecutable que inicia un proceso que escucha las solicitudes HTTP. No se admiten rutas de acceso relativas. Si la ruta de acceso comienza con ., se considera que es relativa a la raíz del sitio.
rapidFailsPerMinute

Atributo integer opcional.

Especifica el número de veces que el proceso indicado en processPath puede bloquearse por minuto. Si se supera este límite, el módulo deja de iniciar el proceso durante lo que resta del minuto.

No admitido con el hospedaje en proceso.

 Valor predeterminado: 10
Mínimo: 0
Máximo: 100
requestTimeout

Atributo timespan opcional.

Especifica el tiempo que el módulo ASP.NET Core espera una respuesta del proceso que escucha en % ASPNETCORE_PORT %.

En las versiones del módulo ASP.NET Core que se envían con la versión de ASP.NET Core 2.1 o posterior, el valor requestTimeout se especifica en horas, minutos y segundos.

No se aplica al hospedaje en proceso. En el hospedaje en proceso, el módulo espera a que la aplicación procese la solicitud.

Los valores válidos para los segmentos de minutos y segundos de la cadena se encuentran en el rango 0-59. El uso de 60 en el valor de minutos o segundos da como resultado el error 500: Error interno del servidor.

 Valor predeterminado: 00:02:00
Mínimo: 00:00:00
Máximo: 360:00:00
shutdownTimeLimit

Atributo integer opcional.

Tiempo en segundos que el módulo espera a que se cierre correctamente el archivo ejecutable cuando se detecta el archivo app_offline.htm.

 Valor predeterminado: 10
Mínimo: 0
Máximo: 600
startupTimeLimit

Atributo integer opcional.

Tiempo en segundos que espera el módulo a que el archivo ejecutable inicie u proceso que escucha en el puerto. Si se supera este límite de tiempo, el módulo termina el proceso.

Al hospedar en proceso: El proceso no se reinicia y no usa la configuración rapidFailsPerMinute.

Al hospedar fuera del proceso: El módulo intenta reiniciar el proceso cuando se recibe una nueva solicitud y lo sigue intentando en las sucesivas solicitudes entrantes a no ser que la aplicación no pueda iniciar rapidFailsPerMinute un número de veces en el último minuto acumulado.

Un valor de 0 (cero) no se considera un tiempo de expiración infinito.

 Valor predeterminado: 120
Mínimo: 0
Máximo: 3600
stdoutLogEnabled

Atributo Boolean opcional.

Si es true, stdout y stderr en el proceso especificado en processPath se redirigen al archivo especificado en stdoutLogFile.

 false
stdoutLogFile

Atributo de cadena opcional.

Especifica la ruta de acceso relativa o absoluta para la que se registran stdout y stderr desde el proceso especificado en processPath. Las rutas de acceso relativas son relativas a la raíz del sitio. Cualquier ruta de acceso que se inicia con . es relativa a la raíz del sitio y todas las demás rutas de acceso se tratan como absolutas. Al crearse el archivo de registro, el módulo crea las carpetas que se proporcionan en la ruta de acceso. Mediante delimitadores se agrega una marca de tiempo, un identificador de proceso y una extensión de archivo ( .log) al último segmento de la ruta de acceso stdoutLogFile. Si se proporciona .\logs\stdout como valor, se guarda un registro de ejemplo de stdout como stdout_20180205194132_1934.log en la carpeta logs, si se guarda el 5 de febrero de 2018 a las 19:41:32 con un identificador de proceso de 1934.

 aspnetcore-stdout

Establecimiento de las variables de entorno

Se pueden especificar variables de entorno para el proceso en el atributo processPath. Especifique una variable de entorno con el elemento secundario <environmentVariable> de un elemento de la colección <environmentVariables>. Las variables de entorno establecidas en esta sección tienen prioridad sobre las variables del entorno del sistema.

En el ejemplo siguiente se establecen dos variables de entorno en web.config. ASPNETCORE_ENVIRONMENT configura el entorno de la aplicación como Development. Un desarrollador puede establecer temporalmente este valor en el archivo web.config con el fin de forzar a que se cargue la página de excepciones del desarrollador al depurar una excepción de aplicación. CONFIG_DIR es un ejemplo de una variable de entorno definida por el usuario, donde el desarrollador ha escrito código que lee el valor al inicio para formar una ruta de acceso destinada a la carga del archivo de configuración de la aplicación.

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

Nota

Una alternativa a establecer directamente el entorno en web.config consiste en incluir la propiedad <EnvironmentName> en el perfil de publicación (.pubxml) o el archivo de proyecto. Este método establece el entorno en web.config cuando se publica el proyecto:

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

Advertencia

Establezca solo la variable de entorno ASPNETCORE_ENVIRONMENT en Development en servidores de ensayo y pruebas a los que no puedan acceder redes que no son de confianza, como Internet.

Configuración de IIS con web.config

En escenarios de IIS que son funcionales para aplicaciones ASP.NET Core con el módulo ASP.NET Core, la configuración de IIS está influenciada por la sección <system.webServer> de web.config. Por ejemplo, la configuración de IIS es funcional para la compresión dinámica. Si IIS está configurado en el nivel de servidor para usar compresión dinámica, el elemento <urlCompression> del archivo web.config de la aplicación puede deshabilitarlo para una aplicación ASP.NET Core.

Para obtener más información, vea los temas siguientes:

Para establecer variables de entorno para aplicaciones individuales que se ejecutan en grupos de aplicaciones aislados (compatible con IIS 10.0 o posterior), vea la sección Comando AppCmd.exe del tema Variables de entorno <environmentVariables> de la documentación de referencia de IIS.

Secciones de configuración de web.config

Las aplicaciones ASP.NET Core no usan las secciones de configuración de aplicaciones ASP.NET 4.x en web.config para la configuración:

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

Las aplicaciones de ASP.NET Core se configuran mediante otros proveedores de configuración. Para obtener más información, vea Configuración.

Transformación de web.config

Si necesita transformar web.config al realizar la publicación, consulte Transformación de web.config. Es posible que necesite transformar web.config al realizar la publicación para establecer variables de entorno basadas en la configuración, el perfil o el entorno.

Recursos adicionales