diff --git a/aspnetcore/host-and-deploy/aspnet-core-module.md b/aspnetcore/host-and-deploy/aspnet-core-module.md index f72fb4f40208..164219f04e08 100644 --- a/aspnetcore/host-and-deploy/aspnet-core-module.md +++ b/aspnetcore/host-and-deploy/aspnet-core-module.md @@ -5,7 +5,7 @@ description: Learn about the ASP.NET Core Module (ANCM) for hosting ASP.NET Core monikerRange: '>= aspnetcore-2.1' ms.author: tdykstra ms.custom: mvc -ms.date: 03/04/2022 +ms.date: 04/20/2026 uid: host-and-deploy/aspnet-core-module --- @@ -15,7 +15,7 @@ uid: host-and-deploy/aspnet-core-module :::moniker range=">= aspnetcore-5.0" -The ASP.NET Core Module (ANCM) is a native IIS module that plugs into the IIS pipeline, allowing ASP.NET Core applications to work with IIS. Run ASP.NET Core apps with IIS by either: +The ASP.NET Core Module (ANCM) is a native IIS module that plugs into the IIS pipeline, allowing ASP.NET Core applications to work with IIS. Run ASP.NET Core apps with IIS by either: * Hosting an ASP.NET Core app inside of the IIS worker process (`w3wp.exe`), called the [in-process hosting model](xref:host-and-deploy/iis/in-process-hosting). * Forwarding web requests to a backend ASP.NET Core app running the Kestrel server, called the [out-of-process hosting model](xref:host-and-deploy/iis/out-of-process-hosting). @@ -151,7 +151,7 @@ For instructions on how to install the ASP.NET Core Module, see [Install the .NE The ASP.NET Core Module is configured with the `aspNetCore` section of the `system.webServer` node in the site's *web.config* file. -The following `web.config` file is published for a [framework-dependent deployment](/dotnet/articles/core/deploying/#framework-dependent-deployments-fdd) and configures the ASP.NET Core Module to handle site requests: +The following `web.config` file is published for a [framework-dependent deployment](/dotnet/core/deploying/#framework-dependent-deployments-fdd) and configures the ASP.NET Core Module to handle site requests: ```xml @@ -171,7 +171,7 @@ The following `web.config` file is published for a [framework-dependent deployme ``` -The following *web.config* is published for a [self-contained deployment](/dotnet/articles/core/deploying/#self-contained-deployments-scd): +The following *web.config* is published for a [self-contained deployment](/dotnet/core/deploying/#self-contained-deployments-scd): ```xml @@ -190,9 +190,9 @@ The following *web.config* is published for a [self-contained deployment](/dotne ``` -The property is set to `false` to indicate that the settings specified within the [``](/iis/manage/managing-your-configuration-settings/understanding-iis-configuration-delegation#the-concept-of-location) element aren't inherited by apps that reside in a subdirectory of the app. +The property is set to `false` to indicate that apps that reside in a subdirectory of the app don't inherit the settings specified within the [``](/iis/manage/managing-your-configuration-settings/understanding-iis-configuration-delegation#the-concept-of-location) element. -When an app is deployed to [Azure App Service](https://azure.microsoft.com/services/app-service/), the `stdoutLogFile` path is set to `\\?\%home%\LogFiles\stdout`. The path saves stdout logs to the `LogFiles` folder, which is a location automatically created by the service. +When an app is deployed to [Azure App Service](https://azure.microsoft.com/products/app-service/), the `stdoutLogFile` path is set to `\\?\%home%\LogFiles\stdout`. The path saves stdout logs to the `LogFiles` folder, which is a location automatically created by the service. For information on IIS sub-application configuration, see . @@ -211,13 +211,13 @@ For information on IIS sub-application configuration, see Optional integer attribute.

Duration in seconds that the module waits for the executable to gracefully shutdown when the `app_offline.htm` file is detected.

| Default: `10`
Min: `0`
Max: `600` | | `startupTimeLimit` |

Optional integer attribute.

Duration in seconds that the module waits for the executable to start a process listening on the port. If this time limit is exceeded, the module kills the process.

When hosting *in-process*: The process is **not** restarted and does **not** use the **rapidFailsPerMinute** setting.

When hosting *out-of-process*: 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.

A value of 0 (zero) is **not** considered an infinite timeout.

| Default: `120`
Min: `0`
Max: `3600` | | `stdoutLogEnabled` |

Optional Boolean attribute.

If true, **stdout** and **stderr** for the process specified in **processPath** are redirected to the file specified in **stdoutLogFile**.

| `false` | -| `stdoutLogFile` |

Optional string attribute.

Specifies the relative or absolute file path for which **stdout** and **stderr** from the process specified in **processPath** are logged. Relative paths are relative to the root of the site. Any path starting with `.` are relative to the site root and all other paths are treated as absolute paths. Any folders provided in the path are created by the module when the log file is created. Using underscore delimiters, a timestamp, process ID, and file extension (`.log`) are added to the last segment of the **stdoutLogFile** path. 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` | +| `stdoutLogFile` |

Optional string attribute.

Specifies the relative or absolute file path for which **stdout** and **stderr** from the process specified in **processPath** are logged. Relative paths are relative to the root of the site. Any path starting with `.` are relative to the site root and all other paths are treated as absolute paths. The module creates any folders provided in the path when it creates the log file. Using underscore delimiters, a timestamp, process ID, and file extension (`.log`) are added to the last segment of the **stdoutLogFile** path. 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` | ### Set environment variables Environment variables can be specified for the process in the `processPath` attribute. Specify an environment variable with the `` child element of an `` collection element. Environment variables set in this section take precedence over system environment variables. -The following example sets two environment variables in `web.config`. `ASPNETCORE_ENVIRONMENT` configures the app's environment to `Development`. A developer may temporarily set this value in the `web.config` file in order to force the [Developer Exception Page](xref:fundamentals/error-handling) to load when debugging an app exception. `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. +The following example sets two environment variables in `web.config`. `ASPNETCORE_ENVIRONMENT` configures the app's environment to `Development`. A developer might temporarily set this value in the `web.config` file in order to force the [Developer Exception Page](xref:fundamentals/error-handling) to load when debugging an app exception. `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. ```xml Development > > ``` - +> > [!WARNING] > 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. @@ -250,7 +250,7 @@ If a file with the name `app_offline.htm` is detected in the root directory of a 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. When the `app_offline.htm` file is removed, the next request starts the app. -When using the out-of-process hosting model, the app might not shut down immediately if there's an open connection. For example, a WebSocket connection may delay app shut down. +When using the out-of-process hosting model, the app might not shut down immediately if there's an open connection. For example, a WebSocket connection might delay app shut down. ## Start-up error page @@ -258,15 +258,15 @@ Both in-process and out-of-process hosting produce custom error pages when they 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. -For in-process hosting if the ASP.NET Core Module fails to start the app, a *500.30 - Start Failure* status code page appears. +For in-process hosting, if the ASP.NET Core Module fails to start the app, a *500.30 - Start Failure* status code page appears. -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. +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. To suppress this page and revert to the default IIS 5xx status code page, use the `disableStartUpErrorPage` attribute. For more information on configuring custom error messages, see [HTTP Errors ``](/iis/configuration/system.webServer/httpErrors/). ## Log creation and redirection -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. Any folders in the `stdoutLogFile` path are created by the module when the log file is created. The app pool must have write access to the location where the logs are written (use `IIS AppPool\` to provide write permission). +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. The module creates any folders in the `stdoutLogFile` path when it creates the log file. The app pool must have write access to the location where the logs are written (use `IIS AppPool\` to provide write permission). Logs aren't rotated, unless process recycling/restart occurs. It's the responsibility of the hoster to limit the disk space the logs consume. @@ -274,7 +274,7 @@ Using the stdout log is only recommended for troubleshooting app startup issues Don't use the stdout log for general app logging purposes. For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. For more information, see [third-party logging providers](xref:fundamentals/logging/index#third-party-logging-providers). -A timestamp and file extension are added automatically when the log file is created. 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. 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`. +A timestamp and file extension are added automatically when the log file is created. 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. If the `stdoutLogFile` path ends with `stdout`, a log for an app with a PID of 1934 created on February 5, 2018 at 19:42:32 has the file name `stdout_20180205194132_1934.log`. If `stdoutLogEnabled` is false, errors that occur on app startup are captured and emitted to the event log up to 30 KB. After startup, all additional logs are discarded. @@ -312,7 +312,7 @@ The ASP.NET Core Module is configurable to provide enhanced diagnostics logs. Ad ``` -Any folders in the path (`logs` in the preceding example) are created by the module when the log file is created. The app pool must have write access to the location where the logs are written (use `IIS AppPool\{APP POOL NAME}`, where the placeholder `{APP POOL NAME}` is the app pool name, to provide write permission). +The module creates any folders in the path (`logs` in the preceding example) when it creates the log file. The app pool must have write access to the location where the logs are written (use `IIS AppPool\{APP POOL NAME}`, where the placeholder `{APP POOL NAME}` is the app pool name, to provide write permission). Debug level (`debugLevel`) values can include both the level and the location. @@ -363,7 +363,7 @@ Configure the managed stack size using the `stackSize` setting in bytes in `web. The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. There's no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server. -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. The pairing token is created and set into an environment variable (`ASPNETCORE_TOKEN`) by the module. The pairing token is also set into a header (`MS-ASPNETCORE-TOKEN`) on every proxied request. IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. If the token values are mismatched, the request is logged and rejected. The pairing token environment variable and the traffic between the module and Kestrel aren't accessible from a location off of the server. Without knowing the pairing token value, a cyberattacker can't submit requests that bypass the check in the IIS Middleware. +A pairing token is used to guarantee that IIS proxied the requests received by Kestrel and didn't come from some other source. The pairing token is created and set into an environment variable (`ASPNETCORE_TOKEN`) by the module. The pairing token is also set into a header (`MS-ASPNETCORE-TOKEN`) on every proxied request. IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. If the token values are mismatched, the request is logged and rejected. The pairing token environment variable and the traffic between the module and Kestrel aren't accessible from a location off of the server. Without knowing the pairing token value, a cyberattacker can't submit requests that bypass the check in the IIS Middleware. ## ASP.NET Core Module with an IIS Shared Configuration @@ -382,7 +382,7 @@ When the path to the shared configuration isn't on the same machine as the IIS i 1. Export the updated `applicationHost.config` file to the share. 1. Re-enable the IIS Shared Configuration. -## Module version and Hosting Bundle installer logs +## version and Hosting Bundle installer logs To determine the version of the installed ASP.NET Core Module: @@ -493,7 +493,7 @@ The following characteristics apply when hosting in-process: * Sharing an app pool among apps isn't supported. Use one app pool per app. -* When using [Web Deploy](/iis/publish/using-web-deploy/introduction-to-web-deploy) or manually placing an [app_offline.htm file in the deployment](xref:host-and-deploy/iis/index#locked-deployment-files), the app might not shut down immediately if there's an open connection. For example, a websocket connection may delay app shut down. +* When using [Web Deploy](/iis/publish/using-web-deploy/introduction-to-web-deploy) or manually placing an [app_offline.htm file in the deployment](xref:host-and-deploy/iis/index#locked-deployment-files), the app might not shut down immediately if there's an open connection. For example, a websocket connection might delay app shut down. * The architecture (bitness) of the app and installed runtime (x64 or x86) must match the architecture of the app pool. @@ -568,7 +568,7 @@ For instructions on how to install the ASP.NET Core Module, see [Install the .NE The ASP.NET Core Module is configured with the `aspNetCore` section of the `system.webServer` node in the site's *web.config* file. -The following *web.config* file is published for a [framework-dependent deployment](/dotnet/articles/core/deploying/#framework-dependent-deployments-fdd) and configures the ASP.NET Core Module to handle site requests: +The following *web.config* file is published for a [framework-dependent deployment](/dotnet/core/deploying/#framework-dependent-deployments-fdd) and configures the ASP.NET Core Module to handle site requests: ```xml @@ -588,7 +588,7 @@ The following *web.config* file is published for a [framework-dependent deployme ``` -The following *web.config* is published for a [self-contained deployment](/dotnet/articles/core/deploying/#self-contained-deployments-scd): +The following *web.config* is published for a [self-contained deployment](/dotnet/core/deploying/#self-contained-deployments-scd): ```xml @@ -607,9 +607,9 @@ The following *web.config* is published for a [self-contained deployment](/dotne ``` -The property is set to `false` to indicate that the settings specified within the [\](/iis/manage/managing-your-configuration-settings/understanding-iis-configuration-delegation#the-concept-of-location) element aren't inherited by apps that reside in a subdirectory of the app. +The property is set to `false` to indicate that apps that reside in a subdirectory of the app aren't inheriting the settings specified within the [\](/iis/manage/managing-your-configuration-settings/understanding-iis-configuration-delegation#the-concept-of-location) element. -When an app is deployed to [Azure App Service](https://azure.microsoft.com/services/app-service/), the `stdoutLogFile` path is set to `\\?\%home%\LogFiles\stdout`. The path saves stdout logs to the *LogFiles* folder, which is a location automatically created by the service. +When an app is deployed to [Azure App Service](https://azure.microsoft.com/products/app-service/), the `stdoutLogFile` path is set to `\\?\%home%\LogFiles\stdout`. The path saves stdout logs to the *LogFiles* folder, which is a location automatically created by the service. For information on IIS sub-application configuration, see . @@ -628,13 +628,13 @@ For information on IIS sub-application configuration, see Optional integer attribute.

Duration in seconds that the module waits for the executable to gracefully shutdown when the `app_offline.htm` file is detected.

| Default: `10`
Min: `0`
Max: `600` | | `startupTimeLimit` |

Optional integer attribute.

Duration in seconds that the module waits for the executable to start a process listening on the port. If this time limit is exceeded, the module kills the process.

When hosting *in-process*: The process is **not** restarted and does **not** use the `rapidFailsPerMinute` setting.

When hosting *out-of-process*: 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.

A value of 0 (zero) is **not** considered an infinite timeout.

| Default: `120`
Min: `0`
Max: `3600` | | `stdoutLogEnabled` |

Optional Boolean attribute.

If true, **stdout** and **stderr** for the process specified in `processPath` are redirected to the file specified in **stdoutLogFile**.

| `false` | -| `stdoutLogFile` |

Optional string attribute.

Specifies the relative or absolute file path for which `stdout` and `stderr` from the process specified in `processPath` are logged. Relative paths are relative to the root of the site. Any path starting with `.` are relative to the site root and all other paths are treated as absolute paths. Any folders provided in the path are created by the module when the log file is created. Using underscore delimiters, a timestamp, process ID, and file extension (`.log`) are added to the last segment of the `stdoutLogFile` path. 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` | +| `stdoutLogFile` |

Optional string attribute.

Specifies the relative or absolute file path for which `stdout` and `stderr` from the process specified in `processPath` are logged. Relative paths are relative to the root of the site. Any path starting with `.` are relative to the site root and all other paths are treated as absolute paths. The module creates any folders provided in the path when it creates the log file. Using underscore delimiters, a timestamp, process ID, and file extension (`.log`) are added to the last segment of the `stdoutLogFile` path. 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` | ### Setting environment variables Environment variables can be specified for the process in the `processPath` attribute. Specify an environment variable with the `` child element of an `` collection element. Environment variables set in this section take precedence over system environment variables. -The following example sets two environment variables. `ASPNETCORE_ENVIRONMENT` configures the app's environment to `Development`. A developer may temporarily set this value in the `web.config` file in order to force the [Developer Exception Page](xref:fundamentals/error-handling) to load when debugging an app exception. `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. +The following example sets two environment variables. `ASPNETCORE_ENVIRONMENT` configures the app's environment to `Development`. A developer might temporarily set this value in the `web.config` file in order to force the [Developer Exception Page](xref:fundamentals/error-handling) to load when debugging an app exception. `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. ```xml Development > > ``` - +> > [!WARNING] > 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. @@ -667,7 +667,7 @@ If a file with the name `app_offline.htm` is detected in the root directory of a 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. When the `app_offline.htm` file is removed, the next request starts the app. -When using the out-of-process hosting model, the app might not shut down immediately if there's an open connection. For example, a websocket connection may delay app shut down. +When using the out-of-process hosting model, the app might not shut down immediately if there's an open connection. For example, a websocket connection might delay app shut down. ## Start-up error page @@ -683,7 +683,7 @@ To suppress this page and revert to the default IIS 5xx status code page, use th ## Log creation and redirection -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. Any folders in the `stdoutLogFile` path are created by the module when the log file is created. 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, where the placeholder `{APP POOL NAME}` is the app pool name). +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. The module creates any folders in the `stdoutLogFile` path when it creates the log file. 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, where the placeholder `{APP POOL NAME}` is the app pool name). Logs aren't rotated, unless process recycling/restart occurs. It's the responsibility of the hoster to limit the disk space the logs consume. @@ -727,7 +727,7 @@ The ASP.NET Core Module is configurable to provide enhanced diagnostics logs. Ad ``` -Folders in the path provided to the `` value (`logs` in the preceding example) aren't created by the module automatically and should pre-exist in the deployment. 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, where the placeholder `{APP POOL NAME}` is the app pool name). +The module doesn't automatically create folders in the path provided to the `` value (`logs` in the preceding example) and should pre-exist in the deployment. 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, where the placeholder `{APP POOL NAME}` is the app pool name). Debug level (`debugLevel`) values can include both the level and the location. @@ -760,7 +760,7 @@ See [Configuration with web.config](#configuration-with-webconfig) for an exampl The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. There's no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server. -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. The pairing token is created and set into an environment variable (`ASPNETCORE_TOKEN`) by the module. The pairing token is also set into a header (`MS-ASPNETCORE-TOKEN`) on every proxied request. IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. If the token values are mismatched, the request is logged and rejected. The pairing token environment variable and the traffic between the module and Kestrel aren't accessible from a location off of the server. Without knowing the pairing token value, a cyberattacker can't submit requests that bypass the check in the IIS Middleware. +A pairing token is used to guarantee that IIS proxied the requests received by Kestrel and didn't come from some other source. The pairing token is created and set into an environment variable (`ASPNETCORE_TOKEN`) by the module. The pairing token is also set into a header (`MS-ASPNETCORE-TOKEN`) on every proxied request. IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. If the token values are mismatched, the request is logged and rejected. The pairing token environment variable and the traffic between the module and Kestrel aren't accessible from a location off of the server. Without knowing the pairing token value, a cyberattacker can't submit requests that bypass the check in the IIS Middleware. ## ASP.NET Core Module with an IIS Shared Configuration @@ -855,7 +855,7 @@ Supported Windows versions: The module only works with Kestrel. The module is incompatible with [HTTP.sys](xref:fundamentals/servers/httpsys). -Because ASP.NET Core apps run in a process separate from the IIS worker process, the module also handles process management. The module starts the process for the ASP.NET Core app when the first request arrives and restarts the app if it crashes. 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)](/iis/manage/provisioning-and-managing-iis/features-of-the-windows-process-activation-service-was). +Because ASP.NET Core apps run in a process separate from the IIS worker process, the module also handles process management. The module starts the process for the ASP.NET Core app when the first request arrives and restarts the app if it crashes. This is essentially the same behavior as seen with ASP.NET 4.x apps that run in-process in IIS that the [Windows Process Activation Service (WAS)](/iis/manage/provisioning-and-managing-iis/features-of-the-windows-process-activation-service-was) manages. The following diagram illustrates the relationship between IIS, the ASP.NET Core Module, and an app: @@ -883,7 +883,7 @@ For instructions on how to install the ASP.NET Core Module, see [Install the .NE The ASP.NET Core Module is configured with the `aspNetCore` section of the `system.webServer` node in the site's *web.config* file. -The following *web.config* file is published for a [framework-dependent deployment](/dotnet/articles/core/deploying/#framework-dependent-deployments-fdd) and configures the ASP.NET Core Module to handle site requests: +The following *web.config* file is published for a [framework-dependent deployment](/dotnet/core/deploying/#framework-dependent-deployments-fdd) and configures the ASP.NET Core Module to handle site requests: ```xml @@ -900,7 +900,7 @@ The following *web.config* file is published for a [framework-dependent deployme ``` -The following *web.config* is published for a [self-contained deployment](/dotnet/articles/core/deploying/#self-contained-deployments-scd): +The following *web.config* is published for a [self-contained deployment](/dotnet/core/deploying/#self-contained-deployments-scd): ```xml @@ -916,7 +916,7 @@ The following *web.config* is published for a [self-contained deployment](/dotne ``` -When an app is deployed to [Azure App Service](https://azure.microsoft.com/services/app-service/), the `stdoutLogFile` path is set to `\\?\%home%\LogFiles\stdout`. The path saves stdout logs to the *LogFiles* folder, which is a location automatically created by the service. +When an app is deployed to [Azure App Service](https://azure.microsoft.com/products/app-service/), the `stdoutLogFile` path is set to `\\?\%home%\LogFiles\stdout`. The path saves stdout logs to the *LogFiles* folder, which is a location automatically created by the service. For information on IIS sub-application configuration, see . @@ -943,7 +943,7 @@ Environment variables can be specified for the process in the `processPath` attr > [!WARNING] > Environment variables set in this section conflict with system environment variables set with the same name. 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. -The following example sets two environment variables. `ASPNETCORE_ENVIRONMENT` configures the app's environment to `Development`. A developer may temporarily set this value in the *web.config* file in order to force the [Developer Exception Page](xref:fundamentals/error-handling) to load when debugging an app exception. `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. +The following example sets two environment variables. `ASPNETCORE_ENVIRONMENT` configures the app's environment to `Development`. A developer might temporarily set this value in the *web.config* file in order to force the [Developer Exception Page](xref:fundamentals/error-handling) to load when debugging an app exception. `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. ```xml ` to provide write permission). +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. The module creates any folders in the `stdoutLogFile` path when it creates the log file. The app pool must have write access to the location where the logs are written (use `IIS AppPool\` to provide write permission). Logs aren't rotated, unless process recycling/restart occurs. It's the responsibility of the hoster to limit the disk space the logs consume. @@ -1002,7 +1002,7 @@ For more information on path formats, see [File path formats on Windows systems] The proxy created between the ASP.NET Core Module and Kestrel uses the HTTP protocol. There's no risk of eavesdropping the traffic between the module and Kestrel from a location off of the server. -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. The pairing token is created and set into an environment variable (`ASPNETCORE_TOKEN`) by the module. The pairing token is also set into a header (`MS-ASPNETCORE-TOKEN`) on every proxied request. IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. If the token values are mismatched, the request is logged and rejected. The pairing token environment variable and the traffic between the module and Kestrel aren't accessible from a location off of the server. Without knowing the pairing token value, a cyberattacker can't submit requests that bypass the check in the IIS Middleware. +A pairing token is used to guarantee that IIS proxied the requests received by Kestrel and didn't come from some other source. The pairing token is created and set into an environment variable (`ASPNETCORE_TOKEN`) by the module. The pairing token is also set into a header (`MS-ASPNETCORE-TOKEN`) on every proxied request. IIS Middleware checks each request it receives to confirm that the pairing token header value matches the environment variable value. If the token values are mismatched, the request is logged and rejected. The pairing token environment variable and the traffic between the module and Kestrel aren't accessible from a location off of the server. Without knowing the pairing token value, a cyberattacker can't submit requests that bypass the check in the IIS Middleware. ## ASP.NET Core Module with an IIS Shared Configuration diff --git a/aspnetcore/host-and-deploy/azure-iis-errors-reference.md b/aspnetcore/host-and-deploy/azure-iis-errors-reference.md index 56f258585a27..ca97e03b9d98 100644 --- a/aspnetcore/host-and-deploy/azure-iis-errors-reference.md +++ b/aspnetcore/host-and-deploy/azure-iis-errors-reference.md @@ -4,7 +4,7 @@ author: tdykstra description: Provides troubleshooting advice for the most common errors when hosting ASP.NET Core apps on Azure Apps Service and IIS. monikerRange: '>= aspnetcore-2.1' ms.author: tdykstra -ms.date: 7/23/2024 +ms.date: 04/21/2026 uid: host-and-deploy/azure-iis-errors-reference --- @@ -14,25 +14,25 @@ uid: host-and-deploy/azure-iis-errors-reference :::moniker range=">= aspnetcore-6.0" -This topic describes the most common errors and provides troubleshooting advice when hosting ASP.NET Core apps on Azure Apps Service and IIS. +This article describes the most common errors and provides troubleshooting advice when hosting ASP.NET Core apps on Azure Apps Service and IIS. See information on common app startup errors and instructions on how to diagnose errors. Collect the following information: * Browser behavior such as status code and error message. -* Application Event Log entries +* Application Event Log entries. * Azure App Service: See . * IIS 1. Select **Start** on the **Windows** menu, type *Event Viewer*, and press **Enter**. 1. After the **Event Viewer** opens, expand **Windows Logs** > **Application** in the sidebar. -* ASP.NET Core Module stdout and debug log entries +* ASP.NET Core Module stdout and debug log entries. * Azure App Service: See . - * IIS: Follow the instructions in the [Log creation and redirection](xref:host-and-deploy/aspnet-core-module#log-creation-and-redirection) and [Enhanced diagnostic logs](xref:host-and-deploy/iis/logging-and-diagnostics#enhanced-diagnostic-logs) sections of the ASP.NET Core Module topic. + * IIS: Follow the instructions in the [Log creation and redirection](xref:host-and-deploy/aspnet-core-module#log-creation-and-redirection) and [Enhanced diagnostic logs](xref:host-and-deploy/iis/logging-and-diagnostics#enhanced-diagnostic-logs) sections of the ASP.NET Core Module article. Compare error information to the following common errors. If a match is found, follow the troubleshooting advice. -The list of errors in this topic isn't exhaustive. If you encounter an error not listed here, open a new issue using the **Content feedback** button at the bottom of this topic with detailed instructions on how to reproduce the error. +The list of errors in this article isn't exhaustive. If you encounter an error not listed here, open a new issue using the **Content feedback** button at the bottom of this article with detailed instructions on how to reproduce the error. [!INCLUDE[Azure App Service Preview Notice](~/includes/azure-apps-preview-notice.md)] @@ -293,7 +293,7 @@ Troubleshooting: The process failed to start, most likely due to an app configuration or programming issue. -For more information, see the following topics: +For more information, see the following articles: * * diff --git a/aspnetcore/host-and-deploy/iis/advanced.md b/aspnetcore/host-and-deploy/iis/advanced.md index f060d199a7fb..83996b4ed479 100644 --- a/aspnetcore/host-and-deploy/iis/advanced.md +++ b/aspnetcore/host-and-deploy/iis/advanced.md @@ -5,7 +5,7 @@ description: Advanced configuration with the ASP.NET Core Module and Internet In monikerRange: '>= aspnetcore-5.0' ms.author: tdykstra ms.custom: mvc, sfi-image-nochange -ms.date: 03/07/2025 +ms.date: 04/21/2026 uid: host-and-deploy/iis/advanced --- # Advanced configuration of the ASP.NET Core Module and IIS @@ -34,7 +34,7 @@ Configure the managed stack size using the `stackSize` setting in hexadecimal by ## Disallow rotation on config -The `disallowRotationOnConfigChange` setting is intended for blue/green scenarios where a change to global config should not cause all sites to recycle. When this flag is true, only changes relevant to the site itself will cause it to recycle. For example, a site recycles if its *web.config* changes or something changes that is relevant to the site's path from IIS's perspective. But a general change to *applicationHost.config* would not cause an app to recycle. The following example sets this setting to true: +The `disallowRotationOnConfigChange` setting is intended for blue/green scenarios where a change to global config shouldn't cause all sites to recycle. When this flag is true, only changes relevant to the site itself will cause it to recycle. For example, a site recycles if its *web.config* changes or something changes that's relevant to the site's path from IIS's perspective. But a general change to *applicationHost.config* wouldn't cause an app to recycle. The following example sets this setting to true: ```xml ``` -This setting corresponds to the API +This setting corresponds to the API. ## Reduce 503 likelihood during app recycle -By default, there is a one second delay between when IIS is notified of a recycle or shutdown and when ANCM tells the managed server to initiate shutdown. The delay is configurable via the `ANCM_shutdownDelay` environment variable or by setting the `shutdownDelay` handler setting. Both values are in milliseconds. The delay is primarily to reduce the likelihood of a race where: +By default, there's a one-second delay between when IIS is notified of a recycle or shutdown and when ANCM tells the managed server to initiate shutdown. The delay is configurable via the `ANCM_shutdownDelay` environment variable or by setting the `shutdownDelay` handler setting. Both values are in milliseconds. The delay is primarily to reduce the likelihood of a race where: * IIS hasn't started queuing requests to go to the new app. * ANCM starts rejecting new requests that come into the old app. @@ -104,9 +104,9 @@ The [ASP.NET Core Data Protection stack](xref:security/data-protection/introduct If the Data Protection key ring is stored in memory when the app restarts: -* All cookie-based authentication tokens are invalidated. -* Users are required to sign in again on their next request. -* Any data protected with the key ring can no longer be decrypted. This may include [CSRF tokens](xref:security/anti-request-forgery#aspnet-core-antiforgery-configuration) and [ASP.NET Core MVC TempData cookies](xref:fundamentals/app-state#tempdata). +* All cookie-based authentication tokens are invalidated. +* Users are required to sign in again on their next request. +* Any data protected with the key ring can no longer be decrypted. This might include [CSRF tokens](xref:security/anti-request-forgery#aspnet-core-antiforgery-configuration) and [ASP.NET Core MVC TempData cookies](xref:fundamentals/app-state#tempdata). To configure data protection under IIS to persist the key ring, use **one** of the following approaches: @@ -144,7 +144,7 @@ To configure data protection under IIS to persist the key ring, use **one** of t ## IIS configuration -**Windows Server operating systems** +### Windows Server operating systems Enable the **Web Server (IIS)** server role and establish role services. @@ -164,7 +164,7 @@ Enable the **Web Server (IIS)** server role and establish role services. 1. Proceed through the **Confirmation** step to install the web server role and services. A server/IIS restart isn't required after installing the **Web Server (IIS)** role. -**Windows desktop operating systems** +### Windows desktop operating systems Enable the **IIS Management Console** and **World Wide Web Services**. @@ -196,7 +196,7 @@ Enable the **IIS Management Console** and **World Wide Web Services**. An ASP.NET Core app can be hosted as an [IIS sub-application (sub-app)](/iis/get-started/planning-your-iis-architecture/understanding-sites-applications-and-virtual-directories-on-iis#applications). The sub-app's path becomes part of the root app's URL. -Static asset links within the sub-app should use tilde-slash (`~/`) notation in MVC and Razor Pages. Tilde-slash notation triggers a [Tag Helper](xref:mvc/views/tag-helpers/intro) to prepend the sub-app's pathbase to the rendered relative link. For a sub-app at `/subapp_path`, an image linked with `src="~/image.png"` is rendered as `src="/subapp_path/image.png"`. The root app's Static File Middleware doesn't process the static file request. The request is processed by the sub-app's Static File Middleware. +Static asset links within the sub-app should use tilde-slash (`~/`) notation in MVC and Razor Pages. Tilde-slash notation triggers a [Tag Helper](xref:mvc/views/tag-helpers/intro) to prepend the sub-app's pathbase to the rendered relative link. For a sub-app at `/subapp_path`, an image linked with `src="~/image.png"` is rendered as `src="/subapp_path/image.png"`. The root app's Static File Middleware doesn't process the static file request. The sub-app's Static File Middleware processes the request. > [!NOTE] > Razor components (`.razor`) shouldn't use tilde-slash notation. For more information, see . @@ -219,10 +219,10 @@ For more information on the in-process hosting model and configuring the ASP.NET ## Application Pools -App pool isolation is determined by the hosting model: +The hosting model determines app pool isolation: -* In-process hosting: Apps are required to run in separate app pools. -* Out-of-process hosting: We recommend isolating the apps from each other by running each app in its own app pool. +* **In-process hosting**: Apps are required to run in separate app pools. +* **Out-of-process hosting**: We recommend isolating the apps from each other by running each app in its own app pool. The IIS **Add Website** dialog defaults to a single app pool per app. When a **Site name** is provided, the text is automatically transferred to the **Application pool** textbox. A new app pool is created using the site name when the site is added. @@ -240,7 +240,7 @@ If the IIS worker process requires elevated access to the app, modify the Access 1. Right-click on the directory and select **Properties**. -1. Under the **Security** tab, select the **Edit** button and then the **Add** button. +1. Under the **Security** tab, select the **Edit** button, and then the **Add** button. 1. Select the **Locations** button and make sure the system is selected. @@ -260,19 +260,19 @@ Access can also be granted at a command prompt using the **ICACLS** tool. Using ICACLS C:\sites\MyWebApp /grant "IIS AppPool\DefaultAppPool:(OI)(CI)RX" ``` -For more information, see the [icacls](/windows-server/administration/windows-commands/icacls) topic. +For more information, see the [icacls](/windows-server/administration/windows-commands/icacls) article. ## HTTP/2 support [HTTP/2](https://httpwg.org/specs/rfc7540.html) is supported with ASP.NET Core in the following IIS deployment scenarios: * In-process - * Windows Server 2016/Windows 10 or later; IIS 10 or later - * TLS 1.2 or later connection + * Windows Server 2016/Windows 10 or later; IIS 10 or later. + * TLS 1.2 or later connection. * Out-of-process - * Windows Server 2016/Windows 10 or later; IIS 10 or later + * Windows Server 2016/Windows 10 or later; IIS 10 or later. * Public-facing edge server connections use HTTP/2, but the reverse proxy connection to the [Kestrel server](xref:fundamentals/servers/kestrel) uses HTTP/1.1. - * TLS 1.2 or later connection + * TLS 1.2 or later connection. For an in-process deployment when an HTTP/2 connection is established, [`HttpRequest.Protocol`](xref:Microsoft.AspNetCore.Http.HttpRequest.Protocol*) reports `HTTP/2`. For an out-of-process deployment when an HTTP/2 connection is established, [`HttpRequest.Protocol`](xref:Microsoft.AspNetCore.Http.HttpRequest.Protocol*) reports `HTTP/1.1`. @@ -290,8 +290,8 @@ For an ASP.NET Core app that targets the .NET Framework, OPTIONS requests aren't When hosted in IIS by the ASP.NET Core Module version 2: -* [Application Initialization Module](#application-initialization-module): App's hosted [in-process](xref:host-and-deploy/iis/in-process-hosting) or [out-of-process](xref:host-and-deploy/iis/out-of-process-hosting) can be configured to start automatically on a worker process restart or server restart. -* [Idle Timeout](#idle-timeout): App's hosted [in-process](xref:host-and-deploy/iis/in-process-hosting) can be configured not to time out during periods of inactivity. +* [**Application Initialization Module**](#application-initialization-module): App's hosted [in-process](xref:host-and-deploy/iis/in-process-hosting) or [out-of-process](xref:host-and-deploy/iis/out-of-process-hosting) can be configured to start automatically on a worker process restart or server restart. +* [**Idle Timeout**](#idle-timeout): App's hosted [in-process](xref:host-and-deploy/iis/in-process-hosting) can be configured not to time out during periods of inactivity. ### Application Initialization Module @@ -356,8 +356,8 @@ To prevent apps hosted [out-of-process](xref:host-and-deploy/iis/out-of-process- ### Application Initialization Module and Idle Timeout additional resources * [IIS 8.0 Application Initialization](/iis/get-started/whats-new-in-iis-8/iis-80-application-initialization) -* [Application Initialization ``](/iis/configuration/system.webserver/applicationinitialization/). -* [Process Model Settings for an Application Pool ``](/iis/configuration/system.applicationhost/applicationpools/add/processmodel). +* [Application Initialization ``](/iis/configuration/system.webserver/applicationinitialization/) +* [Process Model Settings for an Application Pool ``](/iis/configuration/system.applicationhost/applicationpools/add/processmodel) ## Module, schema, and configuration file locations @@ -385,13 +385,13 @@ To prevent apps hosted [out-of-process](xref:host-and-deploy/iis/out-of-process- ### Schema -**IIS** +**IIS**: * `%windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml` * `%windir%\System32\inetsrv\config\schema\aspnetcore_schema_v2.xml` -**IIS Express** +**IIS Express**: * `%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml` @@ -399,11 +399,11 @@ To prevent apps hosted [out-of-process](xref:host-and-deploy/iis/out-of-process- ### Configuration -**IIS** +**IIS**: * `%windir%\System32\inetsrv\config\applicationHost.config` -**IIS Express** +**IIS Express**: * Visual Studio: `{APPLICATION ROOT}\.vs\config\applicationHost.config` @@ -430,7 +430,7 @@ When deploying apps to servers with [Web Deploy](/iis/install/installing-publish 1. Under the server's node, select **Application Pools**. -1. Right-click the site's app pool and select **Basic Settings** from the contextual menu. +1. Right-click the site's app pool, and select **Basic Settings** from the contextual menu. 1. In the **Edit Application Pool** window, set the **.NET CLR version** to **No Managed Code**: @@ -438,9 +438,9 @@ When deploying apps to servers with [Web Deploy](/iis/install/installing-publish ASP.NET Core runs in a separate process and manages the runtime. ASP.NET Core doesn't rely on loading the desktop CLR (.NET CLR). The Core Common Language Runtime (CoreCLR) for .NET is booted to host the app in the worker process. Setting the **.NET CLR version** to **No Managed Code** is optional but recommended. - * For a 32-bit (x86) [self-contained deployment](/dotnet/core/deploying/#self-contained-deployments-scd) published with a 32-bit SDK that uses the in-process hosting model, enable the Application Pool for 32-bit. In IIS Manager, navigate to **Application Pools** in the **Connections** sidebar. Select the app's Application Pool. In the **Actions** sidebar, select **Advanced Settings**. Set **Enable 32-Bit Applications** to `True`. + * For a 32-bit (x86) [self-contained deployment](/dotnet/core/deploying/#self-contained-deployments-scd) published with a 32-bit SDK that uses the in-process hosting model, enable the Application Pool for 32-bit. In IIS Manager, navigate to **Application Pools** in the **Connections** sidebar. Select the app's Application Pool. In the **Actions** sidebar, select **Advanced Settings**. Set **Enable 32-Bit Applications** to `True`. - * For a 64-bit (x64) [self-contained deployment](/dotnet/core/deploying/#self-contained-deployments-scd) that uses the in-process hosting model, disable the app pool for 32-bit (x86) processes. In IIS Manager, navigate to **Application Pools** in the **Connections** sidebar. Select the app's Application Pool. In the **Actions** sidebar, select **Advanced Settings**. Set **Enable 32-Bit Applications** to `False`. + * For a 64-bit (x64) [self-contained deployment](/dotnet/core/deploying/#self-contained-deployments-scd) that uses the in-process hosting model, disable the app pool for 32-bit (x86) processes. In IIS Manager, navigate to **Application Pools** in the **Connections** sidebar. Select the app's Application Pool. In the **Actions** sidebar, select **Advanced Settings**. Set **Enable 32-Bit Applications** to `False`. 1. Confirm the process model identity has the proper permissions. @@ -457,9 +457,9 @@ Shadow copying app assemblies to the [ASP.NET Core Module (ANCM)](xref:host-and- When an ASP.NET Core app is running on Windows, the binaries are locked so that they can't be modified or replaced. Shadow copying enables the app assemblies to be updated while the app is running by making a copy of the assemblies. -Shadow copy isn't intended to enable zero-downtime deployment, so its expected that IIS will still recycle the app, and some requests may get an [503 Service Unavailable](https://developer.mozilla.org/docs/Web/HTTP/Status/503) response. We recommend using a pattern like [blue-green deployments](https://www.martinfowler.com/bliki/BlueGreenDeployment.html) or [Azure deployment slots](/azure/app-service/deploy-best-practices#use-deployment-slots) for zero-downtime deployments. Shadow copy helps minimize downtime on deployments, but can't completely eliminate it. +Shadow copy isn't intended to enable zero-downtime deployment, so it's expected that IIS will still recycle the app, and some requests might get a [503 Service Unavailable](https://developer.mozilla.org/docs/Web/HTTP/Reference/Status/503) response. We recommend using a pattern like [blue-green deployments](https://www.martinfowler.com/bliki/BlueGreenDeployment.html) or [Azure deployment slots](/azure/app-service/deploy-best-practices#use-deployment-slots) for zero-downtime deployments. Shadow copy helps minimize downtime on deployments, but it can't completely eliminate it. -Shadow copying is enabled by customizing the ANCM handler settings in `web.config`: +Customizing the ANCM handler settings in `web.config` enables shadow copying: ``` diff --git a/aspnetcore/host-and-deploy/iis/index.md b/aspnetcore/host-and-deploy/iis/index.md index fe3c86e8c2cb..3c6e67960a08 100644 --- a/aspnetcore/host-and-deploy/iis/index.md +++ b/aspnetcore/host-and-deploy/iis/index.md @@ -5,7 +5,7 @@ description: Learn how to host ASP.NET Core apps on Windows Server Internet Info monikerRange: '>= aspnetcore-2.1' ms.author: tdykstra ms.custom: mvc, sfi-ropc-nochange -ms.date: 04/26/2024 +ms.date: 04/23/2026 uid: host-and-deploy/iis/index --- # Host ASP.NET Core on Windows with IIS @@ -14,7 +14,7 @@ uid: host-and-deploy/iis/index :::moniker range=">= aspnetcore-5.0" -Internet Information Services (IIS) is a flexible, secure and manageable Web Server for hosting web apps, including ASP.NET Core. +Internet Information Services (IIS) is a flexible, secure, and manageable Web Server for hosting web apps, including ASP.NET Core. ## Supported platforms @@ -142,7 +142,7 @@ In-process hosting is opt-in for existing apps. The ASP.NET Core web templates u `CreateDefaultBuilder` adds an instance by calling the method to boot the [CoreCLR](/dotnet/standard/glossary#coreclr) and host the app inside of the IIS worker process (`w3wp.exe` or `iisexpress.exe`). Performance tests indicate that hosting a .NET app in-process delivers significantly higher request throughput compared to hosting the app out-of-process and proxying requests to [Kestrel](xref:fundamentals/servers/kestrel). -Apps published as a single file executable can't be loaded by the in-process hosting model. +The in-process hosting model can't load apps published as a single file executable. ### Out-of-process hosting model @@ -197,7 +197,7 @@ services.Configure(options => | `AutomaticAuthentication` | `true` | If `true`, IIS Server sets the `HttpContext.User` authenticated by [Windows Authentication](xref:security/authentication/windowsauth). If `false`, the server only provides an identity for `HttpContext.User` and responds to challenges when explicitly requested by the `AuthenticationScheme`. Windows Authentication must be enabled in IIS for `AutomaticAuthentication` to function. For more information, see [Windows Authentication](xref:security/authentication/windowsauth). | | `AuthenticationDisplayName` | `null` | Sets the display name shown to users on login pages. | | `AllowSynchronousIO` | `false` | Whether synchronous I/O is allowed for the `HttpContext.Request` and the `HttpContext.Response`. | -| `MaxRequestBodySize` | `30000000` | Gets or sets the max request body size for the `HttpRequest`. Note that IIS itself has the limit `maxAllowedContentLength` which will be processed before the `MaxRequestBodySize` set in the `IISServerOptions`. Changing the `MaxRequestBodySize` won't affect the `maxAllowedContentLength`. To increase `maxAllowedContentLength`, add an entry in the `web.config` to set `maxAllowedContentLength` to a higher value. For more details, see [Configuration](/iis/configuration/system.webServer/security/requestFiltering/requestLimits/#configuration). | +| `MaxRequestBodySize` | `30000000` | Gets or sets the max request body size for the `HttpRequest`. Note that IIS itself has the limit `maxAllowedContentLength`, which will be processed before the `MaxRequestBodySize` set in the `IISServerOptions`. Changing the `MaxRequestBodySize` won't affect the `maxAllowedContentLength`. To increase `maxAllowedContentLength`, add an entry in the `web.config` to set `maxAllowedContentLength` to a higher value. For more details, see [Configuration](/iis/configuration/system.webServer/security/requestFiltering/requestLimits/#configuration). | **Out-of-process hosting model** @@ -212,7 +212,7 @@ services.Configure(options => | Option | Default | Setting | | ------------------------------ | :-----: | ------- | -| `AutomaticAuthentication` | `true` | If `true`, [IIS Integration Middleware](#enable-the-iisintegration-components) sets the `HttpContext.User` authenticated by [Windows Authentication](xref:security/authentication/windowsauth). If `false`, the middleware only provides an identity for `HttpContext.User` and responds to challenges when explicitly requested by the `AuthenticationScheme`. Windows Authentication must be enabled in IIS for `AutomaticAuthentication` to function. For more information, see the [Windows Authentication](xref:security/authentication/windowsauth) topic. | +| `AutomaticAuthentication` | `true` | If `true`, [IIS Integration Middleware](#enable-the-iisintegration-components) sets the `HttpContext.User` authenticated by [Windows Authentication](xref:security/authentication/windowsauth). If `false`, the middleware only provides an identity for `HttpContext.User` and responds to challenges when explicitly requested by the `AuthenticationScheme`. Windows Authentication must be enabled in IIS for `AutomaticAuthentication` to function. For more information, see the [Windows Authentication](xref:security/authentication/windowsauth) article. | | `AuthenticationDisplayName` | `null` | Sets the display name shown to users on login pages. | | `ForwardClientCertificate` | `true` | If `true` and the `MS-ASPNETCORE-CLIENTCERT` request header is present, the `HttpContext.Connection.ClientCertificate` is populated. | @@ -229,7 +229,7 @@ Additional configuration might be required for apps hosted behind additional pro ### `web.config` file -The `web.config` file configures the [ASP.NET Core Module](xref:host-and-deploy/aspnet-core-module). Creating, transforming, and publishing the `web.config` file is handled by an MSBuild target (`_TransformWebConfig`) when the project is published. This target is present in the Web SDK targets (`Microsoft.NET.Sdk.Web`). The SDK is set at the top of the project file: +The `web.config` file configures the [ASP.NET Core Module](xref:host-and-deploy/aspnet-core-module). An MSBuild target (`_TransformWebConfig`) handles creating, transforming, and publishing the `web.config` file when the project is published. This target is present in the Web SDK targets (`Microsoft.NET.Sdk.Web`). The SDK is set at the top of the project file: ```xml @@ -239,7 +239,7 @@ If a `web.config` file isn't present in the project, the file is created with th If a `web.config` file is present in the project, the file is transformed with the correct `processPath` and `arguments` to configure the ASP.NET Core Module and moved to published output. The transformation doesn't modify IIS configuration settings in the file. -The `web.config` file may provide additional IIS configuration settings that control active IIS modules. For information on IIS modules that are capable of processing requests with ASP.NET Core apps, see the [IIS modules](xref:host-and-deploy/iis/modules) topic. +The `web.config` file might provide additional IIS configuration settings that control active IIS modules. For information on IIS modules that are capable of processing requests with ASP.NET Core apps, see the [IIS modules](xref:host-and-deploy/iis/modules) article. To prevent the Web SDK from transforming the `web.config` file, use the `` property in the project file: @@ -249,13 +249,13 @@ To prevent the Web SDK from transforming the `web.config` file, use the ` ``` -When disabling the Web SDK from transforming the file, the `processPath` and `arguments` should be manually set by the developer. For more information, see . +When disabling the Web SDK from transforming the file, the developer should mannually set the `processPath` and `arguments`. For more information, see . ### `web.config` file location In order to set up the [ASP.NET Core Module](xref:host-and-deploy/aspnet-core-module) correctly, the `web.config` file must be present at the [content root](xref:fundamentals/index#content-root) path (typically the app base path) of the deployed app. This is the same location as the website physical path provided to IIS. The `web.config` file is required at the root of the app to enable the publishing of multiple apps using Web Deploy. -Sensitive files exist on the app's physical path, such as `{ASSEMBLY}.runtimeconfig.json`, `{ASSEMBLY}.xml` (XML Documentation comments), and `{ASSEMBLY}.deps.json`, where the placeholder `{ASSEMBLY}` is the assembly name. When the `web.config` file is present and the site starts normally, IIS doesn't serve these sensitive files if they're requested. If the `web.config` file is missing, incorrectly named, or unable to configure the site for normal startup, IIS may serve sensitive files publicly. +Sensitive files exist on the app's physical path, such as `{ASSEMBLY}.runtimeconfig.json`, `{ASSEMBLY}.xml` (XML Documentation comments), and `{ASSEMBLY}.deps.json`, where the placeholder `{ASSEMBLY}` is the assembly name. When the `web.config` file is present and the site starts normally, IIS doesn't serve these sensitive files if they're requested. If the `web.config` file is missing, incorrectly named, or unable to configure the site for normal startup, IIS might serve sensitive files publicly. **The `web.config` file must be present in the deployment at all times, correctly named, and able to configure the site for normal start up. Never remove the `web.config` file from a production deployment.** @@ -334,7 +334,7 @@ To obtain an earlier version of the installer: 1. Download the installer using the **Hosting Bundle** link. > [!WARNING] -> Some installers contain release versions that have reached their end of life (EOL) and are no longer supported by Microsoft. For more information, see the [support policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core). +> Some installers contain release versions that Microsoft no longer supports. For more information, see the [support policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core). ### Install the Hosting Bundle @@ -343,7 +343,7 @@ To obtain an earlier version of the installer: * `OPT_NO_ANCM=1`: Skip installing the ASP.NET Core Module. * `OPT_NO_RUNTIME=1`: Skip installing the .NET runtime. Used when the server only hosts [self-contained deployments (SCD)](/dotnet/core/deploying/#self-contained-deployments-scd). * `OPT_NO_SHAREDFX=1`: Skip installing the ASP.NET Shared Framework (ASP.NET runtime). Used when the server only hosts [self-contained deployments (SCD)](/dotnet/core/deploying/#self-contained-deployments-scd). - * `OPT_NO_X86=1`: Skip installing x86 runtimes. Use this parameter when you know that you won't be hosting 32-bit apps. If there's any chance that you will host both 32-bit and 64-bit apps in the future, don't use this parameter and install both runtimes. + * `OPT_NO_X86=1`: Skip installing x86 runtimes. Use this parameter when you know that you won't be hosting 32-bit apps. If there's any chance that you'll host both 32-bit and 64-bit apps in the future, don't use this parameter and install both runtimes. * `OPT_NO_SHARED_CONFIG_CHECK=1`: Disable the check for using an IIS Shared Configuration when the shared configuration (`applicationHost.config`) is on the same machine as the IIS installation. *Only available for ASP.NET Core 2.2 or later Hosting Bundler installers.* For more information, see . 1. Restarting IIS picks up a change to the system PATH, which is an environment variable, made by the installer. To restart the web server, stop the Windows Process Activation Service (WAS) and then restart the World Wide Web Publishing Service (W3SVC). Restart the system **or** execute the following commands in an elevated command shell: @@ -408,7 +408,7 @@ Deploy the app to the IIS **Physical path** folder that was established in the [ ### Web Deploy with Visual Studio -See the [Visual Studio publish profiles for ASP.NET Core app deployment](xref:host-and-deploy/visual-studio-publish-profiles#publish-profiles) topic to learn how to create a publish profile for use with Web Deploy. If the hosting provider provides a Publish Profile or support for creating one, download their profile and import it using the Visual Studio **Publish** dialog: +See the [Visual Studio publish profiles for ASP.NET Core app deployment](xref:host-and-deploy/visual-studio-publish-profiles#publish-profiles) article to learn how to create a publish profile for use with Web Deploy. If the hosting provider provides a Publish Profile or support for creating one, download their profile and import it using the Visual Studio **Publish** dialog: ![Publish dialog page](index/_static/pub-dialog.png) @@ -456,9 +456,9 @@ The [ASP.NET Core Data Protection stack](xref:security/data-protection/introduct If the key ring is stored in memory when the app restarts: -* All cookie-based authentication tokens are invalidated. -* Users are required to sign in again on their next request. -* Any data protected with the key ring can no longer be decrypted. This may include [CSRF tokens](xref:security/anti-request-forgery#aspnet-core-antiforgery-configuration) and [ASP.NET Core MVC TempData cookies](xref:fundamentals/app-state#tempdata). +* All cookie-based authentication tokens are invalidated. +* Users are required to sign in again on their next request. +* Any data protected with the key ring can no longer be decrypted. This might include [CSRF tokens](xref:security/anti-request-forgery#aspnet-core-antiforgery-configuration) and [ASP.NET Core MVC TempData cookies](xref:fundamentals/app-state#tempdata). To configure data protection under IIS to persist the key ring, use **one** of the following approaches: @@ -502,7 +502,7 @@ To configure data protection under IIS to persist the key ring, use **one** of t An ASP.NET Core app can be hosted as an [IIS sub-application (sub-app)](/iis/get-started/planning-your-iis-architecture/understanding-sites-applications-and-virtual-directories-on-iis#applications). The sub-app's path becomes part of the root app's URL. -Static asset links within the sub-app should use tilde-slash (`~/`) notation. Tilde-slash notation triggers a [Tag Helper](xref:mvc/views/tag-helpers/intro) to prepend the sub-app's pathbase to the rendered relative link. For a sub-app at `/subapp_path`, an image linked with `src="~/image.png"` is rendered as `src="/subapp_path/image.png"`. The root app's Static File Middleware doesn't process the static file request. The request is processed by the sub-app's Static File Middleware. +Static asset links within the sub-app should use tilde-slash (`~/`) notation. Tilde-slash notation triggers a [Tag Helper](xref:mvc/views/tag-helpers/intro) to prepend the sub-app's pathbase to the rendered relative link. For a sub-app at `/subapp_path`, an image linked with `src="~/image.png"` is rendered as `src="/subapp_path/image.png"`. The root app's Static File Middleware doesn't process the static file request. The sub-app's Static File Middleware processes the request. If a static asset's `src` attribute is set to an absolute path (for example, `src="/image.png"`), the link is rendered without the sub-app's pathbase. The root app's Static File Middleware attempts to serve the asset from the root app's [web root](xref:fundamentals/index#web-root), which results in a *404 - Not Found* response unless the static asset is available from the root app. @@ -522,15 +522,15 @@ For more information on the in-process hosting model and configuring the ASP.NET ## Configuration of IIS with web.config -IIS configuration is influenced by the `` section of *web.config* for IIS scenarios that are functional for ASP.NET Core apps with the ASP.NET Core Module. For example, IIS configuration is functional for dynamic compression. If IIS is configured at the server level to use dynamic compression, the `` element in the app's *web.config* file can disable it for an ASP.NET Core app. +The `` section of *web.config* for IIS scenarios that are functional for ASP.NET Core apps with the ASP.NET Core Module influences IIS configuration. For example, IIS configuration is functional for dynamic compression. If IIS is configured at the server level to use dynamic compression, the `` element in the app's *web.config* file can disable it for an ASP.NET Core app. -For more information, see the following topics: +For more information, see the following articles: * [Configuration reference for \](/iis/configuration/system.webServer/) * * -To set environment variables for individual apps running in isolated app pools (supported for IIS 10.0 or later), see the *AppCmd.exe command* section of the [Environment Variables \](/iis/configuration/system.applicationHost/applicationPools/add/environmentVariables/#appcmdexe) topic in the IIS reference documentation. +To set environment variables for individual apps running in isolated app pools (supported for IIS 10.0 or later), see the *AppCmd.exe command* section of the [Environment Variables \](/iis/configuration/system.applicationHost/applicationPools/add/environmentVariables/#appcmdexe) article in the IIS reference documentation. ### Sections that aren't used by ASP.NET Core @@ -545,7 +545,7 @@ ASP.NET Core apps are configured using other configuration providers. For more i ## Application Pools -App pool isolation is determined by the hosting model: +The hosting model determines app pool isolation: * In-process hosting: Apps are required to run in separate app pools. * Out-of-process hosting: We recommend isolating the apps from each other by running each app in its own app pool. @@ -586,7 +586,7 @@ Access can also be granted at a command prompt using the **ICACLS** tool. Using ICACLS C:\sites\MyWebApp /grant "IIS AppPool\DefaultAppPool":F ``` -For more information, see the [icacls](/windows-server/administration/windows-commands/icacls) topic. +For more information, see the [icacls](/windows-server/administration/windows-commands/icacls) article. ## HTTP/2 support @@ -798,7 +798,7 @@ services.Configure(options => | Option | Default | Setting | | ------------------------------ | :-----: | ------- | -| `AutomaticAuthentication` | `true` | If `true`, [IIS Integration Middleware](#enable-the-iisintegration-components) sets the `HttpContext.User` authenticated by [Windows Authentication](xref:security/authentication/windowsauth). If `false`, the middleware only provides an identity for `HttpContext.User` and responds to challenges when explicitly requested by the `AuthenticationScheme`. Windows Authentication must be enabled in IIS for `AutomaticAuthentication` to function. For more information, see the [Windows Authentication](xref:security/authentication/windowsauth) topic. | +| `AutomaticAuthentication` | `true` | If `true`, [IIS Integration Middleware](#enable-the-iisintegration-components) sets the `HttpContext.User` authenticated by [Windows Authentication](xref:security/authentication/windowsauth). If `false`, the middleware only provides an identity for `HttpContext.User` and responds to challenges when explicitly requested by the `AuthenticationScheme`. Windows Authentication must be enabled in IIS for `AutomaticAuthentication` to function. For more information, see the [Windows Authentication](xref:security/authentication/windowsauth) article. | | `AuthenticationDisplayName` | `null` | Sets the display name shown to users on login pages. | | `ForwardClientCertificate` | `true` | If `true` and the `MS-ASPNETCORE-CLIENTCERT` request header is present, the `HttpContext.Connection.ClientCertificate` is populated. | @@ -808,7 +808,7 @@ The [IIS Integration Middleware](#enable-the-iisintegration-components), which c ### web.config file -The *web.config* file configures the [ASP.NET Core Module](xref:host-and-deploy/aspnet-core-module). Creating, transforming, and publishing the *web.config* file is handled by an MSBuild target (`_TransformWebConfig`) when the project is published. This target is present in the Web SDK targets (`Microsoft.NET.Sdk.Web`). The SDK is set at the top of the project file: +The *web.config* file configures the [ASP.NET Core Module](xref:host-and-deploy/aspnet-core-module). MSBuild target (`_TransformWebConfig`) handles creating, transforming, and publishing the *web.config* file when the project is published. This target is present in the Web SDK targets (`Microsoft.NET.Sdk.Web`). The SDK is set at the top of the project file: ```xml @@ -818,7 +818,7 @@ If a *web.config* file isn't present in the project, the file is created with th If a *web.config* file is present in the project, the file is transformed with the correct *processPath* and *arguments* to configure the ASP.NET Core Module and moved to published output. The transformation doesn't modify IIS configuration settings in the file. -The *web.config* file may provide additional IIS configuration settings that control active IIS modules. For information on IIS modules that are capable of processing requests with ASP.NET Core apps, see the [IIS modules](xref:host-and-deploy/iis/modules) topic. +The *web.config* file might provide additional IIS configuration settings that control active IIS modules. For information on IIS modules that are capable of processing requests with ASP.NET Core apps, see the [IIS modules](xref:host-and-deploy/iis/modules) article. To prevent the Web SDK from transforming the *web.config* file, use the **\** property in the project file: @@ -828,13 +828,13 @@ To prevent the Web SDK from transforming the *web.config* file, use the **\ ``` -When disabling the Web SDK from transforming the file, the *processPath* and *arguments* should be manually set by the developer. For more information, see . +When disabling the Web SDK from transforming the file, the developer should manually set the *processPath* and *arguments*. For more information, see . ### web.config file location In order to set up the [ASP.NET Core Module](xref:host-and-deploy/aspnet-core-module) correctly, the *web.config* file must be present at the [content root](xref:fundamentals/index#content-root) path (typically the app base path) of the deployed app. This is the same location as the website physical path provided to IIS. The *web.config* file is required at the root of the app to enable the publishing of multiple apps using Web Deploy. -Sensitive files exist on the app's physical path, such as *\.runtimeconfig.json*, *\.xml* (XML Documentation comments), and *\.deps.json*. When the *web.config* file is present and the site starts normally, IIS doesn't serve these sensitive files if they're requested. If the *web.config* file is missing, incorrectly named, or unable to configure the site for normal startup, IIS may serve sensitive files publicly. +Sensitive files exist on the app's physical path, such as *\.runtimeconfig.json*, *\.xml* (XML Documentation comments), and *\.deps.json*. When the *web.config* file is present and the site starts normally, IIS doesn't serve these sensitive files if they're requested. If the *web.config* file is missing, incorrectly named, or unable to configure the site for normal startup, IIS might serve sensitive files publicly. **The *web.config* file must be present in the deployment at all times, correctly named, and able to configure the site for normal start up. Never remove the *web.config* file from a production deployment.** @@ -905,7 +905,7 @@ Install the *.NET Hosting Bundle* on the hosting system. The bundle installs the 1. Download the installer using the **Hosting Bundle** link. > [!WARNING] -> Some installers contain release versions that have reached their end of life (EOL) and are no longer supported by Microsoft. For more information, see the [support policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core). +> Some installers contain release versions that Microsoft no longer supports. For more information, see the [support policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core). ### Install the Hosting Bundle @@ -914,7 +914,7 @@ Install the *.NET Hosting Bundle* on the hosting system. The bundle installs the * `OPT_NO_ANCM=1`: Skip installing the ASP.NET Core Module. * `OPT_NO_RUNTIME=1`: Skip installing the .NET runtime. Used when the server only hosts [self-contained deployments (SCD)](/dotnet/core/deploying/#self-contained-deployments-scd). * `OPT_NO_SHAREDFX=1`: Skip installing the ASP.NET Shared Framework (ASP.NET runtime). Used when the server only hosts [self-contained deployments (SCD)](/dotnet/core/deploying/#self-contained-deployments-scd). - * `OPT_NO_X86=1`: Skip installing x86 runtimes. Use this parameter when you know that you won't be hosting 32-bit apps. If there's any chance that you will host both 32-bit and 64-bit apps in the future, don't use this parameter and install both runtimes. + * `OPT_NO_X86=1`: Skip installing x86 runtimes. Use this parameter when you know that you won't be hosting 32-bit apps. If there's any chance that you'll host both 32-bit and 64-bit apps in the future, don't use this parameter and install both runtimes. * `OPT_NO_SHARED_CONFIG_CHECK=1`: Disable the check for using an IIS Shared Configuration when the shared configuration (*applicationHost.config*) is on the same machine as the IIS installation. *Only available for ASP.NET Core 2.2 or later Hosting Bundler installers.* For more information, see . 1. Restart the system or execute the following commands in a command shell: @@ -975,7 +975,7 @@ Deploy the app to the IIS **Physical path** folder that was established in the [ ### Web Deploy with Visual Studio -See the [Visual Studio publish profiles for ASP.NET Core app deployment](xref:host-and-deploy/visual-studio-publish-profiles#publish-profiles) topic to learn how to create a publish profile for use with Web Deploy. If the hosting provider provides a Publish Profile or support for creating one, download their profile and import it using the Visual Studio **Publish** dialog: +See the [Visual Studio publish profiles for ASP.NET Core app deployment](xref:host-and-deploy/visual-studio-publish-profiles#publish-profiles) article to learn how to create a publish profile for use with Web Deploy. If the hosting provider provides a Publish Profile or support for creating one, download their profile and import it using the Visual Studio **Publish** dialog: ![Publish dialog page](index/_static/pub-dialog.png) @@ -1024,9 +1024,9 @@ The [ASP.NET Core Data Protection stack](xref:security/data-protection/introduct If the key ring is stored in memory when the app restarts: -* All cookie-based authentication tokens are invalidated. -* Users are required to sign in again on their next request. -* Any data protected with the key ring can no longer be decrypted. This may include [CSRF tokens](xref:security/anti-request-forgery#aspnet-core-antiforgery-configuration) and [ASP.NET Core MVC TempData cookies](xref:fundamentals/app-state#tempdata). +* All cookie-based authentication tokens are invalidated. +* Users are required to sign in again on their next request. +* Any data protected with the key ring can no longer be decrypted. This might include [CSRF tokens](xref:security/anti-request-forgery#aspnet-core-antiforgery-configuration) and [ASP.NET Core MVC TempData cookies](xref:fundamentals/app-state#tempdata). To configure data protection under IIS to persist the key ring, use **one** of the following approaches: @@ -1103,7 +1103,7 @@ When hosting a non-ASP.NET Core sub-app underneath an ASP.NET Core app, explicit ``` -Static asset links within the sub-app should use tilde-slash (`~/`) notation. Tilde-slash notation triggers a [Tag Helper](xref:mvc/views/tag-helpers/intro) to prepend the sub-app's pathbase to the rendered relative link. For a sub-app at `/subapp_path`, an image linked with `src="~/image.png"` is rendered as `src="/subapp_path/image.png"`. The root app's Static File Middleware doesn't process the static file request. The request is processed by the sub-app's Static File Middleware. +Static asset links within the sub-app should use tilde-slash (`~/`) notation. Tilde-slash notation triggers a [Tag Helper](xref:mvc/views/tag-helpers/intro) to prepend the sub-app's pathbase to the rendered relative link. For a sub-app at `/subapp_path`, an image linked with `src="~/image.png"` is rendered as `src="/subapp_path/image.png"`. The root app's Static File Middleware doesn't process the static file request. The sub-app's Static File Middleware processes the request. If a static asset's `src` attribute is set to an absolute path (for example, `src="/image.png"`), the link is rendered without the sub-app's pathbase. The root app's Static File Middleware attempts to serve the asset from the root app's [web root](xref:fundamentals/index#web-root), which results in a *404 - Not Found* response unless the static asset is available from the root app. @@ -1123,15 +1123,15 @@ For more information on the in-process hosting model and configuring the ASP.NET ## Configuration of IIS with web.config -IIS configuration is influenced by the `` section of *web.config* for IIS scenarios that are functional for ASP.NET Core apps with the ASP.NET Core Module. For example, IIS configuration is functional for dynamic compression. If IIS is configured at the server level to use dynamic compression, the `` element in the app's *web.config* file can disable it for an ASP.NET Core app. +The `` section of *web.config* for IIS scenarios that are functional for ASP.NET Core apps with the ASP.NET Core Module influences IIS configuration. For example, IIS configuration is functional for dynamic compression. If IIS is configured at the server level to use dynamic compression, the `` element in the app's *web.config* file can disable it for an ASP.NET Core app. -For more information, see the following topics: +For more information, see the following articles: * [Configuration reference for \](/iis/configuration/system.webServer/) * * -To set environment variables for individual apps running in isolated app pools (supported for IIS 10.0 or later), see the *AppCmd.exe command* section of the [Environment Variables \](/iis/configuration/system.applicationHost/applicationPools/add/environmentVariables/#appcmdexe) topic in the IIS reference documentation. +To set environment variables for individual apps running in isolated app pools (supported for IIS 10.0 or later), see the *AppCmd.exe command* section of the [Environment Variables \](/iis/configuration/system.applicationHost/applicationPools/add/environmentVariables/#appcmdexe) article in the IIS reference documentation. ### Sections that aren't used by ASP.NET Core @@ -1182,7 +1182,7 @@ Access can also be granted at a command prompt using the **ICACLS** tool. Using ICACLS C:\sites\MyWebApp /grant "IIS AppPool\DefaultAppPool":F ``` -For more information, see the [icacls](/windows-server/administration/windows-commands/icacls) topic. +For more information, see the [icacls](/windows-server/administration/windows-commands/icacls) article. ## HTTP/2 support @@ -1190,7 +1190,7 @@ For more information, see the [icacls](/windows-server/administration/windows-co * Windows Server 2016/Windows 10 or later; IIS 10 or later * Public-facing edge server connections use HTTP/2, but the reverse proxy connection to the [Kestrel server](xref:fundamentals/servers/kestrel) uses HTTP/1.1. -* Target framework: Not applicable to out-of-process deployments, since the HTTP/2 connection is handled entirely by IIS. +* Target framework: Not applicable to out-of-process deployments, since IIS handles the HTTP/2 connection entirely. * TLS 1.2 or later connection If an HTTP/2 connection is established, [HttpRequest.Protocol](xref:Microsoft.AspNetCore.Http.HttpRequest.Protocol*) reports `HTTP/1.1`. @@ -1220,7 +1220,7 @@ For an ASP.NET Core app that targets the .NET Framework, OPTIONS requests aren't * * * [The Official Microsoft IIS Site](https://www.iis.net/) -* [Windows Server technical content library](/windows-server/windows-server) +* [Windows Server technical content library](/windows-server) * [HTTP/2 on IIS](/iis/get-started/whats-new-in-iis-10/http2-on-iis) * diff --git a/aspnetcore/host-and-deploy/iis/web-config.md b/aspnetcore/host-and-deploy/iis/web-config.md index 429c094e7389..b952a1950590 100644 --- a/aspnetcore/host-and-deploy/iis/web-config.md +++ b/aspnetcore/host-and-deploy/iis/web-config.md @@ -5,20 +5,20 @@ description: Discover what is inside of the web.config file and how to configure monikerRange: '>= aspnetcore-5.0' ms.author: tdykstra ms.custom: mvc, sfi-ropc-nochange -ms.date: 02/07/2020 +ms.date: 04/22/2026 uid: host-and-deploy/iis/web-config --- # `web.config` file [!INCLUDE[](~/includes/not-latest-version.md)] -The `web.config` is a file that is read by IIS and the [ASP.NET Core Module](xref:host-and-deploy/aspnet-core-module) to configure an app hosted with IIS. +The `web.config` is a file that's read by IIS and the [ASP.NET Core Module](xref:host-and-deploy/aspnet-core-module) to configure an app hosted with IIS. ## `web.config` file location In order to set up the [ASP.NET Core Module](xref:host-and-deploy/aspnet-core-module) correctly, the `web.config` file must be present at the [content root](xref:fundamentals/index#content-root) path (typically the app base path) of the deployed app. This is the same location as the website physical path provided to IIS. The `web.config` file is required at the root of the app to enable the publishing of multiple apps using Web Deploy. -Sensitive files exist on the app's physical path, such as `{ASSEMBLY}.runtimeconfig.json`, `{ASSEMBLY}.xml` (XML Documentation comments), and `{ASSEMBLY}.deps.json`, where the placeholder `{ASSEMBLY}` is the assembly name. When the `web.config` file is present and the site starts normally, IIS doesn't serve these sensitive files if they're requested. If the `web.config` file is missing, incorrectly named, or unable to configure the site for normal startup, IIS may serve sensitive files publicly. +Sensitive files exist on the app's physical path, such as `{ASSEMBLY}.runtimeconfig.json`, `{ASSEMBLY}.xml` (XML Documentation comments), and `{ASSEMBLY}.deps.json`, where the placeholder `{ASSEMBLY}` is the assembly name. When the `web.config` file is present and the site starts normally, IIS doesn't serve these sensitive files if they're requested. If the `web.config` file is missing, incorrectly named, or unable to configure the site for normal startup, IIS might serve sensitive files publicly. **The `web.config` file must be present in the deployment at all times, correctly named, and able to configure the site for normal start up. Never remove the `web.config` file from a production deployment.** @@ -26,9 +26,9 @@ If a `web.config` file isn't present in the project, the file is created with th If a `web.config` file is present in the project, the file is transformed with the correct `processPath` and `arguments` to configure the ASP.NET Core Module and moved to published output. The transformation doesn't modify IIS configuration settings in the file. -The `web.config` file may provide additional IIS configuration settings that control active IIS modules. For information on IIS modules that are capable of processing requests with ASP.NET Core apps, see the [IIS modules](xref:host-and-deploy/iis/modules) topic. +The `web.config` file might provide additional IIS configuration settings that control active IIS modules. For information on IIS modules that are capable of processing requests with ASP.NET Core apps, see the [IIS modules](xref:host-and-deploy/iis/modules) article. -Creating, transforming, and publishing the `web.config` file is handled by an MSBuild target (`_TransformWebConfig`) when the project is published. This target is present in the Web SDK targets (`Microsoft.NET.Sdk.Web`). The SDK is set at the top of the project file: +An MSBuild target (`_TransformWebConfig`) handles creating, transforming, and publishing the `web.config` file when the project is published. This target is present in the Web SDK targets (`Microsoft.NET.Sdk.Web`). The SDK is set at the top of the project file: ```xml @@ -42,13 +42,13 @@ To prevent the Web SDK from transforming the `web.config` file, use the ` ``` -When disabling the Web SDK from transforming the file, the `processPath` and `arguments` should be manually set by the developer. For more information, see . +When disabling the Web SDK from transforming the file, the developer should manually set `processPath` and `arguments`. For more information, see . ## Configuration of ASP.NET Core Module with `web.config` The ASP.NET Core Module is configured with the `aspNetCore` section of the `system.webServer` node in the site's `web.config` file. -The following `web.config` file is published for a [framework-dependent deployment](/dotnet/articles/core/deploying/#framework-dependent-deployments-fdd) and configures the ASP.NET Core Module to handle site requests: +The following `web.config` file is published for a [framework-dependent deployment](/dotnet/core/deploying/#framework-dependent-deployments-fdd) and configures the ASP.NET Core Module to handle site requests: ```xml @@ -68,7 +68,7 @@ The following `web.config` file is published for a [framework-dependent deployme ``` -The following `web.config` is published for a [self-contained deployment](/dotnet/articles/core/deploying/#self-contained-deployments-scd): +The following `web.config` is published for a [self-contained deployment](/dotnet/core/deploying/#self-contained-deployments-scd): ```xml @@ -89,7 +89,7 @@ The following `web.config` is published for a [self-contained deployment](/dotne The property is set to `false` to indicate that the settings specified within the [``](/iis/manage/managing-your-configuration-settings/understanding-iis-configuration-delegation#the-concept-of-location) element aren't inherited by apps that reside in a subdirectory of the app. -When an app is deployed to [Azure App Service](https://azure.microsoft.com/services/app-service/), the `stdoutLogFile` path is set to `\\?\%home%\LogFiles\stdout`. The path saves stdout logs to the `LogFiles` folder, which is a location automatically created by the service. +When an app is deployed to [Azure App Service](https://azure.microsoft.com/products/app-service/), the `stdoutLogFile` path is set to `\\?\%home%\LogFiles\stdout`. The path saves stdout logs to the `LogFiles` folder, which is a location automatically created by the service. For information on IIS sub-application configuration, see . @@ -108,13 +108,13 @@ For information on IIS sub-application configuration, see Optional integer attribute.

Duration in seconds that the module waits for the executable to gracefully shutdown when the `app_offline.htm` file is detected.

| Default: `10`
Min: `0`
Max: `600` | | `startupTimeLimit` |

Optional integer attribute.

Duration in seconds that the module waits for the executable to start a process listening on the port. If this time limit is exceeded, the module kills the process.

When hosting *in-process*: The process is **not** restarted and does **not** use the `rapidFailsPerMinute` setting.

When hosting *out-of-process*: 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.

A value of 0 (zero) is **not** considered an infinite timeout.

| Default: `120`
Min: `0`
Max: `3600` | | `stdoutLogEnabled` |

Optional Boolean attribute.

If true, `stdout` and `stderr` for the process specified in `processPath` are redirected to the file specified in `stdoutLogFile`.

| `false` | -| `stdoutLogFile` |

Optional string attribute.

Specifies the relative or absolute file path for which `stdout` and `stderr` from the process specified in `processPath` are logged. Relative paths are relative to the root of the site. Any path starting with `.` are relative to the site root and all other paths are treated as absolute paths. Any folders provided in the path are created by the module when the log file is created. Using underscore delimiters, a timestamp, process ID, and file extension (`.log`) are added to the last segment of the `stdoutLogFile` path. 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 February 5, 2018 at 19:41:32 with a process ID of 1934.

| `aspnetcore-stdout` | +| `stdoutLogFile` |

Optional string attribute.

Specifies the relative or absolute file path for which `stdout` and `stderr` from the process specified in `processPath` are logged. Relative paths are relative to the root of the site. Any path starting with `.` are relative to the site root and all other paths are treated as absolute paths. The module creates any folders provided in the path when the log file is created. Using underscore delimiters, a timestamp, process ID, and file extension (`.log`) are added to the last segment of the `stdoutLogFile` path. 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 February 5, 2018 at 19:41:32 with a process ID of 1934.

| `aspnetcore-stdout` | ### Set environment variables Environment variables can be specified for the process in the `processPath` attribute. Specify an environment variable with the `` child element of an `` collection element. Environment variables set in this section take precedence over system environment variables. -The following example sets two environment variables in `web.config`. `ASPNETCORE_ENVIRONMENT` configures the app's environment to `Development`. A developer may temporarily set this value in the `web.config` file in order to force the [Developer Exception Page](xref:fundamentals/error-handling) to load when debugging an app exception. `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. +The following example sets two environment variables in `web.config`. `ASPNETCORE_ENVIRONMENT` configures the app's environment to `Development`. A developer might temporarily set this value in the `web.config` file in order to force the [Developer Exception Page](xref:fundamentals/error-handling) to load when debugging an app exception. `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. ```xml Development > > ``` - +> > [!WARNING] > 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. @@ -145,13 +145,13 @@ The following example sets two environment variables in `web.config`. `ASPNETCOR IIS configuration is influenced by the `` section of `web.config` for IIS scenarios that are functional for ASP.NET Core apps with the ASP.NET Core Module. For example, IIS configuration is functional for dynamic compression. If IIS is configured at the server level to use dynamic compression, the `` element in the app's `web.config` file can disable it for an ASP.NET Core app. -For more information, see the following topics: +For more information, see the following articles: * [Configuration reference for ``](/iis/configuration/system.webServer/) * * -To set environment variables for individual apps running in isolated app pools (supported for IIS 10.0 or later), see the *`AppCmd.exe` command* section of the [Environment Variables ``](/iis/configuration/system.applicationHost/applicationPools/add/environmentVariables/#appcmdexe) topic in the IIS reference documentation. +To set environment variables for individual apps running in isolated app pools (supported for IIS 10.0 or later), see the *`AppCmd.exe` command* section of the [Environment Variables ``](/iis/configuration/system.applicationHost/applicationPools/add/environmentVariables/#appcmdexe) article in the IIS reference documentation. ## Configuration sections of `web.config` diff --git a/aspnetcore/host-and-deploy/index.md b/aspnetcore/host-and-deploy/index.md index 864365b7145f..c587188c65da 100644 --- a/aspnetcore/host-and-deploy/index.md +++ b/aspnetcore/host-and-deploy/index.md @@ -5,7 +5,7 @@ description: Learn how to set up hosting environments and deploy ASP.NET Core ap monikerRange: '>= aspnetcore-2.1' ms.author: tdykstra ms.custom: mvc -ms.date: 02/07/2020 +ms.date: 04/22/2026 uid: host-and-deploy/index --- # Host and deploy ASP.NET Core @@ -83,7 +83,7 @@ Additional configuration might be required for apps hosted behind proxy servers Deployment often requires additional tasks besides copying the output from [dotnet publish](/dotnet/core/tools/dotnet-publish) to a server. For example, extra files might be required or excluded from the *publish* folder. Visual Studio uses [MSBuild](/visualstudio/msbuild/msbuild) for web deployment, and MSBuild can be customized to do many other tasks during deployment. For more information, see and the [Using MSBuild and Team Foundation Build](https://www.microsoftpressstore.com/store/inside-the-microsoft-build-engine-using-msbuild-and-9780735645240) book. -By using [the Publish Web feature](xref:tutorials/publish-to-azure-webapp-using-vs) apps can be deployed directly from Visual Studio to the Azure App Service. Azure DevOps Services supports [continuous deployment to Azure App Service](/azure/devops/pipelines/targets/webapp). For more information, see [DevOps for ASP.NET Core Developers](/dotnet/architecture/devops-for-aspnet-developers). +By using [the Publish Web feature](xref:tutorials/publish-to-azure-webapp-using-vs), apps can be deployed directly from Visual Studio to the Azure App Service. Azure DevOps Services supports [continuous deployment to Azure App Service](/azure/devops/pipelines/targets/webapp). For more information, see [DevOps for ASP.NET Core Developers](/dotnet/architecture/devops-for-aspnet-developers). ## Publish to Azure diff --git a/aspnetcore/host-and-deploy/proxy-load-balancer.md b/aspnetcore/host-and-deploy/proxy-load-balancer.md index d1e80370614b..0def1c2fee5c 100644 --- a/aspnetcore/host-and-deploy/proxy-load-balancer.md +++ b/aspnetcore/host-and-deploy/proxy-load-balancer.md @@ -5,7 +5,7 @@ description: Learn about configuration for apps hosted behind proxy servers and monikerRange: '>= aspnetcore-3.1' ms.author: tdykstra ms.custom: mvc, linux-related-content -ms.date: 1/07/2022 +ms.date: 04/23/2026 uid: host-and-deploy/proxy-load-balancer --- # Configure ASP.NET Core to work with proxy servers and load balancers @@ -21,7 +21,7 @@ In the recommended configuration for ASP.NET Core, the app is hosted using . @@ -31,17 +31,17 @@ By convention, proxies forward information in HTTP headers. | Header | Description | | ------ | ----------- | -| [`X-Forwarded-For`](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-For) (XFF) | Holds information about the client that initiated the request and subsequent proxies in a chain of proxies. This parameter may contain IP addresses and, optionally, port numbers. In a chain of proxy servers, the first parameter indicates the client where the request was first made. Subsequent proxy identifiers follow. The last proxy in the chain isn't in the list of parameters. The last proxy's IP address, and optionally a port number, are available as the remote IP address at the transport layer. | -| [`X-Forwarded-Proto`](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto) (XFP)| The value of the originating scheme, HTTP or HTTPS. The value may also be a list of schemes if the request has traversed multiple proxies. | -| [`X-Forwarded-Host`](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Host) (XFH) | The original value of the Host header field. Usually, proxies don't modify the Host header. See [Microsoft Security Advisory CVE-2018-0787](https://github.com/aspnet/Announcements/issues/295) for information on an elevation-of-privileges vulnerability that affects systems where the proxy doesn't validate or restrict Host headers to known good values. | +| [`X-Forwarded-For`](https://developer.mozilla.org/docs/Web/HTTP/Reference/Headers/X-Forwarded-For) (XFF) | Holds information about the client that initiated the request and subsequent proxies in a chain of proxies. This parameter might contain IP addresses and, optionally, port numbers. In a chain of proxy servers, the first parameter indicates the client where the request was first made. Subsequent proxy identifiers follow. The last proxy in the chain isn't in the list of parameters. The last proxy's IP address, and optionally a port number, are available as the remote IP address at the transport layer. | +| [`X-Forwarded-Proto`](https://developer.mozilla.org/docs/Web/HTTP/Reference/Headers/X-Forwarded-Proto) (XFP) | The value of the originating scheme, HTTP, or HTTPS. The value might also be a list of schemes if the request has traversed multiple proxies. | +| [`X-Forwarded-Host`](https://developer.mozilla.org/docs/Web/HTTP/Reference/Headers/X-Forwarded-Host) (XFH) | The original value of the Host header field. Usually, proxies don't modify the Host header. See [Microsoft Security Advisory CVE-2018-0787](https://github.com/aspnet/Announcements/issues/295) for information on an elevation-of-privileges vulnerability that affects systems where the proxy doesn't validate or restrict Host headers to known good values. | | `X-Forwarded-Prefix` | The original base path requested by the client. This header can be useful for applications to correctly generate URLs, redirects, or links back to the client. | The [Forwarded Headers Middleware](https://github.com/dotnet/aspnetcore/blob/main/src/Middleware/HttpOverrides/src/ForwardedHeadersOptions.cs), , reads these headers and fills in the associated fields on . The middleware updates: -* [`HttpContext.Connection.RemoteIpAddress`](xref:Microsoft.AspNetCore.Http.ConnectionInfo.RemoteIpAddress): Set using the `X-Forwarded-For` header value. Additional settings influence how the middleware sets `RemoteIpAddress`. For details, see the [Forwarded Headers Middleware options](#forwarded-headers-middleware-options). The consumed values are removed from `X-Forwarded-For`, and the old value of [`HttpContext.Connection.RemoteIpAddress`](xref:Microsoft.AspNetCore.Http.ConnectionInfo.RemoteIpAddress) is persisted in `X-Original-For`. Note: This process may be repeated several times if there are multiple values in `X-Forwarded-For/Proto/Host/Prefix`, resulting in several values moved to `X-Original-*`, including the original `RemoteIpAddress/Host/Scheme/PathBase`. -* [`HttpContext.Request.Scheme`](xref:Microsoft.AspNetCore.Http.HttpRequest.Scheme): Set using the [`X-Forwarded-Proto`](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto) header value. The consumed value is removed from `X-Forwarded-Proto`, and the old value of [`HttpContext.Request.Scheme`](xref:Microsoft.AspNetCore.Http.HttpRequest.Scheme) is persisted in `X-Original-Proto`. +* [`HttpContext.Connection.RemoteIpAddress`](xref:Microsoft.AspNetCore.Http.ConnectionInfo.RemoteIpAddress): Set using the `X-Forwarded-For` header value. Additional settings influence how the middleware sets `RemoteIpAddress`. For details, see the [Forwarded Headers Middleware options](#forwarded-headers-middleware-options). The consumed values are removed from `X-Forwarded-For`, and the old value of [`HttpContext.Connection.RemoteIpAddress`](xref:Microsoft.AspNetCore.Http.ConnectionInfo.RemoteIpAddress) is persisted in `X-Original-For`. Note: This process might be repeated several times if there are multiple values in `X-Forwarded-For/Proto/Host/Prefix`, resulting in several values moved to `X-Original-*`, including the original `RemoteIpAddress/Host/Scheme/PathBase`. +* [`HttpContext.Request.Scheme`](xref:Microsoft.AspNetCore.Http.HttpRequest.Scheme): Set using the [`X-Forwarded-Proto`](https://developer.mozilla.org/docs/Web/HTTP/Reference/Headers/X-Forwarded-Proto) header value. The consumed value is removed from `X-Forwarded-Proto`, and the old value of [`HttpContext.Request.Scheme`](xref:Microsoft.AspNetCore.Http.HttpRequest.Scheme) is persisted in `X-Original-Proto`. * [`HttpContext.Request.Host`](xref:Microsoft.AspNetCore.Http.HttpRequest.Host): Set using the `X-Forwarded-Host` header value. The consumed value is removed from `X-Forwarded-Host`, and the old value of [`HttpContext.Request.Host`](xref:Microsoft.AspNetCore.Http.HttpRequest.Host) is persisted in `X-Original-Host`. * [`HttpContext.Request.PathBase`](xref:Microsoft.AspNetCore.Http.HttpRequest.PathBase): Set using the `X-Forwarded-Prefix` header value. The consumed value is removed from `X-Forwarded-Prefix`, and the old value of [`HttpContext.Request.PathBase`](xref:Microsoft.AspNetCore.Http.HttpRequest.PathBase) is persisted in `X-Original-Prefix`. @@ -49,22 +49,22 @@ For more information on the preceding, see [this GitHub issue](https://github.co Forwarded Headers Middleware [default settings](#forwarded-headers-middleware-options) can be configured. For the default settings: -* There is only ***one proxy*** between the app and the source of the requests. +* There's only ***one proxy*** between the app and the source of the requests. * Only loopback addresses are configured for known proxies and known networks. -* The forwarded headers are named [`X-Forwarded-For`](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-For), [`X-Forwarded-Proto`](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), [`X-Forwarded-Host`](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Host) and `X-Forwarded-Prefix`. -* The `ForwardedHeaders` value is `ForwardedHeaders.None`, the desired forwarders must be set here to enable the middleware. +* The forwarded headers are named [`X-Forwarded-For`](https://developer.mozilla.org/docs/Web/HTTP/Reference/Headers/X-Forwarded-For), [`X-Forwarded-Proto`](https://developer.mozilla.org/docs/Web/HTTP/Reference/Headers/X-Forwarded-Proto), [`X-Forwarded-Host`](https://developer.mozilla.org/docs/Web/HTTP/Reference/Headers/X-Forwarded-Host) and `X-Forwarded-Prefix`. +* The `ForwardedHeaders` value is `ForwardedHeaders.None`. The desired forwarders must be set here to enable the middleware. Not all network appliances add the `X-Forwarded-For` and `X-Forwarded-Proto` headers without additional configuration. Consult your appliance manufacturer's guidance if proxied requests don't contain these headers when they reach the app. If the appliance uses different header names than `X-Forwarded-For` and `X-Forwarded-Proto`, set the and options to match the header names used by the appliance. For more information, see [Forwarded Headers Middleware options](#forwarded-headers-middleware-options) and [Configuration for a proxy that uses different header names](#configuration-for-a-proxy-that-uses-different-header-names). ## IIS/IIS Express and ASP.NET Core Module -Forwarded Headers Middleware is enabled by default by [IIS Integration Middleware](xref:host-and-deploy/iis/index#enable-the-iisintegration-components) when the app is hosted [out-of-process](xref:host-and-deploy/iis/index#out-of-process-hosting-model) behind IIS and the . Forwarded Headers Middleware is activated to run first in the middleware pipeline with a restricted configuration specific to the ASP.NET Core Module. The restricted configuration is due to trust concerns with forwarded headers, for example, [IP spoofing](https://www.iplocation.net/ip-spoofing). The middleware is configured to forward the [`X-Forwarded-For`](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-For) and [`X-Forwarded-Proto`](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto) headers and is restricted to a single localhost proxy. If additional configuration is required, see the [Forwarded Headers Middleware options](#forwarded-headers-middleware-options). +[IIS Integration Middleware](xref:host-and-deploy/iis/index#enable-the-iisintegration-components) enables Forwarded Headers Middleware by default when the app is hosted [out-of-process](xref:host-and-deploy/iis/index#out-of-process-hosting-model) behind IIS and the . Forwarded Headers Middleware is activated to run first in the middleware pipeline with a restricted configuration specific to the ASP.NET Core Module. The restricted configuration is due to trust concerns with forwarded headers, for example, [IP spoofing](https://www.iplocation.net/ip-spoofing). The middleware is configured to forward the [`X-Forwarded-For`](https://developer.mozilla.org/docs/Web/HTTP/Reference/Headers/X-Forwarded-For) and [`X-Forwarded-Proto`](https://developer.mozilla.org/docs/Web/HTTP/Reference/Headers/X-Forwarded-Proto) headers and is restricted to a single localhost proxy. If additional configuration is required, see the [Forwarded Headers Middleware options](#forwarded-headers-middleware-options). ## Other proxy server and load balancer scenarios Outside of using [IIS Integration](xref:host-and-deploy/iis/index#enable-the-iisintegration-components) when hosting [out-of-process](xref:host-and-deploy/iis/index#out-of-process-hosting-model), [Forwarded Headers Middleware](https://github.com/dotnet/aspnetcore/blob/main/src/Middleware/HttpOverrides/src/ForwardedHeadersOptions.cs) isn't enabled by default. Forwarded Headers Middleware must be enabled for an app to process forwarded headers with . After enabling the middleware if no are specified to the middleware, the default [ForwardedHeadersOptions.ForwardedHeaders](xref:Microsoft.AspNetCore.Builder.ForwardedHeadersOptions.ForwardedHeaders) are [ForwardedHeaders.None](xref:Microsoft.AspNetCore.HttpOverrides.ForwardedHeaders). -Configure the middleware with to forward the [`X-Forwarded-For`](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-For) and [`X-Forwarded-Proto`](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto) headers. +Configure the middleware with to forward the [`X-Forwarded-For`](https://developer.mozilla.org/docs/Web/HTTP/Reference/Headers/X-Forwarded-For) and [`X-Forwarded-Proto`](https://developer.mozilla.org/docs/Web/HTTP/Reference/Headers/X-Forwarded-Proto) headers. ### Forwarded Headers Middleware order @@ -99,7 +99,7 @@ To forward the `X-Forwarded-For` and `X-Forwarded-Proto` headers, see | Restricts hosts by the `X-Forwarded-Host` header to the values provided.
  • Values are compared using ordinal-ignore-case.
  • Port numbers must be excluded.
  • If the list is empty, all hosts are allowed.
  • A top-level wildcard `*` allows all non-empty hosts.
  • Subdomain wildcards are permitted but don't match the root domain. For example, `*.contoso.com` matches the subdomain `foo.contoso.com` but not the root domain `contoso.com`.
  • Unicode host names are allowed but are converted to [Punycode](https://tools.ietf.org/html/rfc3492) for matching.
  • [IPv6 addresses](https://tools.ietf.org/html/rfc4291) must include bounding brackets and be in [conventional form](https://tools.ietf.org/html/rfc4291#section-2.2) (for example, `[ABCD:EF01:2345:6789:ABCD:EF01:2345:6789]`). IPv6 addresses aren't special-cased to check for logical equality between different formats, and no canonicalization is performed.
  • Failure to restrict the allowed hosts may allow a cyberattacker to spoof links generated by the service.
The default value is an empty `IList`. | +| | Restricts hosts by the `X-Forwarded-Host` header to the values provided.
  • Values are compared using ordinal-ignore-case.
  • Port numbers must be excluded.
  • If the list is empty, all hosts are allowed.
  • A top-level wildcard `*` allows all non-empty hosts.
  • Subdomain wildcards are permitted but don't match the root domain. For example, `*.contoso.com` matches the subdomain `foo.contoso.com` but not the root domain `contoso.com`.
  • Unicode host names are allowed but are converted to [Punycode](https://datatracker.ietf.org/doc/html/rfc3492) for matching.
  • [IPv6 addresses](https://datatracker.ietf.org/doc/html/rfc4291) must include bounding brackets and be in [conventional form](https://datatracker.ietf.org/doc/html/rfc4291#section-2.2) (for example, `[ABCD:EF01:2345:6789:ABCD:EF01:2345:6789]`). IPv6 addresses aren't special-cased to check for logical equality between different formats, and no canonicalization is performed.
  • Failure to restrict the allowed hosts might allow a cyberattacker to spoof links generated by the service.
The default value is an empty `IList`. | | | Use the header specified by this property instead of the one specified by [ForwardedHeadersDefaults.XForwardedForHeaderName](xref:Microsoft.AspNetCore.HttpOverrides.ForwardedHeadersDefaults.XForwardedForHeaderName). This option is used when the proxy/forwarder doesn't use the `X-Forwarded-For` header but uses some other header to forward the information.

The default is `X-Forwarded-For`. | | | Identifies which forwarders should be processed. See the [ForwardedHeaders Enum](xref:Microsoft.AspNetCore.HttpOverrides.ForwardedHeaders) for the list of fields that apply. Typical values assigned to this property are `ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto`.

The default value is [ForwardedHeaders.None](xref:Microsoft.AspNetCore.HttpOverrides.ForwardedHeaders). | | | Use the header specified by this property instead of the one specified by [ForwardedHeadersDefaults.XForwardedHostHeaderName](xref:Microsoft.AspNetCore.HttpOverrides.ForwardedHeadersDefaults.XForwardedHostHeaderName). This option is used when the proxy/forwarder doesn't use the `X-Forwarded-Host` header but uses some other header to forward the information.

The default is `X-Forwarded-Host`. | @@ -137,7 +137,7 @@ app.UseRouting(); ``` > [!NOTE] -> When using (see ), [`app.UseRouting`](xref:Microsoft.AspNetCore.Builder.EndpointRoutingApplicationBuilderExtensions.UseRouting%2A) must be called after `UsePathBase` so that the routing middleware can observe the modified path before matching routes. Otherwise, routes are matched before the path is rewritten by `UsePathBase` as described in and . +> When using (see ), [`app.UseRouting`](xref:Microsoft.AspNetCore.Builder.EndpointRoutingApplicationBuilderExtensions.UseRouting%2A) must be called after `UsePathBase` so that the routing middleware can observe the modified path before matching routes. Otherwise, routes are matched before `UsePathBase` rewrites the path as described in and . The original path and path base are reapplied when the middleware is called again in reverse. For more information on middleware order processing, see . @@ -173,7 +173,7 @@ If the proxy doesn't use headers named `X-Forwarded-For` and `X-Forwarded-Proto` ## Forward the scheme for Linux and non-IIS reverse proxies -Apps that call and put a site into an infinite loop if deployed to an Azure Linux App Service, Azure Linux virtual machine (VM), or behind any other reverse proxy besides IIS. TLS is terminated by the reverse proxy, and Kestrel isn't made aware of the correct request scheme. OAuth and OIDC also fail in this configuration because they generate incorrect redirects. adds and configures Forwarded Headers Middleware when running behind IIS, but there's no matching automatic configuration for Linux (Apache or Nginx integration). +Apps that call and put a site into an infinite loop if deployed to an Azure Linux App Service, Azure Linux virtual machine (VM), or behind any other reverse proxy besides IIS. The reverse proxy terminates TLS, and Kestrel isn't made aware of the correct request scheme. OAuth and OIDC also fail in this configuration because they generate incorrect redirects. adds and configures Forwarded Headers Middleware when running behind IIS, but there's no matching automatic configuration for Linux (Apache or Nginx integration). To forward the scheme from the proxy in non-IIS scenarios, enable the Forwarded Headers Middleware by setting `ASPNETCORE_FORWARDEDHEADERS_ENABLED` to `true`. Warning: This flag uses settings designed for cloud environments and doesn't enable features such as the [`KnownProxies option`](#forwarded-headers-middleware-options) to restrict which IPs forwarders are accepted from. @@ -252,7 +252,7 @@ In the recommended configuration for ASP.NET Core, the app is hosted using IIS/A * When HTTPS requests are proxied over HTTP, the original scheme (HTTPS) is lost and must be forwarded in a header. * Because an app receives a request from the proxy and not its true source on the Internet or corporate network, the originating client IP address must also be forwarded in a header. -This information may be important in request processing, for example in redirects, authentication, link generation, policy evaluation, and client geolocation. +This information might be important in request processing, for example in redirects, authentication, link generation, policy evaluation, and client geolocation. ## Forwarded headers @@ -260,8 +260,8 @@ By convention, proxies forward information in HTTP headers. | Header | Description | | ------ | ----------- | -| X-Forwarded-For | Holds information about the client that initiated the request and subsequent proxies in a chain of proxies. This parameter may contain IP addresses (and, optionally, port numbers). In a chain of proxy servers, the first parameter indicates the client where the request was first made. Subsequent proxy identifiers follow. The last proxy in the chain isn't in the list of parameters. The last proxy's IP address, and optionally a port number, are available as the remote IP address at the transport layer. | -| X-Forwarded-Proto | The value of the originating scheme (HTTP/HTTPS). The value may also be a list of schemes if the request has traversed multiple proxies. | +| X-Forwarded-For | Holds information about the client that initiated the request and subsequent proxies in a chain of proxies. This parameter might contain IP addresses (and, optionally, port numbers). In a chain of proxy servers, the first parameter indicates the client where the request was first made. Subsequent proxy identifiers follow. The last proxy in the chain isn't in the list of parameters. The last proxy's IP address, and optionally a port number, are available as the remote IP address at the transport layer. | +| X-Forwarded-Proto | The value of the originating scheme (HTTP/HTTPS). The value might also be a list of schemes if the request has traversed multiple proxies. | | X-Forwarded-Host | The original value of the Host header field. Usually, proxies don't modify the Host header. See [Microsoft Security Advisory CVE-2018-0787](https://github.com/aspnet/Announcements/issues/295) for information on an elevation-of-privileges vulnerability that affects systems where the proxy doesn't validate or restrict Host headers to known good values. | The Forwarded Headers Middleware (), reads these headers and fills in the associated fields on . @@ -276,7 +276,7 @@ For more information on the preceding, see [this GitHub issue](https://github.co Forwarded Headers Middleware [default settings](#forwarded-headers-middleware-options) can be configured. For the default settings: -* There is only *one proxy* between the app and the source of the requests. +* There's only *one proxy* between the app and the source of the requests. * Only loopback addresses are configured for known proxies and known networks. * The forwarded headers are named `X-Forwarded-For` and `X-Forwarded-Proto`. * The `ForwardedHeaders` value is `ForwardedHeaders.None`, the desired forwarders must be set here to enable the middleware. @@ -285,7 +285,7 @@ Not all network appliances add the `X-Forwarded-For` and `X-Forwarded-Proto` hea ## IIS/IIS Express and ASP.NET Core Module -Forwarded Headers Middleware is enabled by default by [IIS Integration Middleware](xref:host-and-deploy/iis/index#enable-the-iisintegration-components) when the app is hosted [out-of-process](xref:host-and-deploy/iis/index#out-of-process-hosting-model) behind IIS and the ASP.NET Core Module. Forwarded Headers Middleware is activated to run first in the middleware pipeline with a restricted configuration specific to the ASP.NET Core Module due to trust concerns with forwarded headers (for example, [IP spoofing](https://www.iplocation.net/ip-spoofing)). The middleware is configured to forward the `X-Forwarded-For` and `X-Forwarded-Proto` headers and is restricted to a single localhost proxy. If additional configuration is required, see the [Forwarded Headers Middleware options](#forwarded-headers-middleware-options). +[IIS Integration Middleware](xref:host-and-deploy/iis/index#enable-the-iisintegration-components) enables Forwarded Headers Middleware by default when the app is hosted [out-of-process](xref:host-and-deploy/iis/index#out-of-process-hosting-model) behind IIS and the ASP.NET Core Module. Forwarded Headers Middleware is activated to run first in the middleware pipeline with a restricted configuration specific to the ASP.NET Core Module due to trust concerns with forwarded headers (for example, [IP spoofing](https://www.iplocation.net/ip-spoofing)). The middleware is configured to forward the `X-Forwarded-For` and `X-Forwarded-Proto` headers and is restricted to a single localhost proxy. If additional configuration is required, see the [Forwarded Headers Middleware options](#forwarded-headers-middleware-options). ## Other proxy server and load balancer scenarios @@ -310,7 +310,7 @@ Alternatively, call `UseForwardedHeaders` before diagnostics: ## Nginx configuration -To forward the `X-Forwarded-For` and `X-Forwarded-Proto` headers, see . For more information, see [NGINX: Using the Forwarded header](https://www.nginx.com/resources/wiki/start/topics/examples/forwarded/). +To forward the `X-Forwarded-For` and `X-Forwarded-Proto` headers, see . For more information, see [NGINX: Using the Forwarded header](https://docs.nginx.com/nginx-gateway-fabric/traffic-management/request-response-headers/). ## Apache configuration @@ -335,7 +335,7 @@ services.Configure(options => | Option | Description | | ------ | ----------- | -| | Restricts hosts by the `X-Forwarded-Host` header to the values provided.
  • Values are compared using ordinal-ignore-case.
  • Port numbers must be excluded.
  • If the list is empty, all hosts are allowed.
  • A top-level wildcard `*` allows all non-empty hosts.
  • Subdomain wildcards are permitted but don't match the root domain. For example, `*.contoso.com` matches the subdomain `foo.contoso.com` but not the root domain `contoso.com`.
  • Unicode host names are allowed but are converted to [Punycode](https://tools.ietf.org/html/rfc3492) for matching.
  • [IPv6 addresses](https://tools.ietf.org/html/rfc4291) must include bounding brackets and be in [conventional form](https://tools.ietf.org/html/rfc4291#section-2.2) (for example, `[ABCD:EF01:2345:6789:ABCD:EF01:2345:6789]`). IPv6 addresses aren't special-cased to check for logical equality between different formats, and no canonicalization is performed.
  • Failure to restrict the allowed hosts may allow a cyberattacker to spoof links generated by the service.
The default value is an empty `IList`. | +| | Restricts hosts by the `X-Forwarded-Host` header to the values provided.
  • Values are compared using ordinal-ignore-case.
  • Port numbers must be excluded.
  • If the list is empty, all hosts are allowed.
  • A top-level wildcard `*` allows all non-empty hosts.
  • Subdomain wildcards are permitted but don't match the root domain. For example, `*.contoso.com` matches the subdomain `foo.contoso.com` but not the root domain `contoso.com`.
  • Unicode host names are allowed but are converted to [Punycode](https://datatracker.ietf.org/doc/html/rfc3492) for matching.
  • [IPv6 addresses](https://datatracker.ietf.org/doc/html/rfc4291) must include bounding brackets and be in [conventional form](https://datatracker.ietf.org/doc/html/rfc4291#section-2.2) (for example, `[ABCD:EF01:2345:6789:ABCD:EF01:2345:6789]`). IPv6 addresses aren't special-cased to check for logical equality between different formats, and no canonicalization is performed.
  • Failure to restrict the allowed hosts might allow a cyberattacker to spoof links generated by the service.
The default value is an empty `IList`. | | | Identifies which forwarders should be processed. See the [ForwardedHeaders Enum](xref:Microsoft.AspNetCore.HttpOverrides.ForwardedHeaders) for the list of fields that apply. Typical values assigned to this property are `ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto`.

The default value is [ForwardedHeaders.None](xref:Microsoft.AspNetCore.HttpOverrides.ForwardedHeaders). | | | Use the header specified by this property instead of the one specified by [ForwardedHeadersDefaults.XForwardedForHeaderName](xref:Microsoft.AspNetCore.HttpOverrides.ForwardedHeadersDefaults.XForwardedForHeaderName). This option is used when the proxy/forwarder doesn't use the `X-Forwarded-For` header but uses some other header to forward the information.

The default is `X-Forwarded-For`. | | | Use the header specified by this property instead of the one specified by [ForwardedHeadersDefaults.XForwardedHostHeaderName](xref:Microsoft.AspNetCore.HttpOverrides.ForwardedHeadersDefaults.XForwardedHostHeaderName). This option is used when the proxy/forwarder doesn't use the `X-Forwarded-Host` header but uses some other header to forward the information.

The default is `X-Forwarded-Host`. | @@ -416,7 +416,7 @@ services.Configure(options => ## Forward the scheme for Linux and non-IIS reverse proxies -Apps that call and put a site into an infinite loop if deployed to an Azure Linux App Service, Azure Linux virtual machine (VM), or behind any other reverse proxy besides IIS. TLS is terminated by the reverse proxy, and Kestrel isn't made aware of the correct request scheme. OAuth and OIDC also fail in this configuration because they generate incorrect redirects. adds and configures Forwarded Headers Middleware when running behind IIS, but there's no matching automatic configuration for Linux (Apache or Nginx integration). +Apps that call and put a site into an infinite loop if deployed to an Azure Linux App Service, Azure Linux virtual machine (VM), or behind any other reverse proxy besides IIS. The reverse proxy terminates TLS, and Kestrel isn't made aware of the correct request scheme. OAuth and OIDC also fail in this configuration because they generate incorrect redirects. adds and configures Forwarded Headers Middleware when running behind IIS, but there's no matching automatic configuration for Linux (Apache or Nginx integration). To forward the scheme from the proxy in non-IIS scenarios, add and configure Forwarded Headers Middleware. In `Startup.ConfigureServices`, use the following code: @@ -452,7 +452,6 @@ In `Startup.Configure`, add the following code before the call to `app.UseAuthen app.UseCertificateForwarding(); ``` - Configure Certificate Forwarding Middleware to specify the header name that Azure uses. In `Startup.ConfigureServices`, add the following code to configure the header from which the middleware builds a certificate: ```csharp