Módulo ASP.NET CoreASP.NET Core Module

Por Tom Dykstra, Rick Strahl, Chris Ross, Rick Anderson, Sourabh Shirhatti y Justin KotalikBy Tom Dykstra, Rick Strahl, Chris Ross, Rick Anderson, Sourabh Shirhatti, and Justin Kotalik

El módulo ASP.NET Core es un módulo nativo de IIS que se conecta a la canalización de IIS para:The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to either:

Versiones de Windows compatibles:Supported Windows versions:

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

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

Cuando se hospeda fuera de proceso, el módulo solo funciona con Kestrel.When hosting out-of-process, the module only works with Kestrel. El módulo no funciona con HTTP. sys.The module doesn't function with HTTP.sys.

Modelos de hospedajeHosting models

Modelo de hospedaje en procesoIn-process hosting model

Las aplicaciones ASP.NET Core usan de forma predeterminada el modelo de hospedaje dentro de proceso.ASP.NET Core apps default to the in-process hosting model.

Al hospedar en proceso, se aplican las siguientes características:The following characteristics apply when hosting in-process:

  • En lugar del servidor HTTP de IIS (IISHttpServer) se usa el servidor Kestrel.IIS HTTP Server (IISHttpServer) is used instead of Kestrel server. En el mismo proceso, CreateDefaultBuilder llama a UseIIS para:For in-process, CreateDefaultBuilder calls UseIIS to:

    • Registrar el IISHttpServer.Register the 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.Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
    • Configurar el host para capturar errores de inicio.Configure the host to capture startup errors.
  • El atributo requestTimeout no se aplica al hospedaje en proceso.The requestTimeout attribute doesn't apply to in-process hosting.

  • No se admite el uso compartido de un grupo de aplicaciones entre aplicaciones.Sharing an app pool among apps isn't supported. Se usa un grupo de aplicaciones por aplicación.Use one app pool per app.

  • 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.When using Web Deploy or manually placing an app_offline.htm file in the deployment, the app might not shut down immediately if there's an open connection. Por ejemplo, una conexión WebSocket puede retrasar el apagado de la aplicación.For example, a websocket connection may delay app shut down.

  • 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.The architecture (bitness) of the app and installed runtime (x64 or x86) must match the architecture of the app pool.

  • Se detectan las desconexiones del cliente.Client disconnects are detected. El token de cancelación HttpContext.RequestAborted se cancela cuando el cliente se desconecta.The HttpContext.RequestAborted cancellation token is cancelled when the client disconnects.

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

    Para conocer el código de ejemplo que establece el directorio actual de la aplicación, consulte la información sobre la clase CurrentDirectoryHelpers.For sample code that sets the app's current directory, see the CurrentDirectoryHelpers class. Llame al método SetCurrentDirectory.Call the SetCurrentDirectory method. Las llamadas subsiguientes a GetCurrentDirectory proporcionan el directorio de la aplicación.Subsequent calls to GetCurrentDirectory provide the app's directory.

  • Cuando se hospeda en el proceso, no se llama a AuthenticateAsync de forma interna para inicializar un usuario.When hosting in-process, AuthenticateAsync isn't called internally to initialize a user. 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.Therefore, an IClaimsTransformation implementation used to transform claims after every authentication isn't activated by default. Al transformar notificaciones con una implementación de IClaimsTransformation, llame a AddAuthentication para agregar servicios de autenticación:When transforming claims with an IClaimsTransformation implementation, call AddAuthentication to add authentication services:

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
        services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
    }
    
    public void Configure(IApplicationBuilder app)
    {
        app.UseAuthentication();
    }
    

Modelo de hospedaje fuera de procesoOut-of-process hosting model

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):To configure an app for out-of-process hosting, set the value of the <AspNetCoreHostingModel> property to OutOfProcess in the project file (.csproj):

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

El hospedaje en proceso se establece con InProcess, que es el valor predeterminado.In-process hosting is set with InProcess, which is the default value.

El valor de <AspNetCoreHostingModel> no distingue mayúsculas de minúsculas, por lo que inprocess y outofprocess son valores válidos.The value of <AspNetCoreHostingModel> is case insensitive, so inprocess and outofprocess are valid values.

En lugar del servidor Kestrel se usa el servidor HTTP de IIS (IISHttpServer).Kestrel server is used instead of IIS HTTP Server (IISHttpServer).

Fuera del proceso, CreateDefaultBuilder llama a UseIISIntegration para:For out-of-process, CreateDefaultBuilder calls UseIISIntegration to:

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

Cambios del modelo de hospedajeHosting model changes

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.If the hostingModel setting is changed in the web.config file (explained in the Configuration with web.config section), the module recycles the worker process for IIS.

En IIS Express, el módulo no recicla el proceso de trabajo, sino que desencadena un cierre estable del proceso de IIS Express actual.For IIS Express, the module doesn't recycle the worker process but instead triggers a graceful shutdown of the current IIS Express process. La siguiente solicitud a la aplicación genera un nuevo proceso de IIS Express.The next request to the app spawns a new IIS Express process.

Nombre del procesoProcess name

Process.GetCurrentProcess().ProcessName informa a w3wp/iisexpress (en proceso) o dotnet (fuera de proceso).Process.GetCurrentProcess().ProcessName reports w3wp/iisexpress (in-process) or dotnet (out-of-process).

Muchos de los módulos nativos, como la autenticación de Windows, permanecen activos.Many native modules, such as Windows Authentication, remain active. 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.To learn more about IIS modules active with the ASP.NET Core Module, see Módulos de IIS con ASP.NET Core.

El módulo ASP.NET Core también puede:The ASP.NET Core Module can also:

  • Establecer variables de entorno para un proceso de trabajo.Set environment variables for the worker process.
  • Registrar la salida en un almacenamiento de archivos para solucionar problemas de inicio.Log stdout output to file storage for troubleshooting startup issues.
  • Reenviar tokens de autenticación de Windows.Forward Windows authentication tokens.

Cómo instalar y usar el módulo ASP.NET CoreHow to install and use the ASP.NET Core Module

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.For instructions on how to install the ASP.NET Core Module, see Install the .NET Core Hosting Bundle.

Configuración con web.configConfiguration with 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.The ASP.NET Core Module is configured with the aspNetCore section of the system.webServer node in the site's web.config file.

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

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

El siguiente archivo web.config se publica para una implementación independiente:The following web.config is published for a self-contained deployment:

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

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

Cuando se implementa una aplicación en Azure App Service, la ruta de acceso de stdoutLogFile se establece en \\?\%home%\LogFiles\stdout.When an app is deployed to Azure App Service, the stdoutLogFile path is set to \\?\%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.The path saves stdout logs to the LogFiles folder, which is a location automatically created by the service.

Para obtener información sobre la configuración de aplicaciones secundarias de IIS, consulte Hospedaje de ASP.NET Core en Windows con IIS.For information on IIS sub-application configuration, see Hospedaje de ASP.NET Core en Windows con IIS.

Atributos del elemento aspNetCoreAttributes of the aspNetCore element

AtributoAttribute DescripciónDescription DefaultDefault
arguments

Atributo de cadena opcional.Optional string attribute.

Argumentos para el archivo ejecutable especificado en processPath.Arguments to the executable specified in processPath.

disableStartUpErrorPage

Atributo Boolean opcional.Optional Boolean attribute.

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.If true, the 502.5 - Process Failure page is suppressed, and the 502 status code page configured in the web.config takes precedence.

false
forwardWindowsAuthToken

Atributo Boolean opcional.Optional Boolean attribute.

Si es true, el token se reenvía al proceso secundario que escucha en % ASPNETCORE_PORT % como un encabezado "MS-ASPNETCORE-WINAUTHTOKEN" por solicitud.If true, the token is forwarded to the child process listening on %ASPNETCORE_PORT% as a header 'MS-ASPNETCORE-WINAUTHTOKEN' per request. Es responsabilidad de dicho proceso llamar a CloseHandle en este token por solicitud.It's the responsibility of that process to call CloseHandle on this token per request.

true
hostingModel

Atributo de cadena opcional.Optional string attribute.

Especifica el modelo de hospedaje como en proceso (InProcess/inprocess) o fuera de proceso (OutOfProcess/outofprocess).Specifies the hosting model as in-process (InProcess/inprocess) or out-of-process (OutOfProcess/outofprocess).

InProcess
inprocess
processesPerApplication

Atributo integer opcional.Optional integer attribute.

Especifica el número de instancias del proceso especificado en el valor processPath que pueden rotarse por aplicación.Specifies the number of instances of the process specified in the processPath setting that can be spun up per app.

†En el hospedaje en proceso, el valor está limitado a 1.†For in-process hosting, the value is limited to 1.

