Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

In-process hosting model coverage #8658

Merged
merged 5 commits into from
Oct 9, 2018
Merged

In-process hosting model coverage #8658

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
41db000
In-process hosting model coverage
guardrex Sep 21, 2018
3b1eaf0
React to feedback
guardrex Sep 21, 2018
bec666a
React to feedback
guardrex Sep 22, 2018
04d833e
UseIIS for in-proc
guardrex Sep 24, 2018
393ccd3
Add "V2" to module name
guardrex Oct 9, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 82 additions & 10 deletions aspnetcore/fundamentals/servers/aspnet-core-module.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,37 +4,108 @@ author: rick-anderson
description: Learn how the ASP.NET Core Module allows the Kestrel web server to use IIS or IIS Express as a reverse proxy server.
ms.author: tdykstra
ms.custom: mvc
ms.date: 02/23/2018
ms.date: 09/21/2018
uid: fundamentals/servers/aspnet-core-module
---
# ASP.NET Core Module

By [Tom Dykstra](https://github.com/tdykstra), [Rick Strahl](https://github.com/RickStrahl), and [Chris Ross](https://github.com/Tratcher)
By [Tom Dykstra](https://github.com/tdykstra), [Rick Strahl](https://github.com/RickStrahl), and [Chris Ross](https://github.com/Tratcher)

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

The ASP.NET Core Module allows ASP.NET Core apps to run in an IIS worker process (*in-process*) or behind IIS in a reverse proxy configuration (*out-of-process*). IIS provides advanced web app security and manageability features.

::: moniker-end

::: moniker range="< aspnetcore-2.2"

The ASP.NET Core Module allows ASP.NET Core apps to run behind IIS in a reverse proxy configuration. IIS provides advanced web app security and manageability features.

::: moniker-end

Supported Windows versions:

* Windows 7 or later
* Windows Server 2008 R2 or later

The ASP.NET Core Module only works with Kestrel. The module is incompatible with [HTTP.sys](xref:fundamentals/servers/httpsys) (formerly called [WebListener](xref:fundamentals/servers/weblistener)).
::: moniker range=">= aspnetcore-2.2"

When hosting in-process, the module has its own server implementation, `IISHttpServer`.

When hosting out-of-process, the module only works with Kestrel. The module is incompatible with [HTTP.sys](xref:fundamentals/servers/httpsys) (formerly called [WebListener](xref:fundamentals/servers/weblistener)).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mention here that inprocess has isn't own IIS server implementation.


::: moniker-end

::: moniker range="< aspnetcore-2.2"

The module only works with Kestrel. The module is incompatible with [HTTP.sys](xref:fundamentals/servers/httpsys) (formerly called [WebListener](xref:fundamentals/servers/weblistener)).

::: moniker-end

## ASP.NET Core Module description

The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to redirect web requests to backend ASP.NET Core apps. Many native modules, such as Windows Authentication, remain active. To learn more about IIS modules active with the module, see [IIS modules](xref:host-and-deploy/iis/modules).
::: moniker range=">= aspnetcore-2.2"

The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to either:

* Host an ASP.NET Core app inside of the IIS worker process (`w3wp.exe`), called the [in-process hosting model](#in-process-hosting-model).

* Forward web requests to a backend ASP.NET Core app running the [Kestrel server](xref:fundamentals/servers/kestrel), called the [out-of-process hosting model](#out-of-process-hosting-model).

### In-process hosting model

Using in-process hosting, an ASP.NET Core app runs in the same process as its IIS worker process. This removes the performance penalty of proxying requests over the loopback adapter when using the out-of-process hosting model. IIS handles process management with the [Windows Process Activation Service (WAS)](/iis/manage/provisioning-and-managing-iis/features-of-the-windows-process-activation-service-was).

The ASP.NET Core Module:

* Performs app initialization.
* Loads the [CoreCLR](/dotnet/standard/glossary#coreclr).
* Calls `Program.Main`.
* Handles the lifetime of the IIS native request.

The following diagram illustrates the relationship between IIS, the ASP.NET Core Module, and an app hosted in-process:

![ASP.NET Core Module](aspnet-core-module/_static/ancm-inprocess.png)

A request arrives from the web to the kernel-mode HTTP.sys driver. The driver routes the native request to IIS on the website's configured port, usually 80 (HTTP) or 443 (HTTPS). The module receives the native request and passes control to `IISHttpServer`, which is what converts the request from native to managed.

After `IISHttpServer` picks up the request, the request is pushed into the ASP.NET Core middleware pipeline. The middleware pipeline handles the request and passes it on as an `HttpContext` instance to the app's logic. The app's response is passed back to IIS, which pushes it back out to the HTTP client that initiated the request.

### Out-of-process hosting model

Because ASP.NET Core apps run in a process separate from the IIS worker process, the module 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 shuts down or crashes. This is essentially the same behavior as seen with apps that run in-process that are managed by the [Windows Process Activation Service (WAS)](/iis/manage/provisioning-and-managing-iis/features-of-the-windows-process-activation-service-was).

The following diagram illustrates the relationship between IIS, the ASP.NET Core Module, and an app hosted out-of-process:

![ASP.NET Core Module](aspnet-core-module/_static/ancm-outofprocess.png)

Requests arrive from the web to the kernel-mode HTTP.sys driver. The driver routes the requests to IIS on the website's configured port, usually 80 (HTTP) or 443 (HTTPS). The module forwards the requests to Kestrel on a random port for the app, which isn't port 80/443.

The module specifies the port via an environment variable at startup, and the IIS Integration Middleware configures the server to listen on `http://localhost:{port}`. Additional checks are performed, and requests that don't originate from the module are rejected. The module doesn't support HTTPS forwarding, so requests are forwarded over HTTP even if received by IIS over HTTPS.

After Kestrel picks up the request from the module, the request is pushed into the ASP.NET Core middleware pipeline. The middleware pipeline handles the request and passes it on as an `HttpContext` instance to the app's logic. Middleware added by IIS Integration updates the scheme, remote IP, and pathbase to account for forwarding the request to Kestrel. The app's response is passed back to IIS, which pushes it back out to the HTTP client that initiated the request.

::: moniker-end

::: moniker range="< aspnetcore-2.2"

The ASP.NET Core Module is a native IIS module that plugs into the IIS pipeline to forward web requests to backend ASP.NET Core apps.

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

The following diagram illustrates the relationship between IIS, the ASP.NET Core Module, and ASP.NET Core apps:
The following diagram illustrates the relationship between IIS, the ASP.NET Core Module, and an app:

![ASP.NET Core Module](aspnet-core-module/_static/ancm.png)
![ASP.NET Core Module](aspnet-core-module/_static/ancm-outofprocess.png)

Requests arrive from the web to the kernel-mode HTTP.sys driver. The driver routes the requests to IIS on the website's configured port, usually 80 (HTTP) or 443 (HTTPS). The module forwards the requests to Kestrel on a random port for the app, which isn't port 80/443.

The module specifies the port via an environment variable at startup, and the IIS Integration Middleware configures the server to listen on `http://localhost:{port}`. Additional checks are performed, and requests that don't originate from the module are rejected. The module doesn't support HTTPS forwarding, so requests are forwarded over HTTP even if received by IIS over HTTPS.

After Kestrel picks up a request from the module, the request is pushed into the ASP.NET Core middleware pipeline. The middleware pipeline handles the request and passes it on as an `HttpContext` instance to the app's logic. The app's response is passed back to IIS, which pushes it back out to the HTTP client that initiated the request.
After Kestrel picks up the request from the module, the request is pushed into the ASP.NET Core middleware pipeline. The middleware pipeline handles the request and passes it on as an `HttpContext` instance to the app's logic. Middleware added by IIS Integration updates the scheme, remote IP, and pathbase to account for forwarding the request to Kestrel. The app's response is passed back to IIS, which pushes it back out to the HTTP client that initiated the request.

::: moniker-end

Many native modules, such as Windows Authentication, remain active. To learn more about IIS modules active with the module, see <xref:host-and-deploy/iis/modules>.

The ASP.NET Core Module has a few other functions. The module can:

Expand All @@ -44,10 +115,11 @@ The ASP.NET Core Module has a few other functions. The module can:

## How to install and use the ASP.NET Core Module

For detailed instructions on how to install and use the ASP.NET Core Module, see [Host on Windows with IIS](xref:host-and-deploy/iis/index). For information on configuring the module, see the [ASP.NET Core Module configuration reference](xref:host-and-deploy/aspnet-core-module).
For detailed instructions on how to install and use the ASP.NET Core Module, see <xref:host-and-deploy/iis/index>. For information on configuring the module, see the <xref:host-and-deploy/aspnet-core-module>.

## Additional resources

* [Host on Windows with IIS](xref:host-and-deploy/iis/index)
* [ASP.NET Core Module configuration reference](xref:host-and-deploy/aspnet-core-module)
* <xref:host-and-deploy/iis/index>
* <xref:host-and-deploy/aspnet-core-module>
* [ASP.NET Core Module GitHub repository (source code)](https://github.com/aspnet/AspNetCoreModule)
* <xref:host-and-deploy/iis/modules>
Binary file added aspnetcore/fundamentals/servers/aspnet-core-module/_static/ancm-inprocess.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
0 ...rvers/aspnet-core-module/_static/ancm.png → ...core-module/_static/ancm-outofprocess.png
View file
Open in desktop
File renamed without changes
32 changes: 28 additions & 4 deletions aspnetcore/fundamentals/servers/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,32 @@ author: rick-anderson
description: Discover the web servers Kestrel and HTTP.sys for ASP.NET Core. Learn how to choose a server and when to use a reverse proxy server.
ms.author: tdykstra
ms.custom: mvc
ms.date: 09/13/2018
ms.date: 09/21/2018
uid: fundamentals/servers/index
---
# Web server implementations in ASP.NET Core

By [Tom Dykstra](https://github.com/tdykstra), [Steve Smith](https://ardalis.com/), [Stephen Halter](https://twitter.com/halter73), and [Chris Ross](https://github.com/Tratcher)

An ASP.NET Core app runs with an in-process HTTP server implementation. The server implementation listens for HTTP requests and surfaces them to the app as sets of [request features](xref:fundamentals/request-features) composed into an [HttpContext](/dotnet/api/system.web.httpcontext).
An ASP.NET Core app runs with an in-process HTTP server implementation. The server implementation listens for HTTP requests and surfaces them to the app as sets of [request features](xref:fundamentals/request-features) composed into an <xref:Microsoft.AspNetCore.Http.HttpContext>.

ASP.NET Core ships two server implementations:
ASP.NET Core ships three server implementations:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This can be done in a separate PR, but I think we should make inprocess and out of process separate pages.

Copy link
Collaborator Author

@guardrex guardrex Sep 22, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TL;DR

I considered it, but it looks like organization, reader flow (navigation), and/or duplication will ensue and make a big mess if the hosting model scenarios are split.

Full explanation

I'll describe the landscape and what I ran into.

In ancient times, the team set up the outline like this ...

  • Fundamentals
    • Servers - Basic descriptions and links
      • Kestrel - Description and configuration
      • HTTP.sys - Description and configuration
      • ANCM - Basic description only (no config)
  • Host-and-deploy ("Publishing" in the olden days) - Basic descriptions and links
    • IIS - Description and configuration
    • ANCM - Configuration

These topics and the content they provide are NOT easy to arrange.

🐉 There be dragons here! 🐉

  • Kestrel is behind a proxy or on its own. Kestrel is fully baked in; others are more hybrid.
  • ANCM/IIS bear some explanation early (Fundamentals), but IIS isn't part of .NET Core and fits better in more of a "host/deploy/proxy" set of topics (Host-and-deploy).
  • IIS has a ton of config.
  • ANCM has a lot of separate config.

One thing that could be done is that Kestrel and HTTP.sys could be split between basic overview and configuration. Kestrel in the Server node could merely be an overview (like ANCM/IIS is). Kestrel in the Host-and-deploy node could hold the configuration. Same deal for HTTP.sys. That would consistently introduce server concepts in Fundamentals but configure every scenario in Host-and-deploy (i.e., Kestrel can "host," so it fits; one just doesn't "deploy" anything to it like reverse proxy scenarios). I'd also pitch making that ANCM topic in the Servers node ANCM and IIS and introduce them with greater balance + see what, if anything, of a general nature in the Host-and-deploy IIS topic can be moved there.

Anyway .... that's a digression!

I considered splitting ANCM in-proc and out-of-proc, but I wasn't looking at the Servers node for that split because the content is so minimal. It's just about three paragraphs of text, a list, and an image. If in-proc and out-of-proc are split out, the reader flow is ...

  1. Servers landing
  2. In-proc page
  3. Back to Servers landing
  4. Out-of-proc page
  5. Back to Servers landing

... mmm ... 🤔 ... not so good.

The other spot to consider for a split is with the configuration in the Host-and-deploy node.

There's no natural way to split the hosting models without creating one of two problems ...

  • A lot of duplicated content.
  • An ugly navigation flow for the reader (same as above ☝️)

If configuration is split out for the two hosting models with common config in an ANCM landing page, then the outline is ...

  • host-and-deploy/ancm/index - Common config
    • host-and-deploy/ancm/in-proc - In-proc config
    • host-and-deploy/ancm/out-of-proc - Out-of-proc config

BUT consider ...

  • That landing page doesn't explain in-proc/out-of-proc config (it just links). The reader has to navigate in and out of the other two topics, then they nav back to the common config in the landing page for the rest of the ANCM config.
  • The landing page either skips the hostingModel attribute and pulls it from the attributes table (bad) or the attribute table gets duplicated across the in-proc and out-of-proc topics (also bad; especially bad because in-proc and out-of-proc topics start to maintain common content).

I didn't see a good workable outline for either the Servers node or the Host-and-deploy node. Therefore as you see, I in-lined the content in both spots.

Do you have a different outline/approach in mind?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that duplicate content/ navigation flow makes the change confusing. This organization seems fine then 😄


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

* [Kestrel](xref:fundamentals/servers/kestrel) is the default, cross-platform HTTP server for ASP.NET Core.
* `IISHttpServer` is used with the [in-process hosting model](xref:fundamentals/servers/aspnet-core-module#in-process-hosting-model) and the [ASP.NET Core Module](xref:fundamentals/servers/aspnet-core-module) on Windows.
* [HTTP.sys](xref:fundamentals/servers/httpsys) is a Windows-only HTTP server based on the [HTTP.sys kernel driver and HTTP Server API](https://msdn.microsoft.com/library/windows/desktop/aa364510.aspx). (HTTP.sys is called [WebListener](xref:fundamentals/servers/weblistener) in ASP.NET Core 1.x.)

::: moniker-end

::: moniker range="< aspnetcore-2.2"

* [Kestrel](xref:fundamentals/servers/kestrel) is the default, cross-platform HTTP server for ASP.NET Core.
* [HTTP.sys](xref:fundamentals/servers/httpsys) is a Windows-only HTTP server based on the [HTTP.sys kernel driver and HTTP Server API](https://msdn.microsoft.com/library/windows/desktop/aa364510.aspx). (HTTP.sys is called [WebListener](xref:fundamentals/servers/weblistener) in ASP.NET Core 1.x.)

::: moniker-end

## Kestrel

Kestrel is the default web server included in ASP.NET Core project templates.
Expand Down Expand Up @@ -54,7 +66,19 @@ IIS, Nginx, and Apache can't be used without Kestrel or a [custom server impleme

### IIS with Kestrel

When using [IIS](/iis/get-started/introduction-to-iis/introduction-to-iis-architecture) or [IIS Express](/iis/extensions/introduction-to-iis-express/iis-express-overview) as a reverse proxy for ASP.NET Core, the ASP.NET Core app runs in a process separate from the IIS worker process. In the IIS process, the [ASP.NET Core Module](xref:fundamentals/servers/aspnet-core-module) coordinates the reverse proxy relationship. The primary functions of the ASP.NET Core Module are to start the ASP.NET Core app, restart the app when it crashes, and forward HTTP traffic to the app. For more information, see [ASP.NET Core Module](xref:fundamentals/servers/aspnet-core-module).
::: moniker range=">= aspnetcore-2.2"

When using [IIS](/iis/get-started/introduction-to-iis/introduction-to-iis-architecture) or [IIS Express](/iis/extensions/introduction-to-iis-express/iis-express-overview), the ASP.NET Core app either runs in the same process as the IIS worker process (the *in-process* hosting model) or in a process separate from the IIS worker process (the *out-of-process* hosting model).

The [ASP.NET Core Module](xref:fundamentals/servers/aspnet-core-module) is a native IIS module that handles native IIS requests between either the in-process IIS Http Server or the out-of-process Kestrel server. For more information, see <xref:fundamentals/servers/aspnet-core-module>.

::: moniker-end

::: moniker range="< aspnetcore-2.2"

When using [IIS](/iis/get-started/introduction-to-iis/introduction-to-iis-architecture) or [IIS Express](/iis/extensions/introduction-to-iis-express/iis-express-overview) as a reverse proxy for ASP.NET Core, the ASP.NET Core app runs in a process separate from the IIS worker process. In the IIS process, the [ASP.NET Core Module](xref:fundamentals/servers/aspnet-core-module) coordinates the reverse proxy relationship. The primary functions of the ASP.NET Core Module are to start the ASP.NET Core app, restart the app when it crashes, and forward HTTP traffic to the app. For more information, see <xref:fundamentals/servers/aspnet-core-module>.

::: moniker-end

### Nginx with Kestrel

Expand Down
Loading