Skip to content

Commit 65bb4b3

Browse files
jkotalikguardrex
jkotalik
and
guardrex
authored
Restructure for IIS docs (#19987)
* Start of restructure * Rest of files * Renames of files and starting to write * Some small progress * Update authors * More doc progress :) * moving files back * Fixing uid * ToC * Update out of process doc * App init * Updates * Updates * Updates * Updates * Updates * Updates * Updates * Updates * Updates * Update * Updates * Updates * Updates * Updates * Updates * Updates * Updates * Updates * Updates * Updates * Updates * Updates * Updates * Updates * Updates * Updates * Updates * Updates * Updates * Updates * Updates * fix some warnings * nit * fixing web.config doc and removing extra tutorial * Another warning * Why is this not working * path * remove * Nit Co-authored-by: Luke Latham <llatham@aquent.com>
1 parent 2f406f5 commit 65bb4b3

12 files changed

Lines changed: 1220 additions & 141 deletions

‎aspnetcore/host-and-deploy/app-offline.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: App Offline file (app_offline.htm)
3+
author: rick-anderson
4+
description: Learn how the App Offline file (`app_offline.htm`) works with the ASP.NET Core Module.
5+
monikerRange: '>= aspnetcore-5.0'
6+
ms.author: riande
7+
ms.custom: mvc
8+
ms.date: 01/13/2020
9+
no-loc: ["ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR]
10+
uid: host-and-deploy/iis/app-offline
11+
---
12+
# App Offline file (`app_offline.htm`)
13+
14+
The App Offline file (`app_offline.htm`) is used by the ASP.NET Core Module to shut down an app.
15+
16+
If a file with the name `app_offline.htm` is detected in the root directory of an app, the ASP.NET Core Module attempts to gracefully shut down the app and stop processing incoming requests. If the app is still running after the number of seconds defined in `shutdownTimeLimit`, the ASP.NET Core Module stops the running process.
17+
18+
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.
19+
20+
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.
21+
22+
## Locked deployment files
23+
24+
Files in the deployment folder are locked when the app is running. Locked files can't be overwritten during deployment.
25+
26+
`app_offline.htm` is the primary mechanism to release locked files. `app_offline.htm` is used by Web Deploy to properly stop and start the app.
27+
28+
`app_offline.htm` can be manually used to start and stop the app (requires PowerShell 5 or later):
29+
30+
```powershell
31+
$pathToApp = '{PATH TO APP}'
32+
33+
New-Item -Path $pathToApp app_offline.htm
34+
35+
# Provide script commands here to deploy the app
36+
37+
Remove-Item -Path $pathToApp app_offline.htm
38+
```
39+
40+
In the preceding PowerShell script:
41+
42+
* The placeholder `{PATH TO APP}` is the path to the app.
43+
* The `New-Item` command stops the app pool.
44+
* The `Remove-Item` command starts the app pool.
45+
* Commands between the `New-Item` command and the `Remove-Item` command are provided by the developer to deploy the app.
46+
47+
Files can also be unlocked by manually stopping the app pool in the IIS Manager on the server. Don't use the `app_offine.htm` file when using the IIS Manager to stop and restart the app pool.

‎aspnetcore/host-and-deploy/azure-iis-errors-reference.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ ms.date: 02/07/2020
99
no-loc: ["ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR]
1010
uid: host-and-deploy/azure-iis-errors-reference
1111
---
12+
1213
# Common errors reference for Azure App Service and IIS with ASP.NET Core
1314

1415
::: moniker range=">= aspnetcore-2.2"

‎aspnetcore/host-and-deploy/iis/advanced.md‎

Lines changed: 367 additions & 0 deletions
Large diffs are not rendered by default.

aspnetcore/host-and-deploy/aspnet-core-module.md renamed to aspnetcore/host-and-deploy/iis/aspnet-core-module.md

Lines changed: 112 additions & 92 deletions
Large diffs are not rendered by default.

‎aspnetcore/host-and-deploy/iis/hosting-bundle.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
title: Hosting Bundle
3+
author: rick-anderson
4+
description: Learn how to configure the .NET Core Hosting Bundle.
5+
monikerRange: '>= aspnetcore-5.0'
6+
ms.author: riande
7+
ms.custom: mvc
8+
ms.date: 02/07/2020
9+
no-loc: ["ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR]
10+
uid: host-and-deploy/iis/hosting-bundle
11+
---
12+
# The .NET Core Hosting Bundle
13+
14+
The .NET Core Hosting bundle is an installer for the .NET Core Runtime and the [ASP.NET Core Module](xref:host-and-deploy/aspnet-core-module). The bundle allows ASP.NET Core apps to run with IIS.
15+
16+
## Install the .NET Core Hosting Bundle
17+
18+
> [!IMPORTANT]
19+
> If the Hosting Bundle is installed before IIS, the bundle installation must be repaired. Run the Hosting Bundle installer again after installing IIS.
20+
>
21+
> If the Hosting Bundle is installed after installing the 64-bit (x64) version of .NET Core, SDKs might appear to be missing ([No .NET Core SDKs were detected](xref:test/troubleshoot#no-net-core-sdks-were-detected)). To resolve the problem, see <xref:test/troubleshoot#missing-sdk-after-installing-the-net-core-hosting-bundle>.
22+
23+
### Direct download (current version)
24+
25+
Download the installer using the following link:
26+
27+
[Current .NET Core Hosting Bundle installer (direct download)](https://dotnet.microsoft.com/permalink/dotnetcore-current-windows-runtime-bundle-installer)
28+
29+
### Earlier versions of the installer
30+
31+
To obtain an earlier version of the installer:
32+
33+
1. Navigate to the [Download .NET Core](https://dotnet.microsoft.com/download/dotnet-core) page.
34+
1. Select the desired .NET Core version.
35+
1. In the **Run apps - Runtime** column, find the row of the .NET Core runtime version desired.
36+
1. Download the installer using the **Hosting Bundle** link.
37+
38+
> [!WARNING]
39+
> 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).
40+
41+
### Install the Hosting Bundle
42+
43+
1. Run the installer on the server. The following parameters are available when running the installer from an administrator command shell:
44+
45+
* `OPT_NO_ANCM=1`: Skip installing the ASP.NET Core Module.
46+
* `OPT_NO_RUNTIME=1`: Skip installing the .NET Core runtime. Used when the server only hosts [self-contained deployments (SCD)](/dotnet/core/deploying/#self-contained-deployments-scd).
47+
* `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).
48+
* `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.
49+
* `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 <xref:host-and-deploy/aspnet-core-module#aspnet-core-module-with-an-iis-shared-configuration>.
50+
1. Restart the system or execute the following commands in a command shell:
51+
52+
```console
53+
net stop was /y
54+
net start w3svc
55+
```
56+
Restarting IIS picks up a change to the system PATH, which is an environment variable, made by the installer.
57+
58+
ASP.NET Core doesn't adopt roll-forward behavior for patch releases of shared framework packages. After upgrading the shared framework by installing a new hosting bundle, restart the system or execute the following commands in a command shell:
59+
60+
```console
61+
net stop was /y
62+
net start w3svc
63+
```
64+
65+
> [!NOTE]
66+
> For information on IIS Shared Configuration, see [ASP.NET Core Module with IIS Shared Configuration](xref:host-and-deploy/aspnet-core-module#aspnet-core-module-with-an-iis-shared-configuration).
67+
68+
## Module version and Hosting Bundle installer logs
69+
70+
To determine the version of the installed ASP.NET Core Module:
71+
72+
1. On the hosting system, navigate to `%PROGRAMFILES%\IIS\Asp.Net Core Module\V2`.
73+
1. Locate the `aspnetcorev2.dll` file.
74+
1. Right-click the file and select **Properties** from the contextual menu.
75+
1. Select the **Details** tab. The **File version** and **Product version** represent the installed version of the module.
76+
77+
The Hosting Bundle installer logs for the module are found at `C:\Users\%UserName%\AppData\Local\Temp`. The file is named `dd_DotNetCoreWinSvrHosting__{TIMESTAMP}_000_AspNetCoreModule_x64.log`, where the placeholder `{TIMESTAMP}` is the timestamp of the file.

‎aspnetcore/host-and-deploy/iis/in-process-hosting.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
---
2+
title: In-process hosting with IIS and ASP.NET Core
3+
author: rick-anderson
4+
description: Learn about in-Process hosting with IIS and the ASP.NET Core Module.
5+
monikerRange: '>= aspnetcore-5.0'
6+
ms.author: riande
7+
ms.custom: mvc
8+
ms.date: 02/07/2020
9+
no-loc: ["ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR]
10+
uid: host-and-deploy/iis/in-process-hosting
11+
---
12+
13+
# In-process hosting with IIS and ASP.NET Core
14+
15+
In-process hosting runs an ASP.NET Core app in the same process as its IIS worker process. In-process hosting provides improved performance over out-of-process hosting because requests aren't proxied over the loopback adapter, a network interface that returns outgoing network traffic back to the same machine.
16+
17+
The following diagram illustrates the relationship between IIS, the ASP.NET Core Module, and an app hosted in-process:
18+
19+
![ASP.NET Core Module in the in-process hosting scenario](index/_static/ancm-inprocess.png)
20+
21+
## Enable in-process hosting
22+
23+
Since ASP.NET Core 3.0, in-process hosting has been enabled by default for all app deployed to IIS.
24+
25+
To explicitly configure an app for in-process hosting, set the value of the `<AspNetCoreHostingModel>` property to `InProcess` in the project file (`.csproj`):
26+
27+
```xml
28+
<PropertyGroup>
29+
<AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
30+
</PropertyGroup>
31+
```
32+
33+
## General architecture
34+
35+
The general flow of a request is as follows:
36+
37+
1. A request arrives from the web to the kernel-mode HTTP.sys driver.
38+
1. The driver routes the native request to IIS on the website's configured port, usually 80 (HTTP) or 443 (HTTPS).
39+
1. The ASP.NET Core Module receives the native request and passes it to IIS HTTP Server (`IISHttpServer`). IIS HTTP Server is an in-process server implementation for IIS that converts the request from native to managed.
40+
41+
After the IIS HTTP Server processes the request:
42+
43+
1. The request is sent to the ASP.NET Core middleware pipeline.
44+
1. The middleware pipeline handles the request and passes it on as an `HttpContext` instance to the app's logic.
45+
1. The app's response is passed back to IIS through IIS HTTP Server.
46+
1. IIS sends the response to the client that initiated the request.
47+
48+
`CreateDefaultBuilder` adds an <xref:Microsoft.AspNetCore.Hosting.Server.IServer> instance by calling the <xref:Microsoft.AspNetCore.Hosting.WebHostBuilderIISExtensions.UseIIS%2A> 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 Core 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).
49+
50+
Apps published as a single file executable can't be loaded by the in-process hosting model.
51+
52+
## Application configuration
53+
54+
To configure IIS options, include a service configuration for <xref:Microsoft.AspNetCore.Builder.IISServerOptions> in <xref:Microsoft.AspNetCore.Hosting.IStartup.ConfigureServices%2A>. The following example disables AutomaticAuthentication:
55+
56+
```csharp
57+
services.Configure<IISServerOptions>(options =>
58+
{
59+
options.AutomaticAuthentication = false;
60+
});
61+
```
62+
63+
| Option | Default | Setting |
64+
| ------ | :-----: | ------- |
65+
| `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). |
66+
| `AuthenticationDisplayName` | `null` | Sets the display name shown to users on login pages. |
67+
| `AllowSynchronousIO` | `false` | Whether synchronous I/O is allowed for the `HttpContext.Request` and the `HttpContext.Response`. |
68+
| `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). |
69+
70+
## Differences between in-process and out-of-process hosting
71+
72+
The following characteristics apply when hosting in-process:
73+
74+
* IIS HTTP Server (`IISHttpServer`) is used instead of [Kestrel](xref:fundamentals/servers/kestrel) server. For in-process, [`CreateDefaultBuilder`](xref:fundamentals/host/generic-host#default-builder-settings) calls <xref:Microsoft.AspNetCore.Hosting.WebHostBuilderIISExtensions.UseIIS%2A> to:
75+
76+
* Register the `IISHttpServer`.
77+
* Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
78+
* Configure the host to capture startup errors.
79+
80+
* The [`requestTimeout` attribute](xref:host-and-deploy/iis/web-config#attributes-of-the-aspnetcore-element) doesn't apply to in-process hosting.
81+
82+
* Sharing an app pool among apps isn't supported. Use one app pool per app.
83+
84+
* The architecture (bitness) of the app and installed runtime (x64 or x86) must match the architecture of the app pool. For example, apps published for 32-bit (x86) must have 32-bit enabled for their IIS Application Pools. For more information, see the [Create the IIS site](xref:tutorials/publish-to-iis#create-the-iis-site) section.
85+
86+
* Client disconnects are detected. The [`HttpContext.RequestAborted`](xref:Microsoft.AspNetCore.Http.HttpContext.RequestAborted%2A) cancellation token is cancelled when the client disconnects.
87+
88+
* When hosting in-process, <xref:Microsoft.AspNetCore.Authentication.AuthenticationService.AuthenticateAsync%2A> isn't called internally to initialize a user. Therefore, an <xref:Microsoft.AspNetCore.Authentication.IClaimsTransformation> implementation used to transform claims after every authentication isn't activated by default. When transforming claims with an <xref:Microsoft.AspNetCore.Authentication.IClaimsTransformation> implementation, call <xref:Microsoft.Extensions.DependencyInjection.AuthenticationServiceCollectionExtensions.AddAuthentication%2A> to add authentication services:
89+
90+
```csharp
91+
public void ConfigureServices(IServiceCollection services)
92+
{
93+
services.AddTransient<IClaimsTransformation, ClaimsTransformer>();
94+
services.AddAuthentication(IISServerDefaults.AuthenticationScheme);
95+
}
96+
97+
public void Configure(IApplicationBuilder app)
98+
{
99+
app.UseAuthentication();
100+
}
101+
```
102+
103+
* [Web Package (single-file) deployments](/aspnet/web-forms/overview/deployment/web-deployment-in-the-enterprise/deploying-web-packages) aren't supported.

0 commit comments

Comments
 (0)