No se recomienda establecer processesPerApplication.Setting processesPerApplication is discouraged. Este atributo se quitará en futuras versiones.This attribute will be removed in a future release.

Valor predeterminado: 1Default: 1
Mínimo: 1Min: 1
Máximo: 100Max: 100
processPath

Atributo de cadena necesario.Required string attribute.

Ruta de acceso al archivo ejecutable que inicia un proceso que escucha las solicitudes HTTP.Path to the executable that launches a process listening for HTTP requests. No se admiten rutas de acceso relativas.Relative paths are supported. Si la ruta de acceso comienza con ., se considera que es relativa a la raíz del sitio.If the path begins with ., the path is considered to be relative to the site root.

rapidFailsPerMinute

Atributo integer opcional.Optional integer attribute.

Especifica el número de veces que el proceso indicado en processPath puede bloquearse por minuto.Specifies the number of times the process specified in processPath is allowed to crash per minute. Si se supera este límite, el módulo deja de iniciar el proceso durante lo que resta del minuto.If this limit is exceeded, the module stops launching the process for the remainder of the minute.

No admitido con el hospedaje en proceso.Not supported with in-process hosting.

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

Atributo timespan opcional.Optional timespan attribute.

Especifica el tiempo que el módulo ASP.NET Core espera una respuesta del proceso que escucha en % ASPNETCORE_PORT %.Specifies the duration for which the ASP.NET Core Module waits for a response from the process listening on %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.In versions of the ASP.NET Core Module that shipped with the release of ASP.NET Core 2.1 or later, the requestTimeout is specified in hours, minutes, and seconds.

No se aplica al hospedaje en proceso.Doesn't apply to in-process hosting. En el hospedaje en proceso, el módulo espera a que la aplicación procese la solicitud.For in-process hosting, the module waits for the app to process the request.

Los valores válidos para los segmentos de minutos y segundos de la cadena se encuentran en el rango 0-59.Valid values for minutes and seconds segments of the string are in the range 0-59. El uso de 60 en el valor de minutos o segundos da como resultado el error 500: Error interno del servidor.Use of 60 in the value for minutes or seconds results in a 500 - Internal Server Error.

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

Atributo integer opcional.Optional integer attribute.

Tiempo en segundos que el módulo espera a que se cierre correctamente el archivo ejecutable cuando se detecta el archivo app_offline.htm.Duration in seconds that the module waits for the executable to gracefully shutdown when the app_offline.htm file is detected.

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

Atributo integer opcional.Optional integer attribute.

Tiempo en segundos que espera el módulo a que el archivo ejecutable inicie u proceso que escucha en el puerto.Duration in seconds that the module waits for the executable to start a process listening on the port. Si se supera este límite de tiempo, el módulo termina el proceso.If this time limit is exceeded, the module kills the process. 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.The module attempts to relaunch the process when it receives a new request and continues to attempt to restart the process on subsequent incoming requests unless the app fails to start rapidFailsPerMinute number of times in the last rolling minute.

Un valor de 0 (cero) no se considera un tiempo de expiración infinito.A value of 0 (zero) is not considered an infinite timeout.

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

Atributo Boolean opcional.Optional Boolean attribute.

Si es true, stdout y stderr en el proceso especificado en processPath se redirigen al archivo especificado en stdoutLogFile.If true, stdout and stderr for the process specified in processPath are redirected to the file specified in stdoutLogFile.

false
stdoutLogFile

Atributo de cadena opcional.Optional string attribute.

Especifica la ruta de acceso relativa o absoluta para la que se registran stdout y stderr desde el proceso especificado en processPath.Specifies the relative or absolute file path for which stdout and stderr from the process specified in processPath are logged. Las rutas de acceso relativas son relativas a la raíz del sitio.Relative paths are relative to the root of the site. 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.Any path starting with . are relative to the site root and all other paths are treated as absolute paths. Al crearse el archivo de registro, el módulo crea las carpetas que se proporcionan en la ruta de acceso.Any folders provided in the path are created by the module when the log file is created. 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.Using underscore delimiters, a timestamp, process ID, and file extension (.log) are added to the last segment of the stdoutLogFile path. Si .\logs\stdout se proporciona como valor, se guarda un registro de ejemplo de stdout como stdout_20180205194132_1934.log en la carpeta logs, cuando se guarda el 5/2/2018 a las 19:41:32 con un identificador de proceso de 1934.If .\logs\stdout is supplied as a value, an example stdout log is saved as stdout_20180205194132_1934.log in the logs folder when saved on 2/5/2018 at 19:41:32 with a process ID of 1934.

aspnetcore-stdout

Establecimiento de las variables de entornoSet environment variables

Se pueden especificar variables de entorno para el proceso en el atributo processPath.Environment variables can be specified for the process in the processPath attribute. Especifique una variable de entorno con el elemento secundario <environmentVariable> de un elemento de la colección <environmentVariables>.Specify an environment variable with the <environmentVariable> child element of an <environmentVariables> collection element. Las variables de entorno establecidas en esta sección tienen prioridad sobre las variables del entorno del sistema.Environment variables set in this section take precedence over system environment variables.

El ejemplo siguiente establece dos variables de entorno en web.config. ASPNETCORE_ENVIRONMENT configura el entorno de la aplicación en Development.The following example sets two environment variables in web.config. ASPNETCORE_ENVIRONMENT configures the app's environment to 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.A developer may temporarily set this value in the web.config file in order to force the Developer Exception Page to load when debugging an app exception. CONFIG_DIR 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.CONFIG_DIR is an example of a user-defined environment variable, where the developer has written code that reads the value on startup to form a path for loading the app's configuration file.

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile=".\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.An alternative to setting the environment directly in web.config is to include the <EnvironmentName> property in the publish profile (.pubxml) or project file. Este método establece el entorno en web.config cuando se publica el proyecto:This approach sets the environment in web.config when the project is published:

<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.Only set the ASPNETCORE_ENVIRONMENT environment variable to Development on staging and testing servers that aren't accessible to untrusted networks, such as the Internet.

app_offline.htmapp_offline.htm

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

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.While the app_offline.htm file is present, the ASP.NET Core Module responds to requests by sending back the contents of the app_offline.htm file. Cuando se quita el archivo app_offline.htm, la solicitud siguiente inicia la aplicación.When the app_offline.htm file is removed, the next request starts the app.

Al usar el modelo de hospedaje fuera de proceso, puede que la aplicación no se apague inmediatamente si hay una conexión abierta.When using the out-of-process hosting model, the app might not shut down immediately if there's an open connection. Por ejemplo, una conexión WebSocket puede retrasar el apagado de la aplicación.For example, a websocket connection may delay app shut down.

Página de errores de inicioStart-up error page

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.Both in-process and out-of-process hosting produce custom error pages when they fail to start the app.

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

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

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

Para suprimir esta página y volver a la página de código de estado 5xx de IIS predeterminada, use el atributo disableStartUpErrorPage.To suppress this page and revert to the default IIS 5xx status code page, use the disableStartUpErrorPage attribute. Para obtener más información sobre cómo configurar los mensajes de error personalizados, consulte Errores HTTP <httpErrors>.For more information on configuring custom error messages, see HTTP Errors <httpErrors>.

Creación y redireccionamiento de registrosLog creation and redirection

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.The ASP.NET Core Module redirects stdout and stderr console output to disk if the stdoutLogEnabled and stdoutLogFile attributes of the aspNetCore element are set. Al crearse el archivo de registro, el módulo crea las carpetas de la ruta de acceso de stdoutLogFile.Any folders in the stdoutLogFile path are created by the module when the log file is created. 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).The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

Los registros no se rotan, a no ser que se produzca un reinicio o reciclaje del proceso.Logs aren't rotated, unless process recycling/restart occurs. Es responsabilidad del proveedor de servicios de hospedaje limitar el espacio en disco que consumen los registros.It's the responsibility of the hoster to limit the disk space the logs consume.

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.Using the stdout log is only recommended for troubleshooting app startup issues when hosting on IIS or when using development-time support for IIS with Visual Studio, not while debugging locally and running the app with IIS Express.

No use el registro de stdout con fines de registro de aplicaciones general.Don't use the stdout log for general app logging purposes. 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.For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. Para más información, consulte los proveedores de registro de terceros.For more information, see third-party logging providers.

Cuando se crea el archivo de registro, se agregan automáticamente una marca de tiempo y una extensión de archivo.A timestamp and file extension are added automatically when the log file is created. 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.The log file name is composed by appending the timestamp, process ID, and file extension (.log) to the last segment of the stdoutLogFile path (typically stdout) delimited by underscores. 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.If the stdoutLogFile path ends with stdout, a log for an app with a PID of 1934 created on 2/5/2018 at 19:42:32 has the file name stdout_20180205194132_1934.log.

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.If stdoutLogEnabled is false, errors that occur on app startup are captured and emitted to the event log up to 30 KB. Después del inicio, se descartarán los registros adicionales.After startup, all additional logs are discarded.

