Módulo ASP.NET Core (ANCM) para IIS
Nota:
Esta no es la versión más reciente de este artículo. Para la versión actual, consulte la versión de .NET 9 de este artículo.
Advertencia
Esta versión de ASP.NET Core ya no se admite. Para obtener más información, consulta la Directiva de soporte técnico de .NET y .NET Core. Para la versión actual, consulta la versión .NET 8 de este artículo.
Importante
Esta información hace referencia a un producto en versión preliminar, el cual puede sufrir importantes modificaciones antes de que se publique la versión comercial. Microsoft no proporciona ninguna garantía, expresa o implícita, con respecto a la información proporcionada aquí.
Para la versión actual, consulte la versión de .NET 9 de este artículo.
El módulo de ASP.NET Core (ANCM) es un módulo nativo de IIS que se conecta a la canalización de IIS, lo que permite que las aplicaciones de ASP.NET Core funcionen con IIS. Para ejecutar las aplicaciones de ASP.NET Core con IIS puede:
- Hospedar una aplicación de ASP.NET Core dentro del proceso de trabajo de IIS (
w3wp.exe
), lo que se denomina modelo de hospedaje en proceso. - Reenviar solicitudes web a una aplicación de ASP.NET Core de back-end que ejecuta el servidor de Kestrel, lo que se denomina modelo de hospedaje fuera de proceso.
Existen ventajas y desventajas entre cada uno de los modelos de hospedaje. De manera predeterminada, se usa el modelo de hospedaje en proceso por el mejor rendimiento y diagnóstico que ofrece.
Para obtener más información e instrucciones de configuración, vea los temas siguientes:
Instalación del módulo de ASP.NET Core (ANCM)
El módulo ASP.NET Core (ANCM) se instala con el entorno de ejecución de .NET Core desde el conjunto de hospedaje de .NET Core. El módulo ASP.NET Core es compatible con versiones anteriores y posteriores de las versiones con soporte técnico de .NET.
Los cambios importantes y los avisos de seguridad se notifican en el repositorio de anuncios. Los anuncios se pueden limitar a una versión específica seleccionando un filtro de etiqueta.
Descargue al instalador mediante el vínculo siguiente:
Instalador del conjunto de hospedaje de .NET Core actual (descarga directa)
Para más información, incluida la instalación de una versión anterior del módulo, vea Conjunto de hospedaje.
Para una experiencia de tutorial sobre la publicación de una aplicación ASP.NET Core en un servidor IIS, vea Publicación de una aplicación ASP.NET Core en IIS.
El módulo ASP.NET Core (ANCM) es un módulo nativo de IIS que se conecta a la canalización de IIS para:
- Hospedar una aplicación ASP.NET Core dentro del proceso de trabajo de IIS (
w3wp.exe
), lo que se denomina modelo de hospedaje en proceso. - Reenviar solicitudes web a una aplicación ASP.NET Core de back-end que ejecuta el servidor de Kestrel, lo que se denomina modelo de hospedaje fuera de proceso.
Versiones de Windows compatibles:
- Windows 7 o posterior
- Windows Server 2012 R2 o versiones posteriores
En el caso del hospedaje en proceso, el módulo usa el servidor HTTP de IIS (IISHttpServer
), una implementación de servidor en proceso de IIS.
Cuando se hospeda fuera de proceso, el módulo solo funciona con Kestrel. El módulo no funciona con HTTP. sys.
Modelos de hospedaje
Modelo de hospedaje en proceso
Las aplicaciones ASP.NET Core usan de forma predeterminada el modelo de hospedaje dentro de proceso.
Al hospedar en proceso, se aplican las siguientes características:
Se usa el servidor HTTP de IIS (
IISHttpServer
) en lugar del servidor Kestrel. En el mismo proceso, CreateDefaultBuilder llama a UseIIS para:- Registrar el
IISHttpServer
. - Configurar el puerto y la ruta de acceso base donde debe escuchar el servidor al ejecutarse detrás del módulo de ASP.NET Core.
- Configurar el host para capturar errores de inicio.
- Registrar el
El atributo requestTimeout no se aplica al hospedaje en proceso.
No se admite el uso compartido de un grupo de aplicaciones entre aplicaciones. Se usa un grupo de aplicaciones por aplicación.
Cuando se usa Web Deploy o se coloca manualmente un archivo
app_offline.htm
en la implementación, puede que la aplicación no se apague inmediatamente si hay una conexión abierta. Por ejemplo, una conexión WebSocket puede retrasar el apagado de la aplicación.La arquitectura (valor de bits) de la aplicación y el runtime instalado (x64 o x86) deben coincidir con la arquitectura del grupo de aplicaciones.
Se detectan las desconexiones del cliente. El token de cancelación de
HttpContext.RequestAborted
se cancela cuando el cliente se desconecta.En ASP.NET Core 2.2.1 o versiones anteriores, GetCurrentDirectory devuelve el directorio de trabajo del proceso iniciado por IIS en lugar del de la aplicación (por ejemplo,
C:\Windows\System32\inetsrv
paraw3wp.exe
).Para conocer el código de ejemplo que establece el directorio actual de la aplicación, consulte la información sobre la clase
CurrentDirectoryHelpers
. Llame al métodoSetCurrentDirectory
. Las llamadas subsiguientes a GetCurrentDirectory proporcionan el directorio de la aplicación.Cuando se hospeda en el proceso, no se llama a AuthenticateAsync de forma interna para inicializar un usuario. Por tanto, se usa una implementación de IClaimsTransformation para transformar las notificaciones después de que cada autenticación no se active de forma predeterminada. Al transformar notificaciones con una implementación de IClaimsTransformation, llame a AddAuthentication para agregar servicios de autenticación:
public void ConfigureServices(IServiceCollection services) { services.AddTransient<IClaimsTransformation, ClaimsTransformer>(); services.AddAuthentication(IISServerDefaults.AuthenticationScheme); } public void Configure(IApplicationBuilder app) { app.UseAuthentication(); }
- No se admiten implementaciones de paquetes web (archivo único).
Modelo de hospedaje fuera de proceso
Para configurar una aplicación para un hospedaje fuera de proceso, establezca el valor de la propiedad <AspNetCoreHostingModel>
en OutOfProcess
en el archivo del proyecto ( .csproj
):
<PropertyGroup>
<AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>
El hospedaje en proceso se establece con InProcess
, que es el valor predeterminado.
El valor de <AspNetCoreHostingModel>
no distingue mayúsculas de minúsculas, por lo que inprocess
y outofprocess
son valores válidos.
En lugar del servidor Kestrel se usa el servidor HTTP de IIS (IISHttpServer
).
Fuera del proceso, CreateDefaultBuilder
llama a UseIISIntegration para:
- Configurar el puerto y la ruta de acceso base donde debe escuchar el servidor al ejecutarse detrás del módulo de ASP.NET Core.
- Configurar el host para capturar errores de inicio.
Cambios del modelo de hospedaje
Si se modifica el valor hostingModel
en el archivo web.config
(se explica en la sección Configuración con web.config
), el módulo recicla el proceso de trabajo de IIS.
En IIS Express, el módulo no recicla el proceso de trabajo, sino que desencadena un cierre estable del proceso de IIS Express actual. La siguiente solicitud a la aplicación genera un nuevo proceso de IIS Express.
Nombre del proceso
Process.GetCurrentProcess().ProcessName
informa a w3wp
/iisexpress
(en proceso) o dotnet
(fuera de proceso).
Muchos de los módulos nativos, como la autenticación de Windows, permanecen activos. Para obtener más información sobre los módulos de IIS activos con el módulo ASP.NET Core, vea Módulos de IIS con ASP.NET Core.
El módulo ASP.NET Core también puede:
- Establecer variables de entorno para un proceso de trabajo.
- Registrar la salida en un almacenamiento de archivos para solucionar problemas de inicio.
- Reenviar tokens de autenticación de Windows.
Instalación y uso del módulo de ASP.NET Core (ANCM)
Para obtener instrucciones sobre cómo instalar y usar el módulo ASP.NET Core, consulte Instalación del conjunto de hospedaje de .NET Core. El módulo ASP.NET Core es compatible con versiones anteriores y posteriores de las versiones con soporte técnico de .NET.
Los cambios importantes y los avisos de seguridad se notifican en el repositorio de anuncios. Los anuncios se pueden limitar a una versión específica seleccionando un filtro de etiqueta.
Configuración 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 Hospedaje de ASP.NET Core en Windows con IIS.
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 |
true |
hostingModel |
Atributo de cadena opcional. Especifica el modelo de hospedaje como en proceso ( |
InProcess inprocess |
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 No se recomienda establecer |
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 |
|
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 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 |
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 |
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.
app_offline.htm
Si un archivo con el nombre app_offline.htm
se detecta en el directorio raíz de una aplicación, el módulo ASP.NET Core intenta cerrar correctamente la aplicación y deja de procesar las solicitudes entrantes. Si la aplicación se sigue ejecutando después del número definido en shutdownTimeLimit
, el módulo ASP.NET Core termina el proceso en ejecución.
Mientras el archivo app_offline.htm
existe, el módulo ASP.NET Core responde a solicitudes con la devolución del contenido del archivo app_offline.htm
. Cuando se quita el archivo app_offline.htm
, la solicitud siguiente inicia la aplicación.
Al usar el modelo de hospedaje fuera de proceso, puede que la aplicación no se apague inmediatamente si hay una conexión abierta. Por ejemplo, una conexión WebSocket puede retrasar el apagado de la aplicación.
Página de errores de inicio
Tanto el hospedaje en proceso como el hospedaje fuera de proceso generan páginas de error personalizado cuando se produce un error al iniciar la aplicación.
Si el módulo ASP.NET Core no logra encontrar el controlador de solicitudes en proceso o fuera de proceso, aparecerá la página de código de estado 500.0 - Error de carga de controlador en proceso/fuera de proceso.
Para el hospedaje en proceso, si el módulo ASP.NET Core no logra iniciar la aplicación, aparecerá la página de código de estado 500.30 - Error de inicio.
En cuanto al hospedaje fuera de proceso, si el módulo ASP.NET Core no es capaz de iniciar el proceso de back-end o este se inicia pero no puede escuchar en el puerto configurado, aparecerá la página de código de estado 502.5 - Error de proceso.
Para suprimir esta página y volver a la página de código de estado 5xx de IIS predeterminada, use el atributo disableStartUpErrorPage
. Para más información sobre cómo configurar mensajes de error personalizados, consulte Errores HTTP<httpErrors>
.
Creación y redireccionamiento de registros
El módulo ASP.NET Core redirige los resultados de consola stdout y stderr al disco si se establecen los atributos stdoutLogEnabled
y stdoutLogFile
del elemento aspNetCore
. Al crearse el archivo de registro, el módulo crea las carpetas de la ruta de acceso de stdoutLogFile
. El grupo de aplicaciones debe tener acceso de escritura a la ubicación en la que se escriben los registros (use IIS AppPool\<app_pool_name>
para proporcionar permiso de escritura).
Los registros no se rotan, a no ser que se produzca un reinicio o reciclaje del proceso. Es responsabilidad del proveedor de servicios de hospedaje limitar el espacio en disco que consumen los registros.
Solo se recomienda usar el registro stdout para solucionar problemas de inicio de la aplicación al hospedar en IIS o al usar compatibilidad de IIS en tiempo de desarrollo para Visual Studio, no durante la depuración local y ejecución de la aplicación con IIS Express.
No use el registro de stdout con fines de registro de aplicaciones general. Para el registro rutinario en una aplicación ASP.NET Core, use una biblioteca de registro que limite el tamaño del archivo de registro y realice la rotación de los registros. Para más información, consulte los proveedores de registro de terceros.
Cuando se crea el archivo de registro, se agregan automáticamente una marca de tiempo y una extensión de archivo. El nombre del archivo de registro se forma mediante la anexión de la marca de tiempo, el identificador de proceso y la extensión de archivo ( .log
) al último segmento de la ruta de acceso stdoutLogFile
(normalmente stdout
) delimitados por caracteres de subrayado. Si la ruta de acceso de stdoutLogFile
finaliza con stdout
, el registro de una aplicación con un PID de 1934 creado el 5/2/2018 a las 19:42:32 tiene el nombre de archivo stdout_20180205194132_1934.log
.
Si stdoutLogEnabled
es falso, los errores que se produzcan al iniciar la aplicación se registrarán y se emitirán en el registro de eventos hasta un máximo de 30 KB. Después del inicio, se descartarán los registros adicionales.
En el siguiente elemento aspNetCore
de ejemplo se configura el registro de stdout en la ruta de acceso relativa .\log\
. Confirma que identity del usuario de AppPool tiene permiso para escribir en la ruta de acceso proporcionada.
<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="true"
stdoutLogFile=".\logs\stdout"
hostingModel="inprocess">
</aspNetCore>
Al publicar una aplicación para la implementación de Azure App Service, el SDK web establece el valor de stdoutLogFile
en \\?\%home%\LogFiles\stdout
. La variable de entorno %home
está predefinida para las aplicaciones hospedadas por Azure App Service.
Para crear reglas de filtro de registro, vea la sección Aplicación de reglas de filtro de registro en el código de la documentación sobre el registro en ASP.NET Core.
Para más información sobre los formatos de ruta de acceso, vea Formatos de ruta de acceso de archivo en los sistemas Windows.
Registros de diagnóstico mejorados
El módulo ASP.NET Core es configurable para proporcionar registros de diagnóstico mejorados. Agregue el elemento <handlerSettings>
al elemento <aspNetCore>
en web.config
. Al establecer debugLevel
en TRACE
se expone una fidelidad mayor de información de diagnóstico:
<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile="\\?\%home%\LogFiles\stdout"
hostingModel="inprocess">
<handlerSettings>
<handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
<handlerSetting name="debugLevel" value="FILE,TRACE" />
</handlerSettings>
</aspNetCore>
Al crearse el archivo de registro, el módulo crea las carpetas de la ruta de acceso (logs
en el ejemplo anterior). El grupo de aplicaciones debe tener acceso de escritura a la ubicación en la que se escriben los registros (use IIS AppPool\{APP POOL NAME}
, donde el marcador de posición {APP POOL NAME}
es el nombre del grupo de aplicaciones, para proporcionar permiso de escritura).
Los valores de nivel de depuración (debugLevel
) pueden incluir el nivel y la ubicación.
Niveles (en orden de menos a más detallado):
- ERROR
- WARNING
- INFO
- TRACE
Ubicaciones (se permiten varias ubicaciones):
- CONSOLE
- EVENTLOG
- ARCHIVO
También se puede proporcionar la configuración de controlador a través de variables de entorno:
ASPNETCORE_MODULE_DEBUG_FILE
: ruta de acceso al archivo de registro de depuración. (Valor predeterminado:aspnetcore-debug.log
)ASPNETCORE_MODULE_DEBUG
: valor de nivel de depuración.
Advertencia
No deje habilitado el registro de depuración más tiempo del necesario en la implementación para solucionar un problema. El tamaño del registro no es limitado. Dejar habilitado el registro de depuración puede agotar el espacio disponible en disco y bloquear el servidor o el servicio de aplicación.
Consulte Configuración con web.config para ver un ejemplo del elemento aspNetCore
en el archivo web.config
.
Modificación del tamaño de la pila
Solo se aplica cuando se usa el modelo de hospedaje dentro de proceso.
Configure el tamaño de la pila administrada mediante el valor stackSize
en bytes en web.config
. El tamaño predeterminado es de 1 048 576 bytes (1 MB).
<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile="\\?\%home%\LogFiles\stdout"
hostingModel="inprocess">
<handlerSettings>
<handlerSetting name="stackSize" value="2097152" />
</handlerSettings>
</aspNetCore>
La configuración de proxy usa el protocolo HTTP y un token de emparejamiento
Solo se aplica al hospedaje fuera de proceso.
El proxy creado entre el módulo ASP.NET Core y Kestrel usa el protocolo HTTP. No hay ningún riesgo de interceptación del tráfico entre el módulo y Kestrel desde una ubicación fuera del servidor.
Un token de emparejamiento sirve para garantizar que las solicitudes recibidas por Kestrel se redirigieron mediante proxy por IIS y no procedieron de otra fuente. El módulo crea el token de emparejamiento y lo establece en una variable de entorno (ASPNETCORE_TOKEN
). El token de emparejamiento también se establece en un encabezado (MS-ASPNETCORE-TOKEN
) en cada solicitud redirigida mediante proxy. El middleware de IIS comprueba cada solicitud recibida para confirmar que el valor del encabezado del token de emparejamiento coincida con el valor de la variable de entorno. Si los valores del token no coinciden, la solicitud se registra y se rechaza. No se puede acceder a la variable de entorno del token de emparejamiento y al tráfico entre el módulo y Kestrel desde una ubicación fuera del servidor. Sin conocer el valor del token de emparejamiento, un ciberdelincuente no puede enviar solicitudes que omitan la comprobación en el middleware de IIS.
El módulo ASP.NET Core con una configuración compartida de IIS
El instalador del módulo ASP.NET Core se ejecuta con los privilegios de la cuenta TrustedInstaller. Como la cuenta local del sistema no tiene permiso de modificación en la ruta de acceso de recurso compartido que se usa en la configuración compartida de IIS, el instalador inicia un error de acceso denegado al intentar configurar los valores del módulo en el archivo applicationHost.config
del recurso compartido.
Cuando se usa una configuración compartida de IIS en el mismo equipo que la instalación de IIS, ejecute el instalador del lote de hospedaje de ASP.NET Core con el parámetro OPT_NO_SHARED_CONFIG_CHECK
establecido en 1
:
dotnet-hosting-{VERSION}.exe OPT_NO_SHARED_CONFIG_CHECK=1
Cuando la ruta de acceso a la configuración compartida no se encuentra en el mismo equipo que la instalación de IIS, siga estos pasos:
- Deshabilite la configuración compartida de IIS.
- Ejecute el instalador.
- Exporte el archivo
applicationHost.config
actualizado al recurso compartido. - Vuelva a habilitar la configuración compartida de IIS.
Versión del módulo y registros del instalador de la agrupación de hospedaje
Para determinar la versión instalada del módulo ASP.NET Core, siga estos pasos:
- En el sistema de hospedaje, vaya a
%windir%\System32\inetsrv
. - Busque el archivo
aspnetcore.dll
. - Haga clic con el botón derecho en el archivo y seleccione Propiedades en el menú contextual.
- Seleccione la pestaña Detalles. La versión del archivo y la versión del producto representan la versión instalada del módulo.
Los registros del instalador del conjunto de hospedaje para el módulo se encuentran en C:\Users\%UserName%\AppData\Local\Temp
. El archivo se denomina dd_DotNetCoreWinSvrHosting__{TIMESTAMP}_000_AspNetCoreModule_x64.log
.
Ubicaciones del módulo, el esquema y el archivo de configuración
Module
IIS (x86/amd64) :
%windir%\System32\inetsrv\aspnetcore.dll
%windir%\SysWOW64\inetsrv\aspnetcore.dll
%ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll
%ProgramFiles(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll
IIS Express (x86/amd64) :
%ProgramFiles%\IIS Express\aspnetcore.dll
%ProgramFiles(x86)%\IIS Express\aspnetcore.dll
%ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll
%ProgramFiles(x86)%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll
Schema
IIS
%windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml
%windir%\System32\inetsrv\config\schema\aspnetcore_schema_v2.xml
IIS Express
%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml
%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema_v2.xml
Configuración
IIS
%windir%\System32\inetsrv\config\applicationHost.config
IIS Express
Visual Studio:
{APPLICATION ROOT}\.vs\config\applicationHost.config
CLI de iisexpress.exe:
%USERPROFILE%\Documents\IISExpress\config\applicationhost.config
Los archivos se pueden encontrar mediante la búsqueda de aspnetcore
en el archivo applicationHost.config
.
El módulo ASP.NET Core (ANCM) es un módulo nativo de IIS que se conecta a la canalización de IIS para:
- Hospedar una aplicación ASP.NET Core dentro del proceso de trabajo de IIS (
w3wp.exe
), lo que se denomina modelo de hospedaje en proceso. - Reenviar solicitudes web a una aplicación ASP.NET Core de back-end que ejecuta el servidor de Kestrel, lo que se denomina modelo de hospedaje fuera de proceso.
Versiones de Windows compatibles:
- Windows 7 o posterior
- Windows Server 2008 R2 o posterior
En el caso del hospedaje en proceso, el módulo usa el servidor HTTP de IIS (IISHttpServer
), una implementación de servidor en proceso de IIS.
Cuando se hospeda fuera de proceso, el módulo solo funciona con Kestrel. El módulo no funciona con HTTP. sys.
Modelos de hospedaje
Modelo de hospedaje en proceso
Para configurar una aplicación para el hospedaje en proceso, agregue la propiedad <AspNetCoreHostingModel>
al archivo de proyecto de la aplicación con un valor de InProcess
(el hospedaje fuera de proceso se establece con OutOfProcess
):
<PropertyGroup>
<AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
</PropertyGroup>
No se admite el modelo de hospedaje en proceso para aplicaciones de ASP.NET Core que tienen como destino .NET Framework.
El valor de <AspNetCoreHostingModel>
no distingue mayúsculas de minúsculas, por lo que inprocess
y outofprocess
son valores válidos.
Si la propiedad <AspNetCoreHostingModel>
no está presente en el archivo, el valor predeterminado es OutOfProcess
.
Al hospedar en proceso, se aplican las siguientes características:
Se usa el servidor HTTP de IIS (
IISHttpServer
) en lugar del servidor Kestrel. En el mismo proceso, CreateDefaultBuilder llama a UseIIS para:- Registrar el
IISHttpServer
. - Configurar el puerto y la ruta de acceso base donde debe escuchar el servidor al ejecutarse detrás del módulo de ASP.NET Core.
- Configurar el host para capturar errores de inicio.
- Registrar el
El atributo requestTimeout no se aplica al hospedaje en proceso.
No se admite el uso compartido de un grupo de aplicaciones entre aplicaciones. Se usa un grupo de aplicaciones por aplicación.
Cuando se usa Web Deploy o se coloca manualmente un archivo app_offline.htm en la implementación, puede que la aplicación no se apague inmediatamente si hay una conexión abierta. Por ejemplo, una conexión WebSocket puede retrasar el apagado de la aplicación.
La arquitectura (valor de bits) de la aplicación y el runtime instalado (x64 o x86) deben coincidir con la arquitectura del grupo de aplicaciones.
Se detectan las desconexiones del cliente. El token de cancelación HttpContext.RequestAborted se cancela cuando el cliente se desconecta.
En ASP.NET Core 2.2.1 o versiones anteriores, GetCurrentDirectory devuelve el directorio de trabajo del proceso iniciado por IIS en lugar del de la aplicación (por ejemplo, C:\Windows\System32\inetsrv para w3wp.exe).
Para conocer el código de ejemplo que establece el directorio actual de la aplicación, consulte la información sobre la clase CurrentDirectoryHelpers. Llame al método
SetCurrentDirectory
. Las llamadas subsiguientes a GetCurrentDirectory proporcionan el directorio de la aplicación.Cuando se hospeda en el proceso, no se llama a AuthenticateAsync de forma interna para inicializar un usuario. Por tanto, se usa una implementación de IClaimsTransformation para transformar las notificaciones después de que cada autenticación no se active de forma predeterminada. Al transformar notificaciones con una implementación de IClaimsTransformation, llame a AddAuthentication para agregar servicios de autenticación:
public void ConfigureServices(IServiceCollection services) { services.AddTransient<IClaimsTransformation, ClaimsTransformer>(); services.AddAuthentication(IISServerDefaults.AuthenticationScheme); } public void Configure(IApplicationBuilder app) { app.UseAuthentication(); }
Modelo de hospedaje fuera de proceso
Para configurar una aplicación para el hospedaje fuera de proceso, use uno de los métodos siguientes en el archivo de proyecto:
- No especifique la propiedad
<AspNetCoreHostingModel>
. Si la propiedad<AspNetCoreHostingModel>
no está presente en el archivo, el valor predeterminado esOutOfProcess
. - Establezca el valor de la propiedad
<AspNetCoreHostingModel>
enOutOfProcess
(el hospedaje en proceso se establece conInProcess
):
<PropertyGroup>
<AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>
El valor no distingue mayúsculas de minúsculas, por lo que inprocess
y outofprocess
son valores válidos.
En lugar del servidor Kestrel se usa el servidor HTTP de IIS (IISHttpServer
).
Fuera del proceso, CreateDefaultBuilder llama a UseIISIntegration para:
- Configurar el puerto y la ruta de acceso base donde debe escuchar el servidor al ejecutarse detrás del módulo de ASP.NET Core.
- Configurar el host para capturar errores de inicio.
Cambios del modelo de hospedaje
Si se modifica el valor hostingModel
en el archivo web.config (se explica en la sección Configuración con web.config), el módulo recicla el proceso de trabajo de IIS.
En IIS Express, el módulo no recicla el proceso de trabajo, sino que desencadena un cierre estable del proceso de IIS Express actual. La siguiente solicitud a la aplicación genera un nuevo proceso de IIS Express.
Nombre del proceso
Process.GetCurrentProcess().ProcessName
informa a w3wp
/iisexpress
(en proceso) o dotnet
(fuera de proceso).
Muchos de los módulos nativos, como la autenticación de Windows, permanecen activos. Para obtener más información sobre los módulos de IIS activos con el módulo ASP.NET Core, vea Módulos de IIS con ASP.NET Core.
El módulo ASP.NET Core también puede:
- Establecer variables de entorno para un proceso de trabajo.
- Registrar la salida en un almacenamiento de archivos para solucionar problemas de inicio.
- Reenviar tokens de autenticación de Windows.
Instalación y uso del módulo de ASP.NET Core (ANCM)
Para obtener instrucciones sobre cómo instalar y usar el módulo ASP.NET Core, consulte Instalación del conjunto de hospedaje de .NET Core. El módulo ASP.NET Core es compatible con versiones anteriores y posteriores de las versiones con soporte técnico de .NET.
Los cambios importantes y los avisos de seguridad se notifican en el repositorio de anuncios. Los anuncios se pueden limitar a una versión específica seleccionando un filtro de etiqueta.
Configuración 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 Hospedaje de ASP.NET Core en Windows con IIS.
Atributos del elemento aspNetCore
Atributo | Descripción | Default |
---|---|---|
arguments |
Atributo de cadena opcional. Argumentos para el archivo ejecutable especificado en |
|
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 ( |
OutOfProcess outofprocess |
processesPerApplication |
Atributo integer opcional. Especifica el número de instancias del proceso especificado en el valor †En el hospedaje en proceso, el valor está limitado a No se recomienda establecer |
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 |
|
rapidFailsPerMinute |
Atributo integer opcional. Especifica el número de veces que el proceso indicado en 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 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 |
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 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 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 |
false |
stdoutLogFile |
Atributo de cadena opcional. Especifica la ruta de acceso relativa o absoluta para la que se registran |
aspnetcore-stdout |
Configuración 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. 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.
app_offline.htm
Si un archivo con el nombre app_offline.htm
se detecta en el directorio raíz de una aplicación, el módulo ASP.NET Core intenta cerrar correctamente la aplicación y deja de procesar las solicitudes entrantes. Si la aplicación se sigue ejecutando después del número definido en shutdownTimeLimit
, el módulo ASP.NET Core termina el proceso en ejecución.
Mientras el archivo app_offline.htm
existe, el módulo ASP.NET Core responde a solicitudes con la devolución del contenido del archivo app_offline.htm
. Cuando se quita el archivo app_offline.htm
, la solicitud siguiente inicia la aplicación.
Al usar el modelo de hospedaje fuera de proceso, puede que la aplicación no se apague inmediatamente si hay una conexión abierta. Por ejemplo, una conexión WebSocket puede retrasar el apagado de la aplicación.
Página de errores de inicio
Tanto el hospedaje en proceso como el hospedaje fuera de proceso generan páginas de error personalizado cuando se produce un error al iniciar la aplicación.
Si el módulo ASP.NET Core no logra encontrar el controlador de solicitudes en proceso o fuera de proceso, aparecerá la página de código de estado 500.0 - Error de carga de controlador en proceso/fuera de proceso.
Para el hospedaje en proceso, si el módulo ASP.NET Core no logra iniciar la aplicación, aparecerá la página de código de estado 500.30 - Error de inicio.
En cuanto al hospedaje fuera de proceso, si el módulo ASP.NET Core no es capaz de iniciar el proceso de back-end o este se inicia pero no puede escuchar en el puerto configurado, aparecerá la página de código de estado 502.5 - Error de proceso.
Para suprimir esta página y volver a la página de código de estado 5xx de IIS predeterminada, use el atributo disableStartUpErrorPage
. Para obtener más información sobre cómo configurar los mensajes de error personalizados, consulte Errores HTTP <httpErrors>.
Creación y redireccionamiento de registros
El módulo ASP.NET Core redirige los resultados de consola stdout y stderr al disco si se establecen los atributos stdoutLogEnabled
y stdoutLogFile
del elemento aspNetCore
. Al crearse el archivo de registro, el módulo crea las carpetas de la ruta de acceso de stdoutLogFile
. El grupo de aplicaciones debe tener acceso de escritura a la ubicación en la que se escriben los registros (use IIS AppPool\{APP POOL NAME}
para proporcionar permiso de escritura, donde el marcador de posición {APP POOL NAME}
es el nombre del grupo de aplicaciones).
Los registros no se rotan, a no ser que se produzca un reinicio o reciclaje del proceso. Es responsabilidad del proveedor de servicios de hospedaje limitar el espacio en disco que consumen los registros.
Solo se recomienda usar el registro stdout para solucionar problemas de inicio de la aplicación al hospedar en IIS o al usar compatibilidad de IIS en tiempo de desarrollo para Visual Studio, no durante la depuración local y ejecución de la aplicación con IIS Express.
No use el registro de stdout con fines de registro de aplicaciones general. Para el registro rutinario en una aplicación ASP.NET Core, use una biblioteca de registro que limite el tamaño del archivo de registro y realice la rotación de los registros. Para más información, consulte los proveedores de registro de terceros.
Cuando se crea el archivo de registro, se agregan automáticamente una marca de tiempo y una extensión de archivo. El nombre del archivo de registro se forma mediante la anexión de la marca de tiempo, el identificador de proceso y la extensión de archivo ( .log
) al último segmento de la ruta de acceso stdoutLogFile
(normalmente stdout
) delimitados por caracteres de subrayado. Si la ruta de acceso de stdoutLogFile
finaliza con stdout
, el registro de una aplicación con un PID de 1934 creado el 5/2/2018 a las 19:42:32 tiene el nombre de archivo stdout_20180205194132_1934.log
.
Si stdoutLogEnabled
es falso, los errores que se produzcan al iniciar la aplicación se registrarán y se emitirán en el registro de eventos hasta un máximo de 30 KB. Después del inicio, se descartarán los registros adicionales.
En el siguiente elemento aspNetCore
de ejemplo se configura el registro de stdout en la ruta de acceso relativa .\log\
. Confirma que identity del usuario del grupo de aplicaciones tiene permiso para escribir en la ruta de acceso proporcionada.
<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="true"
stdoutLogFile=".\logs\stdout"
hostingModel="inprocess">
</aspNetCore>
Al publicar una aplicación para la implementación de Azure App Service, el SDK web establece el valor de stdoutLogFile
en \\?\%home%\LogFiles\stdout
. La variable de entorno %home
está predefinida para las aplicaciones hospedadas por Azure App Service.
Para más información sobre los formatos de ruta de acceso, vea Formatos de ruta de acceso de archivo en los sistemas Windows.
Registros de diagnóstico mejorados
El módulo ASP.NET Core es configurable para proporcionar registros de diagnóstico mejorados. Agregue el elemento <handlerSettings>
al elemento <aspNetCore>
en web.config
. Al establecer debugLevel
en TRACE
se expone una fidelidad mayor de información de diagnóstico:
<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile="\\?\%home%\LogFiles\stdout"
hostingModel="inprocess">
<handlerSettings>
<handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
<handlerSetting name="debugLevel" value="FILE,TRACE" />
</handlerSettings>
</aspNetCore>
El módulo no crea automáticamente las carpetas de la ruta de acceso proporcionada al valor <handlerSetting>
(logs
en el ejemplo anterior), que deben existir previamente en la implementación. El grupo de aplicaciones debe tener acceso de escritura a la ubicación en la que se escriben los registros (use IIS AppPool\{APP POOL NAME}
para proporcionar permiso de escritura, donde el marcador de posición {APP POOL NAME}
es el nombre del grupo de aplicaciones).
Los valores de nivel de depuración (debugLevel
) pueden incluir el nivel y la ubicación.
Niveles (en orden de menos a más detallado):
- ERROR
- WARNING
- INFO
- TRACE
Ubicaciones (se permiten varias ubicaciones):
- CONSOLE
- EVENTLOG
- ARCHIVO
También se puede proporcionar la configuración de controlador a través de variables de entorno:
ASPNETCORE_MODULE_DEBUG_FILE
: ruta de acceso al archivo de registro de depuración. (Valor predeterminado:aspnetcore-debug.log
)ASPNETCORE_MODULE_DEBUG
: valor de nivel de depuración.
Advertencia
No deje habilitado el registro de depuración más tiempo del necesario en la implementación para solucionar un problema. El tamaño del registro no es limitado. Dejar habilitado el registro de depuración puede agotar el espacio disponible en disco y bloquear el servidor o el servicio de aplicación.
Consulte Configuración con web.config para ver un ejemplo del elemento aspNetCore
en el archivo web.config
.
La configuración de proxy usa el protocolo HTTP y un token de emparejamiento
Solo se aplica al hospedaje fuera de proceso.
El proxy creado entre el módulo ASP.NET Core y Kestrel usa el protocolo HTTP. No hay ningún riesgo de interceptación del tráfico entre el módulo y Kestrel desde una ubicación fuera del servidor.
Un token de emparejamiento sirve para garantizar que las solicitudes recibidas por Kestrel se redirigieron mediante proxy por IIS y no procedieron de otra fuente. El módulo crea el token de emparejamiento y lo establece en una variable de entorno (ASPNETCORE_TOKEN
). El token de emparejamiento también se establece en un encabezado (MS-ASPNETCORE-TOKEN
) en cada solicitud redirigida mediante proxy. El middleware de IIS comprueba cada solicitud recibida para confirmar que el valor del encabezado del token de emparejamiento coincida con el valor de la variable de entorno. Si los valores del token no coinciden, la solicitud se registra y se rechaza. No se puede acceder a la variable de entorno del token de emparejamiento y al tráfico entre el módulo y Kestrel desde una ubicación fuera del servidor. Sin conocer el valor del token de emparejamiento, un ciberdelincuente no puede enviar solicitudes que omitan la comprobación en el middleware de IIS.
El módulo ASP.NET Core con una configuración compartida de IIS
El instalador del módulo ASP.NET Core se ejecuta con los privilegios de la cuenta TrustedInstaller
. Como la cuenta local del sistema no tiene permiso de modificación en la ruta de acceso de recurso compartido que se usa en la configuración compartida de IIS, el instalador inicia un error de acceso denegado al intentar configurar los valores del módulo en el archivo applicationHost.config
del recurso compartido.
Cuando se usa una configuración compartida de IIS en el mismo equipo que la instalación de IIS, ejecute el instalador del lote de hospedaje de ASP.NET Core con el parámetro OPT_NO_SHARED_CONFIG_CHECK
establecido en 1
:
dotnet-hosting-{VERSION}.exe OPT_NO_SHARED_CONFIG_CHECK=1
Cuando la ruta de acceso a la configuración compartida no se encuentra en el mismo equipo que la instalación de IIS, siga estos pasos:
- Deshabilite la configuración compartida de IIS.
- Ejecute el instalador.
- Exporte el archivo
applicationHost.config
actualizado al recurso compartido. - Vuelva a habilitar la configuración compartida de IIS.
Versión del módulo y registros del instalador de la agrupación de hospedaje
Para determinar la versión instalada del módulo ASP.NET Core, siga estos pasos:
- En el sistema de hospedaje, vaya a
%windir%\System32\inetsrv
. - Busque el archivo
aspnetcore.dll
. - Haga clic con el botón derecho en el archivo y seleccione Propiedades en el menú contextual.
- Seleccione la pestaña Detalles. La versión del archivo y la versión del producto representan la versión instalada del módulo.
Los registros del instalador del conjunto de hospedaje para el módulo se encuentran en C:\\Users\\%UserName%\\AppData\\Local\\Temp
. El archivo se denomina dd_DotNetCoreWinSvrHosting__\{TIMESTAMP}_000_AspNetCoreModule_x64.log
, donde el marcador de posición {TIMESTAMP}
es la marca de tiempo.
Ubicaciones del módulo, el esquema y el archivo de configuración
Module
IIS (x86/amd64) :
%windir%\System32\inetsrv\aspnetcore.dll
%windir%\SysWOW64\inetsrv\aspnetcore.dll
%ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll
%ProgramFiles(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll
IIS Express (x86/amd64) :
%ProgramFiles%\IIS Express\aspnetcore.dll
%ProgramFiles(x86)%\IIS Express\aspnetcore.dll
%ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll
%ProgramFiles(x86)%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll
Schema
IIS
%windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml
%windir%\System32\inetsrv\config\schema\aspnetcore_schema_v2.xml
IIS Express
%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml
%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema_v2.xml
Configuración
IIS
%windir%\System32\inetsrv\config\applicationHost.config
IIS Express
Visual Studio:
{APPLICATION ROOT}\.vs\config\applicationHost.config
CLI de iisexpress.exe:
%USERPROFILE%\Documents\IISExpress\config\applicationhost.config
Los archivos se pueden encontrar mediante la búsqueda de aspnetcore
en el archivo applicationHost.config
.
El módulo ASP.NET Core (ANCM) es un módulo nativo de IIS que se conecta a la canalización de IIS para reenviar solicitudes web a aplicaciones ASP.NET Core de back-end.
Versiones de Windows compatibles:
- Windows 7 o posterior
- Windows Server 2008 R2 o posterior
El módulo solo funciona con Kestrel. El módulo no es compatible con HTTP.sys.
Dado que las aplicaciones ASP.NET Core se ejecutan en un proceso independiente del proceso de trabajo de IIS, el módulo también se encarga de la administración de procesos. El módulo inicia el proceso de la aplicación ASP.NET Core cuando entra la primera solicitud, y reinicia la aplicación si esta se bloquea. Este comportamiento es básicamente el mismo que el de las aplicaciones ASP.NET 4.x que se ejecutan en el proceso en IIS y se administran a través del Servicio de activación de procesos de Windows (WAS).
En el siguiente diagrama se muestra la relación entre IIS, el módulo ASP.NET Core y una aplicación:
Las solicitudes llegan procedentes de Internet al controlador HTTP.sys en modo kernel. El controlador enruta las solicitudes a IIS en el puerto configurado del sitio web, que suele ser el puerto 80 (HTTP) o 443 (HTTPS). El módulo reenvía las solicitudes a Kestrel en un puerto aleatorio de la aplicación, que no es ni 80 ni 443.
El módulo especifica el puerto a través de la variable de entorno en el inicio, y el middleware de integración de IIS configura el servidor para que escuche en http://localhost:{port}
. Se realizan más comprobaciones y se rechazan las solicitudes que no se hayan originado en el módulo. El módulo no admite el reenvío de HTTPS, por lo que las solicitudes se reenvían a través de HTTP, aunque IIS las reciba a través de HTTPS.
Una vez que Kestrel toma la solicitud del módulo, la envía a la canalización de middleware de ASP.NET Core. La canalización de middleware controla la solicitud y la pasa como una instancia de HttpContext
a la lógica de la aplicación. El middleware agregado por la integración de IIS actualiza el esquema, la dirección IP remota y PathBase para responder del reenvío de la solicitud a Kestrel. La respuesta de la aplicación se vuelve a pasar a IIS, que la envía de nuevo al cliente HTTP que inició la solicitud.
Muchos de los módulos nativos, como la autenticación de Windows, permanecen activos. Para obtener más información sobre los módulos de IIS activos con el módulo ASP.NET Core, vea Módulos de IIS con ASP.NET Core.
El módulo ASP.NET Core también puede:
- Establecer variables de entorno para un proceso de trabajo.
- Registrar la salida en un almacenamiento de archivos para solucionar problemas de inicio.
- Reenviar tokens de autenticación de Windows.
Instalación y uso del módulo de ASP.NET Core (ANCM)
Para obtener instrucciones sobre cómo instalar y usar el módulo ASP.NET Core, consulte Instalación del conjunto de hospedaje de .NET Core.
Configuración 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>
<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>
El siguiente archivo web.config se publica para una implementación independiente:
<?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>
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 Hospedaje de ASP.NET Core en Windows con IIS.
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 |
processesPerApplication |
Atributo integer opcional. Especifica el número de instancias del proceso especificado en el valor processPath que pueden rotarse por aplicación. No se recomienda establecer |
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 |
|
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. |
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 |
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 |
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. 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 |
aspnetcore-stdout |
Configuración 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>
.
Advertencia
Las variables de entorno establecidas en esta sección entran en conflicto con las variables de entorno del sistema que tienen el mismo nombre. Si se establece una variable de entorno en el archivo web.config y en el nivel del sistema en Windows, el valor del archivo web.config se anexa al valor de la variable de entorno del sistema (por ejemplo, ASPNETCORE_ENVIRONMENT: Development;Development
), que impide que se inicie la aplicación.
En el ejemplo siguiente se establecen dos variables de entorno. 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="\\?\%home%\LogFiles\stdout">
<environmentVariables>
<environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
<environmentVariable name="CONFIG_DIR" value="f:\application_config" />
</environmentVariables>
</aspNetCore>
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.
app_offline.htm
Si un archivo con el nombre app_offline.htm
se detecta en el directorio raíz de una aplicación, el módulo ASP.NET Core intenta cerrar correctamente la aplicación y deja de procesar las solicitudes entrantes. Si la aplicación se sigue ejecutando después del número definido en shutdownTimeLimit
, el módulo ASP.NET Core termina el proceso en ejecución.
Mientras el archivo app_offline.htm
existe, el módulo ASP.NET Core responde a solicitudes con la devolución del contenido del archivo app_offline.htm
. Cuando se quita el archivo app_offline.htm
, la solicitud siguiente inicia la aplicación.
Página de errores de inicio
Si el módulo ASP.NET Core no es capaz de iniciar el proceso de back-end o este se inicia pero no puede escuchar en el puerto configurado, aparece una página de código de estado 502.5 - Error de proceso. Para suprimir esta página y volver a la página de código de estado 502 de IIS predeterminada, use el atributo disableStartUpErrorPage
. Para obtener más información sobre cómo configurar los mensajes de error personalizados, consulte Errores HTTP <httpErrors>.
Creación y redireccionamiento de registros
El módulo ASP.NET Core redirige los resultados de consola stdout y stderr al disco si se establecen los atributos stdoutLogEnabled
y stdoutLogFile
del elemento aspNetCore
. Al crearse el archivo de registro, el módulo crea las carpetas de la ruta de acceso de stdoutLogFile
. El grupo de aplicaciones debe tener acceso de escritura a la ubicación en la que se escriben los registros (use IIS AppPool\<app_pool_name>
para proporcionar permiso de escritura).
Los registros no se rotan, a no ser que se produzca un reinicio o reciclaje del proceso. Es responsabilidad del proveedor de servicios de hospedaje limitar el espacio en disco que consumen los registros.
Solo se recomienda usar el registro stdout para solucionar problemas de inicio de la aplicación al hospedar en IIS o al usar compatibilidad de IIS en tiempo de desarrollo para Visual Studio, no durante la depuración local y ejecución de la aplicación con IIS Express.
No use el registro de stdout con fines de registro de aplicaciones general. Para el registro rutinario en una aplicación ASP.NET Core, use una biblioteca de registro que limite el tamaño del archivo de registro y realice la rotación de los registros. Para más información, consulte los proveedores de registro de terceros.
Cuando se crea el archivo de registro, se agregan automáticamente una marca de tiempo y una extensión de archivo. El nombre del archivo de registro se forma mediante la anexión de la marca de tiempo, el identificador de proceso y la extensión de archivo ( .log) al último segmento de la ruta de acceso stdoutLogFile
(normalmente stdout) delimitados por caracteres de subrayado. Si la ruta de acceso de stdoutLogFile
finaliza con stdout, el registro de una aplicación con un PID de 1934 creado el 5/2/2018 a las 19:42:32 tiene el nombre de archivo stdout_20180205194132_1934.log.
En el siguiente elemento aspNetCore
de ejemplo se configura el registro de stdout en la ruta de acceso relativa .\log\
. Confirma que identity del usuario de AppPool tiene permiso para escribir en la ruta de acceso proporcionada.
<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="true"
stdoutLogFile=".\logs\stdout">
</aspNetCore>
Al publicar una aplicación para la implementación de Azure App Service, el SDK web establece el valor de stdoutLogFile
en \\?\%home%\LogFiles\stdout
. La variable de entorno %home
está predefinida para las aplicaciones hospedadas por Azure App Service.
Para crear reglas de filtro de registro, vea la sección Aplicación de reglas de filtro de registro en el código de la documentación sobre el registro en ASP.NET Core.
Para más información sobre los formatos de ruta de acceso, vea Formatos de ruta de acceso de archivo en los sistemas Windows.
La configuración de proxy usa el protocolo HTTP y un token de emparejamiento
El proxy creado entre el módulo ASP.NET Core y Kestrel usa el protocolo HTTP. No hay ningún riesgo de interceptación del tráfico entre el módulo y Kestrel desde una ubicación fuera del servidor.
Un token de emparejamiento sirve para garantizar que las solicitudes recibidas por Kestrel se redirigieron mediante proxy por IIS y no procedieron de otra fuente. El módulo crea el token de emparejamiento y lo establece en una variable de entorno (ASPNETCORE_TOKEN
). El token de emparejamiento también se establece en un encabezado (MS-ASPNETCORE-TOKEN
) en cada solicitud redirigida mediante proxy. El middleware de IIS comprueba cada solicitud recibida para confirmar que el valor del encabezado del token de emparejamiento coincida con el valor de la variable de entorno. Si los valores del token no coinciden, la solicitud se registra y se rechaza. No se puede acceder a la variable de entorno del token de emparejamiento y al tráfico entre el módulo y Kestrel desde una ubicación fuera del servidor. Sin conocer el valor del token de emparejamiento, un ciberdelincuente no puede enviar solicitudes que omitan la comprobación en el middleware de IIS.
El módulo ASP.NET Core con una configuración compartida de IIS
El instalador del módulo ASP.NET Core se ejecuta con los privilegios de la cuenta TrustedInstaller. Como la cuenta local del sistema no tiene permiso de modificación en la ruta de acceso de recurso compartido que se usa en la configuración compartida de IIS, el instalador inicia un error de acceso denegado al intentar configurar los valores del módulo en el archivo applicationHost.config del recurso compartido.
Al usar una configuración compartida de IIS, siga estos pasos:
- Deshabilite la configuración compartida de IIS.
- Ejecute el instalador.
- Exporte el archivo applicationHost.config actualizado al recurso compartido.
- Vuelva a habilitar la configuración compartida de IIS.
Versión del módulo y registros del instalador de la agrupación de hospedaje
Para determinar la versión instalada del módulo ASP.NET Core, siga estos pasos:
- En el sistema de hospedaje, vaya a %windir%\System32\inetsrv.
- Busque el archivo aspnetcore.dll.
- Haga clic con el botón derecho en el archivo y seleccione Propiedades en el menú contextual.
- Seleccione la pestaña Detalles. La versión del archivo y la versión del producto representan la versión instalada del módulo.
Los registros del instalador del conjunto de hospedaje para el módulo se encuentran en C:\Users\%UserName%\AppData\Local\Temp. El archivo se denomina dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.
Ubicaciones del módulo, el esquema y el archivo de configuración
Module
IIS (x86/amd64):
%windir%\System32\inetsrv\aspnetcore.dll
%windir%\SysWOW64\inetsrv\aspnetcore.dll
IIS Express (x86/amd64):
%ProgramFiles%\IIS Express\aspnetcore.dll
%ProgramFiles(x86)%\IIS Express\aspnetcore.dll
Schema
IIS
- %windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml
IIS Express
- %ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml
Configuración
IIS
- %windir%\System32\inetsrv\config\applicationHost.config
IIS Express
Visual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.config
iisexpress.exe CLI: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config
Los archivos se pueden encontrar mediante la búsqueda de aspnetcore en el archivo applicationHost.config.
Recursos adicionales
- Hospedaje de ASP.NET Core en Windows con IIS
- Implementar aplicaciones de ASP.NET Core en Azure App Service
- Origen de referencia del módulo ASP.NET Core (rama predeterminada [main]): use la lista desplegable Rama para seleccionar una versión específica (por ejemplo,
release/3.1
). - Módulos de IIS con ASP.NET Core