En el siguiente elemento aspNetCore de ejemplo se configura el registro de stdout en la ruta de acceso relativa .\log\.The following sample aspNetCore element configures stdout logging at the relative path .\log\. Confirme que la identidad del usuario de AppPool tenga permiso para escribir en la ruta de acceso proporcionada.Confirm that the AppPool user identity has permission to write to the path provided.

<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.When publishing an app for Azure App Service deployment, the Web SDK sets the stdoutLogFile value to \\?\%home%\LogFiles\stdout. La variable de entorno %home está predefinida para las aplicaciones hospedadas por Azure App Service.The %home environment variable is predefined for apps hosted by Azure App Service.

Para crear reglas de filtro de registro, vea las secciones Configuración y Filtrado de registros de la documentación del registro en ASP.NET Core.To create logging filter rules, see the Configuration and Log filtering sections of the ASP.NET Core logging documentation.

Para más información sobre los formatos de ruta de acceso, vea Formatos de ruta de acceso de archivo en los sistemas Windows.For more information on path formats, see File path formats on Windows systems.

Registros de diagnóstico mejoradosEnhanced diagnostic logs

El módulo ASP.NET Core es configurable para proporcionar registros de diagnóstico mejorados.The ASP.NET Core Module is configurable to provide enhanced diagnostics logs. Agregue el elemento <handlerSettings> al elemento <aspNetCore> de web.config. Al establecer debugLevel en TRACE se expone una fidelidad mayor de información de diagnóstico:Add the <handlerSettings> element to the <aspNetCore> element in web.config. Setting the debugLevel to TRACE exposes a higher fidelity of diagnostic information:

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="false"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="inprocess">
  <handlerSettings>
    <handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
    <handlerSetting name="debugLevel" value="FILE,TRACE" />
  </handlerSettings>
</aspNetCore>

Al crearse el archivo de registro, el módulo crea las carpetas de la ruta de acceso (logs en el ejemplo anterior).Any folders in the path (logs in the preceding example) are created by the module when the log file is created. 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).The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

Los valores de nivel de depuración (debugLevel) pueden incluir el nivel y la ubicación.Debug level (debugLevel) values can include both the level and the location.

Niveles (en orden de menos a más detallado):Levels (in order from least to most verbose):

  • ERRORERROR
  • WARNINGWARNING
  • INFOINFO
  • TRACETRACE

Ubicaciones (se permiten varias ubicaciones):Locations (multiple locations are permitted):

  • CONSOLECONSOLE
  • EVENTLOGEVENTLOG
  • ARCHIVOFILE

También se puede proporcionar la configuración de controlador a través de variables de entorno:The handler settings can also be provided via environment variables:

  • ASPNETCORE_MODULE_DEBUG_FILE – Ruta de acceso al archivo de registro de depuración.ASPNETCORE_MODULE_DEBUG_FILE – Path to the debug log file. (El valor predeterminado es aspnetcore-debug.log)(Default: aspnetcore-debug.log)
  • ASPNETCORE_MODULE_DEBUG – Valor de nivel de depuración.ASPNETCORE_MODULE_DEBUG – Debug level setting.

Advertencia

No deje habilitado el registro de depuración más tiempo del necesario en la implementación para solucionar un problema.Do not leave debug logging enabled in the deployment for longer than required to troubleshoot an issue. El tamaño del registro no es limitado.The size of the log isn't limited. Dejar habilitado el registro de depuración puede agotar el espacio disponible en disco y bloquear el servidor o el servicio de aplicación.Leaving the debug log enabled can exhaust the available disk space and crash the server or app service.

Consulte Configuración con web.config para ver un ejemplo del elemento aspNetCore en el archivo web.config.See Configuration with web.config for an example of the aspNetCore element in the web.config file.

Modificación del tamaño de la pilaModify the stack size

Solo se aplica cuando se usa el modelo de hospedaje dentro de proceso.Only applies when using the in-process hosting model.

Configure el tamaño de la pila administrada mediante el valor stackSize en bytes en web.config. El tamaño predeterminado es 1048576 bytes (1 MB).Configure the managed stack size using the stackSize setting in bytes in web.config. The default size is 1048576 bytes (1 MB).

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="false"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="inprocess">
  <handlerSettings>
    <handlerSetting name="stackSize" value="2097152" />
  </handlerSettings>
</aspNetCore>

La configuración de proxy usa el protocolo HTTP y un token de emparejamientoProxy configuration uses HTTP protocol and a pairing token

Solo se aplica al hospedaje fuera de proceso.Only applies to out-of-process hosting.

El proxy creado entre el módulo ASP.NET Core y Kestrel usa el protocolo HTTP.The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. No hay ningún riesgo de interceptación del tráfico entre el módulo y Kestrel desde una ubicación fuera del servidor.There's no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server.

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.A pairing token is used to guarantee that the requests received by Kestrel were proxied by IIS and didn't come from some other source. El módulo crea el token de emparejamiento y lo establece en una variable de entorno (ASPNETCORE_TOKEN).The pairing token is created and set into an environment variable (ASPNETCORE_TOKEN) by the module. El token de emparejamiento también se establece en un encabezado (MS-ASPNETCORE-TOKEN) en cada solicitud redirigida mediante proxy.The pairing token is also set into a header (MS-ASPNETCORE-TOKEN) on every proxied request. 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.IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. Si los valores del token no coinciden, la solicitud se registra y se rechaza.If the token values are mismatched, the request is logged and rejected. 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.The pairing token environment variable and the traffic between the module and Kestrel aren't accessible from a location off of the server. Sin conocer el valor del token de emparejamiento, un atacante no puede enviar solicitudes que omitan la comprobación en el middleware de IIS.Without knowing the pairing token value, an attacker can't submit requests that bypass the check in the IIS Middleware.

El módulo ASP.NET Core con una configuración compartida de IISASP.NET Core Module with an IIS Shared Configuration

El instalador del módulo ASP.NET Core se ejecuta con los privilegios de la cuenta TrustedInstaller.The ASP.NET Core Module installer runs with the privileges of the TrustedInstaller account. 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.Because the local system account doesn't have modify permission for the share path used by the IIS Shared Configuration, the installer throws an access denied error when attempting to configure the module settings in the applicationHost.config file on the share.

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:When using an IIS Shared Configuration on the same machine as the IIS installation, run the ASP.NET Core Hosting Bundle installer with the OPT_NO_SHARED_CONFIG_CHECK parameter set to 1:

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

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:When the path to the shared configuration isn't on the same machine as the IIS installation, follow these steps:

  1. Deshabilite la configuración compartida de IIS.Disable the IIS Shared Configuration.
  2. Ejecute el instalador.Run the installer.
  3. Exporte el archivo applicationHost.config actualizado al recurso compartido.Export the updated applicationHost.config file to the share.
  4. Vuelva a habilitar la configuración compartida de IIS.Re-enable the IIS Shared Configuration.

Versión del módulo y registros del instalador de la agrupación de hospedajeModule version and Hosting Bundle installer logs

Para determinar la versión instalada del módulo ASP.NET Core, siga estos pasos:To determine the version of the installed ASP.NET Core Module:

  1. En el sistema de hospedaje, vaya a %windir%\System32\inetsrv.On the hosting system, navigate to %windir%\System32\inetsrv.
  2. Busque el archivo aspnetcore.dll.Locate the aspnetcore.dll file.
  3. Haga clic con el botón derecho en el archivo y seleccione Propiedades en el menú contextual.Right-click the file and select Properties from the contextual menu.
  4. Seleccione la pestaña Detalles. La versión del archivo y la versión del producto representan la versión instalada del módulo.Select the Details tab. The File version and Product version represent the installed version of the module.

Los registros del instalador de la agrupación de hospedaje del módulo se encuentran en C:\Users\%UserName%\AppData\Local\Temp. El archivo se llama dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.The Hosting Bundle installer logs for the module are found at C:\Users\%UserName%\AppData\Local\Temp. The file is named dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

Ubicaciones del módulo, el esquema y el archivo de configuraciónModule, schema, and configuration file locations

ModuleModule

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

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

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

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

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

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

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

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

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

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

SchemaSchema

IISIIS

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

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

IIS ExpressIIS Express

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

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

ConfiguraciónConfiguration

IISIIS

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

IIS ExpressIIS Express

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

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

Los archivos se pueden encontrar mediante la búsqueda de aspnetcore en el archivo applicationHost.config.The files can be found by searching for aspnetcore in the applicationHost.config file.

El módulo ASP.NET Core es un módulo nativo de IIS que se conecta a la canalización de IIS para:The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to either:

Versiones de Windows compatibles:Supported Windows versions:

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

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

Cuando se hospeda fuera de proceso, el módulo solo funciona con Kestrel.When hosting out-of-process, the module only works with Kestrel. El módulo no funciona con HTTP. sys.The module doesn't function with HTTP.sys.

Modelos de hospedajeHosting models

Modelo de hospedaje en procesoIn-process hosting model

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):To configure an app for in-process hosting, add the <AspNetCoreHostingModel> property to the app's project file with a value of InProcess (out-of-process hosting is set with OutOfProcess):

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

No se admite el modelo de hospedaje en proceso para aplicaciones de ASP.NET Core que tienen como destino .NET Framework.The in-process hosting model isn't supported for ASP.NET Core apps that target the .NET Framework.

El valor de <AspNetCoreHostingModel> no distingue mayúsculas de minúsculas, por lo que inprocess y outofprocess son valores válidos.The value of <AspNetCoreHostingModel> is case insensitive, so inprocess and outofprocess are valid values.

Si la propiedad <AspNetCoreHostingModel> no está presente en el archivo, el valor predeterminado es OutOfProcess.If the <AspNetCoreHostingModel> property isn't present in the file, the default value is OutOfProcess.

Al hospedar en proceso, se aplican las siguientes características:The following characteristics apply when hosting in-process:

  • En lugar del servidor HTTP de IIS (IISHttpServer) se usa el servidor Kestrel.IIS HTTP Server (IISHttpServer) is used instead of Kestrel server. En el mismo proceso, CreateDefaultBuilder llama a UseIIS para:For in-process, CreateDefaultBuilder calls UseIIS to:

    • Registrar el IISHttpServer.Register the 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.Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
    • Configurar el host para capturar errores de inicio.Configure the host to capture startup errors.
  • El atributo requestTimeout no se aplica al hospedaje en proceso.The requestTimeout attribute doesn't apply to in-process hosting.

  • No se admite el uso compartido de un grupo de aplicaciones entre aplicaciones.Sharing an app pool among apps isn't supported. Se usa un grupo de aplicaciones por aplicación.Use one app pool per app.

  • 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.When using Web Deploy or manually placing an app_offline.htm file in the deployment, the app might not shut down immediately if there's an open connection. Por ejemplo, una conexión WebSocket puede retrasar el apagado de la aplicación.For example, a websocket connection may delay app shut down.

  • 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.The architecture (bitness) of the app and installed runtime (x64 or x86) must match the architecture of the app pool.

  • Se detectan las desconexiones del cliente.Client disconnects are detected. El token de cancelación HttpContext.RequestAborted se cancela cuando el cliente se desconecta.The HttpContext.RequestAborted cancellation token is cancelled when the client disconnects.

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

    Para conocer el código de ejemplo que establece el directorio actual de la aplicación, consulte la información sobre la clase CurrentDirectoryHelpers.For sample code that sets the app's current directory, see the CurrentDirectoryHelpers class. Llame al método SetCurrentDirectory.Call the SetCurrentDirectory method. Las llamadas subsiguientes a GetCurrentDirectory proporcionan el directorio de la aplicación.Subsequent calls to GetCurrentDirectory provide the app's directory.

  • Cuando se hospeda en el proceso, no se llama a AuthenticateAsync de forma interna para inicializar un usuario.When hosting in-process, AuthenticateAsync isn't called internally to initialize a user. 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.Therefore, an IClaimsTransformation implementation used to transform claims after every authentication isn't activated by default. Al transformar notificaciones con una implementación de IClaimsTransformation, llame a AddAuthentication para agregar servicios de autenticación:When transforming claims with an IClaimsTransformation implementation, call AddAuthentication to add authentication services:

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
        services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
    }
    
    public void Configure(IApplicationBuilder app)
    {
        app.UseAuthentication();
    }
    

Modelo de hospedaje fuera de procesoOut-of-process hosting model

Para configurar una aplicación para el hospedaje fuera de proceso, use uno de los métodos siguientes en el archivo de proyecto:To configure an app for out-of-process hosting, use either of the following approaches in the project file:

  • No especifique la propiedad <AspNetCoreHostingModel>.Don't specify the <AspNetCoreHostingModel> property. Si la propiedad <AspNetCoreHostingModel> no está presente en el archivo, el valor predeterminado es OutOfProcess.If the <AspNetCoreHostingModel> property isn't present in the file, the default value is OutOfProcess.
  • Establezca el valor de la propiedad <AspNetCoreHostingModel> en OutOfProcess (el hospedaje en proceso se establece con InProcess):Set the value of the <AspNetCoreHostingModel> property to OutOfProcess (in-process hosting is set with InProcess):
<PropertyGroup>
  <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>

El valor no distingue mayúsculas de minúsculas, por lo que inprocess y outofprocess son valores válidos.The value is case insensitive, so inprocess and outofprocess are valid values.

En lugar del servidor Kestrel se usa el servidor HTTP de IIS (IISHttpServer).Kestrel server is used instead of IIS HTTP Server (IISHttpServer).

Fuera del proceso, CreateDefaultBuilder llama a UseIISIntegration para:For out-of-process, CreateDefaultBuilder calls UseIISIntegration to:

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

Cambios del modelo de hospedajeHosting model changes

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.If the hostingModel setting is changed in the web.config file (explained in the Configuration with web.config section), the module recycles the worker process for IIS.

En IIS Express, el módulo no recicla el proceso de trabajo, sino que desencadena un cierre estable del proceso de IIS Express actual.For IIS Express, the module doesn't recycle the worker process but instead triggers a graceful shutdown of the current IIS Express process. La siguiente solicitud a la aplicación genera un nuevo proceso de IIS Express.The next request to the app spawns a new IIS Express process.

Nombre del procesoProcess name

Process.GetCurrentProcess().ProcessName informa a w3wp/iisexpress (en proceso) o dotnet (fuera de proceso).Process.GetCurrentProcess().ProcessName reports w3wp/iisexpress (in-process) or dotnet (out-of-process).

Muchos de los módulos nativos, como la autenticación de Windows, permanecen activos.Many native modules, such as Windows Authentication, remain active. 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.To learn more about IIS modules active with the ASP.NET Core Module, see Módulos de IIS con ASP.NET Core.

El módulo ASP.NET Core también puede:The ASP.NET Core Module can also:

  • Establecer variables de entorno para un proceso de trabajo.Set environment variables for the worker process.
  • Registrar la salida en un almacenamiento de archivos para solucionar problemas de inicio.Log stdout output to file storage for troubleshooting startup issues.
  • Reenviar tokens de autenticación de Windows.Forward Windows authentication tokens.

Cómo instalar y usar el módulo ASP.NET CoreHow to install and use the ASP.NET Core Module

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.For instructions on how to install the ASP.NET Core Module, see Install the .NET Core Hosting Bundle.

Configuración con web.configConfiguration with 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.The ASP.NET Core Module is configured with the aspNetCore section of the system.webServer node in the site's web.config file.

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

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

El siguiente archivo web.config se publica para una implementación independiente:The following web.config is published for a self-contained deployment:

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

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

Cuando se implementa una aplicación en Azure App Service, la ruta de acceso de stdoutLogFile se establece en \\?\%home%\LogFiles\stdout.When an app is deployed to Azure App Service, the stdoutLogFile path is set to \\?\%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.The path saves stdout logs to the LogFiles folder, which is a location automatically created by the service.

Para obtener información sobre la configuración de aplicaciones secundarias de IIS, consulte Hospedaje de ASP.NET Core en Windows con IIS.For information on IIS sub-application configuration, see Hospedaje de ASP.NET Core en Windows con IIS.

Atributos del elemento aspNetCoreAttributes of the aspNetCore element

AtributoAttribute DescripciónDescription DefaultDefault
arguments

Atributo de cadena opcional.Optional string attribute.

Argumentos para el archivo ejecutable especificado en processPath.Arguments to the executable specified in processPath.

disableStartUpErrorPage

Atributo Boolean opcional.Optional Boolean attribute.

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.If true, the 502.5 - Process Failure page is suppressed, and the 502 status code page configured in the web.config takes precedence.

false
forwardWindowsAuthToken

Atributo Boolean opcional.Optional Boolean attribute.

Si es true, el token se reenvía al proceso secundario que escucha en % ASPNETCORE_PORT % como un encabezado "MS-ASPNETCORE-WINAUTHTOKEN" por solicitud.If true, the token is forwarded to the child process listening on %ASPNETCORE_PORT% as a header 'MS-ASPNETCORE-WINAUTHTOKEN' per request. Es responsabilidad de dicho proceso llamar a CloseHandle en este token por solicitud.It's the responsibility of that process to call CloseHandle on this token per request.

true
hostingModel

Atributo de cadena opcional.Optional string attribute.

Especifica el modelo de hospedaje como en proceso (InProcess/inprocess) o fuera de proceso (OutOfProcess/outofprocess).Specifies the hosting model as in-process (InProcess/inprocess) or out-of-process (OutOfProcess/outofprocess).

OutOfProcess
outofprocess
processesPerApplication

Atributo integer opcional.Optional integer attribute.

Especifica el número de instancias del proceso especificado en el valor processPath que pueden rotarse por aplicación.Specifies the number of instances of the process specified in the processPath setting that can be spun up per app.

†En el hospedaje en proceso, el valor está limitado a 1.†For in-process hosting, the value is limited to 1.

No se recomienda establecer processesPerApplication.Setting processesPerApplication is discouraged. Este atributo se quitará en futuras versiones.This attribute will be removed in a future release.

Valor predeterminado: 1Default: 1
Mínimo: 1Min: 1
Máximo: 100Max: 100
processPath

Atributo de cadena necesario.Required string attribute.

Ruta de acceso al archivo ejecutable que inicia un proceso que escucha las solicitudes HTTP.Path to the executable that launches a process listening for HTTP requests. No se admiten rutas de acceso relativas.Relative paths are supported. Si la ruta de acceso comienza con ., se considera que es relativa a la raíz del sitio.If the path begins with ., the path is considered to be relative to the site root.

rapidFailsPerMinute

Atributo integer opcional.Optional integer attribute.

Especifica el número de veces que el proceso indicado en processPath puede bloquearse por minuto.Specifies the number of times the process specified in processPath is allowed to crash per minute. Si se supera este límite, el módulo deja de iniciar el proceso durante lo que resta del minuto.If this limit is exceeded, the module stops launching the process for the remainder of the minute.

No admitido con el hospedaje en proceso.Not supported with in-process hosting.

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

Atributo timespan opcional.Optional timespan attribute.

Especifica el tiempo que el módulo ASP.NET Core espera una respuesta del proceso que escucha en % ASPNETCORE_PORT %.Specifies the duration for which the ASP.NET Core Module waits for a response from the process listening on %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.In versions of the ASP.NET Core Module that shipped with the release of ASP.NET Core 2.1 or later, the requestTimeout is specified in hours, minutes, and seconds.

No se aplica al hospedaje en proceso.Doesn't apply to in-process hosting. En el hospedaje en proceso, el módulo espera a que la aplicación procese la solicitud.For in-process hosting, the module waits for the app to process the request.

Los valores válidos para los segmentos de minutos y segundos de la cadena se encuentran en el rango 0-59.Valid values for minutes and seconds segments of the string are in the range 0-59. El uso de 60 en el valor de minutos o segundos da como resultado el error 500: Error interno del servidor.Use of 60 in the value for minutes or seconds results in a 500 - Internal Server Error.

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

Atributo integer opcional.Optional integer attribute.

Tiempo en segundos que el módulo espera a que se cierre correctamente el archivo ejecutable cuando se detecta el archivo app_offline.htm.Duration in seconds that the module waits for the executable to gracefully shutdown when the app_offline.htm file is detected.

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

Atributo integer opcional.Optional integer attribute.

Tiempo en segundos que espera el módulo a que el archivo ejecutable inicie u proceso que escucha en el puerto.Duration in seconds that the module waits for the executable to start a process listening on the port. Si se supera este límite de tiempo, el módulo termina el proceso.If this time limit is exceeded, the module kills the process. 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.The module attempts to relaunch the process when it receives a new request and continues to attempt to restart the process on subsequent incoming requests unless the app fails to start rapidFailsPerMinute number of times in the last rolling minute.

Un valor de 0 (cero) no se considera un tiempo de expiración infinito.A value of 0 (zero) is not considered an infinite timeout.

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

Atributo Boolean opcional.Optional Boolean attribute.

Si es true, stdout y stderr en el proceso especificado en processPath se redirigen al archivo especificado en stdoutLogFile.If true, stdout and stderr for the process specified in processPath are redirected to the file specified in stdoutLogFile.

false
stdoutLogFile

Atributo de cadena opcional.Optional string attribute.

Especifica la ruta de acceso relativa o absoluta para la que se registran stdout y stderr desde el proceso especificado en processPath.Specifies the relative or absolute file path for which stdout and stderr from the process specified in processPath are logged. Las rutas de acceso relativas son relativas a la raíz del sitio.Relative paths are relative to the root of the site. 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.Any path starting with . are relative to the site root and all other paths are treated as absolute paths. Al crearse el archivo de registro, el módulo crea las carpetas que se proporcionan en la ruta de acceso.Any folders provided in the path are created by the module when the log file is created. 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.Using underscore delimiters, a timestamp, process ID, and file extension (.log) are added to the last segment of the stdoutLogFile path. Si .\logs\stdout se proporciona como valor, se guarda un registro de ejemplo de stdout como stdout_20180205194132_1934.log en la carpeta logs, cuando se guarda el 5/2/2018 a las 19:41:32 con un identificador de proceso de 1934.If .\logs\stdout is supplied as a value, an example stdout log is saved as stdout_20180205194132_1934.log in the logs folder when saved on 2/5/2018 at 19:41:32 with a process ID of 1934.

aspnetcore-stdout

Configuración de las variables de entornoSetting environment variables

Se pueden especificar variables de entorno para el proceso en el atributo processPath.Environment variables can be specified for the process in the processPath attribute. Especifique una variable de entorno con el elemento secundario <environmentVariable> de un elemento de la colección <environmentVariables>.Specify an environment variable with the <environmentVariable> child element of an <environmentVariables> collection element. Las variables de entorno establecidas en esta sección tienen prioridad sobre las variables del entorno del sistema.Environment variables set in this section take precedence over system environment variables.

En el ejemplo siguiente se establecen dos variables de entorno.The following example sets two environment variables. ASPNETCORE_ENVIRONMENT configura el entorno de la aplicación como Development.ASPNETCORE_ENVIRONMENT configures the app's environment to 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.A developer may temporarily set this value in the web.config file in order to force the Developer Exception Page to load when debugging an app exception. CONFIG_DIR 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.CONFIG_DIR is an example of a user-defined environment variable, where the developer has written code that reads the value on startup to form a path for loading the app's configuration file.

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile=".\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.An alternative to setting the environment directly in web.config is to include the <EnvironmentName> property in the publish profile (.pubxml) or project file. Este método establece el entorno en web.config cuando se publica el proyecto:This approach sets the environment in web.config when the project is published:

<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.Only set the ASPNETCORE_ENVIRONMENT environment variable to Development on staging and testing servers that aren't accessible to untrusted networks, such as the Internet.

app_offline.htmapp_offline.htm

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

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.While the app_offline.htm file is present, the ASP.NET Core Module responds to requests by sending back the contents of the app_offline.htm file. Cuando se quita el archivo app_offline.htm, la solicitud siguiente inicia la aplicación.When the app_offline.htm file is removed, the next request starts the app.

Al usar el modelo de hospedaje fuera de proceso, puede que la aplicación no se apague inmediatamente si hay una conexión abierta.When using the out-of-process hosting model, the app might not shut down immediately if there's an open connection. Por ejemplo, una conexión WebSocket puede retrasar el apagado de la aplicación.For example, a websocket connection may delay app shut down.

Página de errores de inicioStart-up error page

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.Both in-process and out-of-process hosting produce custom error pages when they fail to start the app.

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

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

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

Para suprimir esta página y volver a la página de código de estado 5xx de IIS predeterminada, use el atributo disableStartUpErrorPage.To suppress this page and revert to the default IIS 5xx status code page, use the disableStartUpErrorPage attribute. Para obtener más información sobre cómo configurar los mensajes de error personalizados, consulte Errores HTTP <httpErrors>.For more information on configuring custom error messages, see HTTP Errors <httpErrors>.

Creación y redireccionamiento de registrosLog creation and redirection

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.The ASP.NET Core Module redirects stdout and stderr console output to disk if the stdoutLogEnabled and stdoutLogFile attributes of the aspNetCore element are set. Al crearse el archivo de registro, el módulo crea las carpetas de la ruta de acceso de stdoutLogFile.Any folders in the stdoutLogFile path are created by the module when the log file is created. 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).The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

Los registros no se rotan, a no ser que se produzca un reinicio o reciclaje del proceso.Logs aren't rotated, unless process recycling/restart occurs. Es responsabilidad del proveedor de servicios de hospedaje limitar el espacio en disco que consumen los registros.It's the responsibility of the hoster to limit the disk space the logs consume.

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.Using the stdout log is only recommended for troubleshooting app startup issues when hosting on IIS or when using development-time support for IIS with Visual Studio, not while debugging locally and running the app with IIS Express.

No use el registro de stdout con fines de registro de aplicaciones general.Don't use the stdout log for general app logging purposes. 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.For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. Para más información, consulte los proveedores de registro de terceros.For more information, see third-party logging providers.

Cuando se crea el archivo de registro, se agregan automáticamente una marca de tiempo y una extensión de archivo.A timestamp and file extension are added automatically when the log file is created. 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.The log file name is composed by appending the timestamp, process ID, and file extension (.log) to the last segment of the stdoutLogFile path (typically stdout) delimited by underscores. 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.If the stdoutLogFile path ends with stdout, a log for an app with a PID of 1934 created on 2/5/2018 at 19:42:32 has the file name stdout_20180205194132_1934.log.

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.If stdoutLogEnabled is false, errors that occur on app startup are captured and emitted to the event log up to 30 KB. Después del inicio, se descartarán los registros adicionales.After startup, all additional logs are discarded.

En el siguiente elemento aspNetCore de ejemplo se configura el registro de stdout en la ruta de acceso relativa .\log\.The following sample aspNetCore element configures stdout logging at the relative path .\log\. Confirme que la identidad del usuario de AppPool tenga permiso para escribir en la ruta de acceso proporcionada.Confirm that the AppPool user identity has permission to write to the path provided.

<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.When publishing an app for Azure App Service deployment, the Web SDK sets the stdoutLogFile value to \\?\%home%\LogFiles\stdout. La variable de entorno %home está predefinida para las aplicaciones hospedadas por Azure App Service.The %home environment variable is predefined for apps hosted by 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.For more information on path formats, see File path formats on Windows systems.

Registros de diagnóstico mejoradosEnhanced diagnostic logs

El módulo ASP.NET Core es configurable para proporcionar registros de diagnóstico mejorados.The ASP.NET Core Module is configurable to provide enhanced diagnostics logs. Agregue el elemento <handlerSettings> al elemento <aspNetCore> de web.config. Al establecer debugLevel en TRACE se expone una fidelidad mayor de información de diagnóstico:Add the <handlerSettings> element to the <aspNetCore> element in web.config. Setting the debugLevel to TRACE exposes a higher fidelity of diagnostic information:

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="false"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="inprocess">
  <handlerSettings>
    <handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
    <handlerSetting name="debugLevel" value="FILE,TRACE" />
  </handlerSettings>
</aspNetCore>

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

Los valores de nivel de depuración (debugLevel) pueden incluir el nivel y la ubicación.Debug level (debugLevel) values can include both the level and the location.

Niveles (en orden de menos a más detallado):Levels (in order from least to most verbose):

  • ERRORERROR
  • WARNINGWARNING
  • INFOINFO
  • TRACETRACE

Ubicaciones (se permiten varias ubicaciones):Locations (multiple locations are permitted):

  • CONSOLECONSOLE
  • EVENTLOGEVENTLOG
  • ARCHIVOFILE

También se puede proporcionar la configuración de controlador a través de variables de entorno:The handler settings can also be provided via environment variables:

  • ASPNETCORE_MODULE_DEBUG_FILE – Ruta de acceso al archivo de registro de depuración.ASPNETCORE_MODULE_DEBUG_FILE – Path to the debug log file. (El valor predeterminado es aspnetcore-debug.log)(Default: aspnetcore-debug.log)
  • ASPNETCORE_MODULE_DEBUG – Valor de nivel de depuración.ASPNETCORE_MODULE_DEBUG – Debug level setting.

Advertencia

No deje habilitado el registro de depuración más tiempo del necesario en la implementación para solucionar un problema.Do not leave debug logging enabled in the deployment for longer than required to troubleshoot an issue. El tamaño del registro no es limitado.The size of the log isn't limited. Dejar habilitado el registro de depuración puede agotar el espacio disponible en disco y bloquear el servidor o el servicio de aplicación.Leaving the debug log enabled can exhaust the available disk space and crash the server or app service.

Consulte Configuración con web.config para ver un ejemplo del elemento aspNetCore en el archivo web.config.See Configuration with web.config for an example of the aspNetCore element in the web.config file.

La configuración de proxy usa el protocolo HTTP y un token de emparejamientoProxy configuration uses HTTP protocol and a pairing token

Solo se aplica al hospedaje fuera de proceso.Only applies to out-of-process hosting.

El proxy creado entre el módulo ASP.NET Core y Kestrel usa el protocolo HTTP.The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. No hay ningún riesgo de interceptación del tráfico entre el módulo y Kestrel desde una ubicación fuera del servidor.There's no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server.

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.A pairing token is used to guarantee that the requests received by Kestrel were proxied by IIS and didn't come from some other source. El módulo crea el token de emparejamiento y lo establece en una variable de entorno (ASPNETCORE_TOKEN).The pairing token is created and set into an environment variable (ASPNETCORE_TOKEN) by the module. El token de emparejamiento también se establece en un encabezado (MS-ASPNETCORE-TOKEN) en cada solicitud redirigida mediante proxy.The pairing token is also set into a header (MS-ASPNETCORE-TOKEN) on every proxied request. 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.IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. Si los valores del token no coinciden, la solicitud se registra y se rechaza.If the token values are mismatched, the request is logged and rejected. 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.The pairing token environment variable and the traffic between the module and Kestrel aren't accessible from a location off of the server. Sin conocer el valor del token de emparejamiento, un atacante no puede enviar solicitudes que omitan la comprobación en el middleware de IIS.Without knowing the pairing token value, an attacker can't submit requests that bypass the check in the IIS Middleware.

El módulo ASP.NET Core con una configuración compartida de IISASP.NET Core Module with an IIS Shared Configuration

El instalador del módulo ASP.NET Core se ejecuta con los privilegios de la cuenta TrustedInstaller.The ASP.NET Core Module installer runs with the privileges of the TrustedInstaller account. 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.Because the local system account doesn't have modify permission for the share path used by the IIS Shared Configuration, the installer throws an access denied error when attempting to configure the module settings in the applicationHost.config file on the share.

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:When using an IIS Shared Configuration on the same machine as the IIS installation, run the ASP.NET Core Hosting Bundle installer with the OPT_NO_SHARED_CONFIG_CHECK parameter set to 1:

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

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:When the path to the shared configuration isn't on the same machine as the IIS installation, follow these steps:

  1. Deshabilite la configuración compartida de IIS.Disable the IIS Shared Configuration.
  2. Ejecute el instalador.Run the installer.
  3. Exporte el archivo applicationHost.config actualizado al recurso compartido.Export the updated applicationHost.config file to the share.
  4. Vuelva a habilitar la configuración compartida de IIS.Re-enable the IIS Shared Configuration.

Versión del módulo y registros del instalador de la agrupación de hospedajeModule version and Hosting Bundle installer logs

Para determinar la versión instalada del módulo ASP.NET Core, siga estos pasos:To determine the version of the installed ASP.NET Core Module:

  1. En el sistema de hospedaje, vaya a %windir%\System32\inetsrv.On the hosting system, navigate to %windir%\System32\inetsrv.
  2. Busque el archivo aspnetcore.dll.Locate the aspnetcore.dll file.
  3. Haga clic con el botón derecho en el archivo y seleccione Propiedades en el menú contextual.Right-click the file and select Properties from the contextual menu.
  4. Seleccione la pestaña Detalles. La versión del archivo y la versión del producto representan la versión instalada del módulo.Select the Details tab. The File version and Product version represent the installed version of the module.

Los registros del instalador de la agrupación de hospedaje del módulo se encuentran en C:\Users\%UserName%\AppData\Local\Temp. El archivo se llama dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.The Hosting Bundle installer logs for the module are found at C:\Users\%UserName%\AppData\Local\Temp. The file is named dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

Ubicaciones del módulo, el esquema y el archivo de configuraciónModule, schema, and configuration file locations

ModuleModule

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

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

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

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

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

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

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

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

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

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

SchemaSchema

IISIIS

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

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

IIS ExpressIIS Express

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

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

ConfiguraciónConfiguration

IISIIS

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

IIS ExpressIIS Express

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

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

Los archivos se pueden encontrar mediante la búsqueda de aspnetcore en el archivo applicationHost.config.The files can be found by searching for aspnetcore in the applicationHost.config file.

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

Versiones de Windows compatibles:Supported Windows versions:

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

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

En el siguiente diagrama se muestra la relación entre IIS, el módulo ASP.NET Core y una aplicación:The following diagram illustrates the relationship between IIS, the ASP.NET Core Module, and an app:

Módulo ASP.NET Core

Las solicitudes llegan procedentes de Internet al controlador HTTP.sys en modo kernel.Requests arrive from the web to the kernel-mode HTTP.sys driver. El controlador enruta las solicitudes a IIS en el puerto configurado del sitio web, que suele ser el puerto 80 (HTTP) o 443 (HTTPS).The driver routes the requests to IIS on the website's configured port, usually 80 (HTTP) or 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.The module forwards the requests to Kestrel on a random port for the app, which isn't port 80 or 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}.The module specifies the port via an environment variable at startup, and the IIS Integration Middleware configures the server to listen on http://localhost:{port}. Se realizan más comprobaciones y se rechazan las solicitudes que no se hayan originado en el módulo.Additional checks are performed, and requests that don't originate from the module are rejected. 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.The module doesn't support HTTPS forwarding, so requests are forwarded over HTTP even if received by IIS over HTTPS.

Una vez que Kestrel toma la solicitud del módulo, la envía a la canalización de middleware de ASP.NET Core.After Kestrel picks up the request from the module, the request is pushed into the ASP.NET Core middleware pipeline. La canalización de middleware controla la solicitud y la pasa como una instancia de HttpContext a la lógica de la aplicación.The middleware pipeline handles the request and passes it on as an HttpContext instance to the app's logic. 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.Middleware added by IIS Integration updates the scheme, remote IP, and pathbase to account for forwarding the request to 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.The app's response is passed back to IIS, which pushes it back out to the HTTP client that initiated the request.

Muchos de los módulos nativos, como la autenticación de Windows, permanecen activos.Many native modules, such as Windows Authentication, remain active. 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.To learn more about IIS modules active with the ASP.NET Core Module, see Módulos de IIS con ASP.NET Core.

El módulo ASP.NET Core también puede:The ASP.NET Core Module can also:

  • Establecer variables de entorno para un proceso de trabajo.Set environment variables for the worker process.
  • Registrar la salida en un almacenamiento de archivos para solucionar problemas de inicio.Log stdout output to file storage for troubleshooting startup issues.
  • Reenviar tokens de autenticación de Windows.Forward Windows authentication tokens.

Cómo instalar y usar el módulo ASP.NET CoreHow to install and use the ASP.NET Core Module

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.For instructions on how to install the ASP.NET Core Module, see Install the .NET Core Hosting Bundle.

Configuración con web.configConfiguration with 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.The ASP.NET Core Module is configured with the aspNetCore section of the system.webServer node in the site's web.config file.

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

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

El siguiente archivo web.config se publica para una implementación independiente:The following web.config is published for a self-contained deployment:

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

Cuando se implementa una aplicación en Azure App Service, la ruta de acceso de stdoutLogFile se establece en \\?\%home%\LogFiles\stdout.When an app is deployed to Azure App Service, the stdoutLogFile path is set to \\?\%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.The path saves stdout logs to the LogFiles folder, which is a location automatically created by the service.

Para obtener información sobre la configuración de aplicaciones secundarias de IIS, consulte Hospedaje de ASP.NET Core en Windows con IIS.For information on IIS sub-application configuration, see Hospedaje de ASP.NET Core en Windows con IIS.

Atributos del elemento aspNetCoreAttributes of the aspNetCore element

AtributoAttribute DescripciónDescription DefaultDefault
arguments

Atributo de cadena opcional.Optional string attribute.

Argumentos para el archivo ejecutable especificado en processPath.Arguments to the executable specified in processPath.

disableStartUpErrorPage

Atributo Boolean opcional.Optional Boolean attribute.

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.If true, the 502.5 - Process Failure page is suppressed, and the 502 status code page configured in the web.config takes precedence.

false
forwardWindowsAuthToken

Atributo Boolean opcional.Optional Boolean attribute.

Si es true, el token se reenvía al proceso secundario que escucha en % ASPNETCORE_PORT % como un encabezado "MS-ASPNETCORE-WINAUTHTOKEN" por solicitud.If true, the token is forwarded to the child process listening on %ASPNETCORE_PORT% as a header 'MS-ASPNETCORE-WINAUTHTOKEN' per request. Es responsabilidad de dicho proceso llamar a CloseHandle en este token por solicitud.It's the responsibility of that process to call CloseHandle on this token per request.

true
processesPerApplication

Atributo integer opcional.Optional integer attribute.

Especifica el número de instancias del proceso especificado en el valor processPath que pueden rotarse por aplicación.Specifies the number of instances of the process specified in the processPath setting that can be spun up per app.

No se recomienda establecer processesPerApplication.Setting processesPerApplication is discouraged. Este atributo se quitará en futuras versiones.This attribute will be removed in a future release.

Valor predeterminado: 1Default: 1
Mínimo: 1Min: 1
Máximo: 100Max: 100
processPath

Atributo de cadena necesario.Required string attribute.

Ruta de acceso al archivo ejecutable que inicia un proceso que escucha las solicitudes HTTP.Path to the executable that launches a process listening for HTTP requests. No se admiten rutas de acceso relativas.Relative paths are supported. Si la ruta de acceso comienza con ., se considera que es relativa a la raíz del sitio.If the path begins with ., the path is considered to be relative to the site root.

rapidFailsPerMinute

Atributo integer opcional.Optional integer attribute.

Especifica el número de veces que el proceso indicado en processPath puede bloquearse por minuto.Specifies the number of times the process specified in processPath is allowed to crash per minute. Si se supera este límite, el módulo deja de iniciar el proceso durante lo que resta del minuto.If this limit is exceeded, the module stops launching the process for the remainder of the minute.

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

Atributo timespan opcional.Optional timespan attribute.

Especifica el tiempo que el módulo ASP.NET Core espera una respuesta del proceso que escucha en % ASPNETCORE_PORT %.Specifies the duration for which the ASP.NET Core Module waits for a response from the process listening on %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.In versions of the ASP.NET Core Module that shipped with the release of ASP.NET Core 2.1 or later, the requestTimeout is specified in hours, minutes, and seconds.

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

Atributo integer opcional.Optional integer attribute.

Tiempo en segundos que el módulo espera a que se cierre correctamente el archivo ejecutable cuando se detecta el archivo app_offline.htm.Duration in seconds that the module waits for the executable to gracefully shutdown when the app_offline.htm file is detected.

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

Atributo integer opcional.Optional integer attribute.

Tiempo en segundos que espera el módulo a que el archivo ejecutable inicie u proceso que escucha en el puerto.Duration in seconds that the module waits for the executable to start a process listening on the port. Si se supera este límite de tiempo, el módulo termina el proceso.If this time limit is exceeded, the module kills the process. 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.The module attempts to relaunch the process when it receives a new request and continues to attempt to restart the process on subsequent incoming requests unless the app fails to start rapidFailsPerMinute number of times in the last rolling minute.

Un valor de 0 (cero) no se considera un tiempo de expiración infinito.A value of 0 (zero) is not considered an infinite timeout.

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

Atributo Boolean opcional.Optional Boolean attribute.

Si es true, stdout y stderr en el proceso especificado en processPath se redirigen al archivo especificado en stdoutLogFile.If true, stdout and stderr for the process specified in processPath are redirected to the file specified in stdoutLogFile.

false
stdoutLogFile

Atributo de cadena opcional.Optional string attribute.

Especifica la ruta de acceso relativa o absoluta para la que se registran stdout y stderr desde el proceso especificado en processPath.Specifies the relative or absolute file path for which stdout and stderr from the process specified in processPath are logged. Las rutas de acceso relativas son relativas a la raíz del sitio.Relative paths are relative to the root of the site. 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.Any path starting with . are relative to the site root and all other paths are treated as absolute paths. Las carpetas que se proporcionan en la ruta de acceso deben estar en orden para que el módulo cree el archivo de registro.Any folders provided in the path must exist in order for the module to create the log file. 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.Using underscore delimiters, a timestamp, process ID, and file extension (.log) are added to the last segment of the stdoutLogFile path. Si .\logs\stdout se proporciona como valor, se guarda un registro de ejemplo de stdout como stdout_20180205194132_1934.log en la carpeta logs, cuando se guarda el 5/2/2018 a las 19:41:32 con un identificador de proceso de 1934.If .\logs\stdout is supplied as a value, an example stdout log is saved as stdout_20180205194132_1934.log in the logs folder when saved on 2/5/2018 at 19:41:32 with a process ID of 1934.

aspnetcore-stdout

Configuración de las variables de entornoSetting environment variables

Se pueden especificar variables de entorno para el proceso en el atributo processPath.Environment variables can be specified for the process in the processPath attribute. Especifique una variable de entorno con el elemento secundario <environmentVariable> de un elemento de la colección <environmentVariables>.Specify an environment variable with the <environmentVariable> child element of an <environmentVariables> collection element.

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.Environment variables set in this section conflict with system environment variables set with the same name. 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.If an environment variable is set in both the web.config file and at the system level in Windows, the value from the web.config file becomes appended to the system environment variable value (for example, ASPNETCORE_ENVIRONMENT: Development;Development), which prevents the app from starting.

En el ejemplo siguiente se establecen dos variables de entorno.The following example sets two environment variables. ASPNETCORE_ENVIRONMENT configura el entorno de la aplicación como Development.ASPNETCORE_ENVIRONMENT configures the app's environment to 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.A developer may temporarily set this value in the web.config file in order to force the Developer Exception Page to load when debugging an app exception. CONFIG_DIR 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.CONFIG_DIR is an example of a user-defined environment variable, where the developer has written code that reads the value on startup to form a path for loading the app's configuration file.

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

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.Only set the ASPNETCORE_ENVIRONMENT environment variable to Development on staging and testing servers that aren't accessible to untrusted networks, such as the Internet.

app_offline.htmapp_offline.htm

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

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.While the app_offline.htm file is present, the ASP.NET Core Module responds to requests by sending back the contents of the app_offline.htm file. Cuando se quita el archivo app_offline.htm, la solicitud siguiente inicia la aplicación.When the app_offline.htm file is removed, the next request starts the app.

Página de errores de inicioStart-up error page

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.If the ASP.NET Core Module fails to launch the backend process or the backend process starts but fails to listen on the configured port, a 502.5 - Process Failure status code page appears. Para suprimir esta página y volver a la página de código de estado 502 de IIS predeterminada, use el atributo disableStartUpErrorPage.To suppress this page and revert to the default IIS 502 status code page, use the disableStartUpErrorPage attribute. Para obtener más información sobre cómo configurar los mensajes de error personalizados, consulte Errores HTTP <httpErrors>.For more information on configuring custom error messages, see HTTP Errors <httpErrors>.

Página de códigos de estado 502.5 Error de proceso

Creación y redireccionamiento de registrosLog creation and redirection

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.The ASP.NET Core Module redirects stdout and stderr console output to disk if the stdoutLogEnabled and stdoutLogFile attributes of the aspNetCore element are set. Al crearse el archivo de registro, el módulo crea las carpetas de la ruta de acceso de stdoutLogFile.Any folders in the stdoutLogFile path are created by the module when the log file is created. 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).The app pool must have write access to the location where the logs are written (use IIS AppPool\<app_pool_name> to provide write permission).

Los registros no se rotan, a no ser que se produzca un reinicio o reciclaje del proceso.Logs aren't rotated, unless process recycling/restart occurs. Es responsabilidad del proveedor de servicios de hospedaje limitar el espacio en disco que consumen los registros.It's the responsibility of the hoster to limit the disk space the logs consume.

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.Using the stdout log is only recommended for troubleshooting app startup issues when hosting on IIS or when using development-time support for IIS with Visual Studio, not while debugging locally and running the app with IIS Express.

No use el registro de stdout con fines de registro de aplicaciones general.Don't use the stdout log for general app logging purposes. 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.For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. Para más información, consulte los proveedores de registro de terceros.For more information, see third-party logging providers.

Cuando se crea el archivo de registro, se agregan automáticamente una marca de tiempo y una extensión de archivo.A timestamp and file extension are added automatically when the log file is created. 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.The log file name is composed by appending the timestamp, process ID, and file extension (.log) to the last segment of the stdoutLogFile path (typically stdout) delimited by underscores. 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.If the stdoutLogFile path ends with stdout, a log for an app with a PID of 1934 created on 2/5/2018 at 19:42:32 has the file name stdout_20180205194132_1934.log.

En el siguiente elemento aspNetCore de ejemplo se configura el registro de stdout en la ruta de acceso relativa .\log\.The following sample aspNetCore element configures stdout logging at the relative path .\log\. Confirme que la identidad del usuario de AppPool tenga permiso para escribir en la ruta de acceso proporcionada.Confirm that the AppPool user identity has permission to write to the path provided.

<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.When publishing an app for Azure App Service deployment, the Web SDK sets the stdoutLogFile value to \\?\%home%\LogFiles\stdout. La variable de entorno %home está predefinida para las aplicaciones hospedadas por Azure App Service.The %home environment variable is predefined for apps hosted by Azure App Service.

Para crear reglas de filtro de registro, vea las secciones Configuración y Filtrado de registros de la documentación del registro en ASP.NET Core.To create logging filter rules, see the Configuration and Log filtering sections of the ASP.NET Core logging documentation.

Para más información sobre los formatos de ruta de acceso, vea Formatos de ruta de acceso de archivo en los sistemas Windows.For more information on path formats, see File path formats on Windows systems.

La configuración de proxy usa el protocolo HTTP y un token de emparejamientoProxy configuration uses HTTP protocol and a pairing token

El proxy creado entre el módulo ASP.NET Core y Kestrel usa el protocolo HTTP.The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. No hay ningún riesgo de interceptación del tráfico entre el módulo y Kestrel desde una ubicación fuera del servidor.There's no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server.

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.A pairing token is used to guarantee that the requests received by Kestrel were proxied by IIS and didn't come from some other source. El módulo crea el token de emparejamiento y lo establece en una variable de entorno (ASPNETCORE_TOKEN).The pairing token is created and set into an environment variable (ASPNETCORE_TOKEN) by the module. El token de emparejamiento también se establece en un encabezado (MS-ASPNETCORE-TOKEN) en cada solicitud redirigida mediante proxy.The pairing token is also set into a header (MS-ASPNETCORE-TOKEN) on every proxied request. 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.IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. Si los valores del token no coinciden, la solicitud se registra y se rechaza.If the token values are mismatched, the request is logged and rejected. 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.The pairing token environment variable and the traffic between the module and Kestrel aren't accessible from a location off of the server. Sin conocer el valor del token de emparejamiento, un atacante no puede enviar solicitudes que omitan la comprobación en el middleware de IIS.Without knowing the pairing token value, an attacker can't submit requests that bypass the check in the IIS Middleware.

El módulo ASP.NET Core con una configuración compartida de IISASP.NET Core Module with an IIS Shared Configuration

El instalador del módulo ASP.NET Core se ejecuta con los privilegios de la cuenta TrustedInstaller.The ASP.NET Core Module installer runs with the privileges of the TrustedInstaller account. 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.Because the local system account doesn't have modify permission for the share path used by the IIS Shared Configuration, the installer throws an access denied error when attempting to configure the module settings in the applicationHost.config file on the share.

Al usar una configuración compartida de IIS, siga estos pasos:When using an IIS Shared Configuration, follow these steps:

  1. Deshabilite la configuración compartida de IIS.Disable the IIS Shared Configuration.
  2. Ejecute el instalador.Run the installer.
  3. Exporte el archivo applicationHost.config actualizado al recurso compartido.Export the updated applicationHost.config file to the share.
  4. Vuelva a habilitar la configuración compartida de IIS.Re-enable the IIS Shared Configuration.

Versión del módulo y registros del instalador de la agrupación de hospedajeModule version and Hosting Bundle installer logs

Para determinar la versión instalada del módulo ASP.NET Core, siga estos pasos:To determine the version of the installed ASP.NET Core Module:

  1. En el sistema de hospedaje, vaya a %windir%\System32\inetsrv.On the hosting system, navigate to %windir%\System32\inetsrv.
  2. Busque el archivo aspnetcore.dll.Locate the aspnetcore.dll file.
  3. Haga clic con el botón derecho en el archivo y seleccione Propiedades en el menú contextual.Right-click the file and select Properties from the contextual menu.
  4. Seleccione la pestaña Detalles. La versión del archivo y la versión del producto representan la versión instalada del módulo.Select the Details tab. The File version and Product version represent the installed version of the module.

Los registros del instalador de la agrupación de hospedaje del módulo se encuentran en C:\Users\%UserName%\AppData\Local\Temp. El archivo se llama dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.The Hosting Bundle installer logs for the module are found at C:\Users\%UserName%\AppData\Local\Temp. The file is named dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log.

Ubicaciones del módulo, el esquema y el archivo de configuraciónModule, schema, and configuration file locations

ModuleModule

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

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

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

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

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

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

SchemaSchema

IISIIS

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

IIS ExpressIIS Express

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

ConfiguraciónConfiguration

IISIIS

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

IIS ExpressIIS Express

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

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

Los archivos se pueden encontrar mediante la búsqueda de aspnetcore en el archivo applicationHost.config.The files can be found by searching for aspnetcore in the applicationHost.config file.

Recursos adicionalesAdditional resources