Servers > HTTP.sys UE pass #5558

guardrex · 2018-02-27T06:05:58Z

Fixes #5549

Internal Review Topic

Did quite a lot of work on this one (and thus added myself to the authors list at the end):

The structure of the doc was overhauled. See remarks below.
The ordinary slate of grammar+style updates.
Lists of steps numbered.
All of the config options surfaced in a table now. I still think the three column table is too wide for the docs, but that's management's call.
Added lots 'o API doc links.
Section headers refactored.
Third party links removed:
- httpsysmanager seems ancient at this point. I pulled it down, and it doesn't compile. It doesn't seem supported. It seems downright dangerous! ☠️
- HttpConfig also seems ancient, unsupported, and dangerous. The homepage of that project has a comments section full of porn website links! Yikes!
Two links for 3rd party content that "provide detailed instructions for several scenarios" removed: When there are statements in the topic like "is fairly old but still has useful information" and "older blog with useful information," I think we should identify what content we'd like to have and either find a better resource to link or write something here.
I removed the edge of the torn-edge image, which seems rather at odds with the theme. I find it very distracting ... the eye goes right to the edge of the image when consuming the topic and off of the content.
I think we should be saying "X.509 certificate" in the docs over "SSL certificate." I revised the "make X.509 cert" language [INCLUDE]. We'll need @blowdart to take a look at what I did there.
AND we have a shiny spank'in new Razor Pages sample now! 🎉 🎈 🍻

Doc structure overhaul

The current outline goes something like this ...

Intro
When to use
How to use
- Configure the server
  - Framework install
  - Preregister URLs and HTTPS, but refers to content at the end of the topic 👇
- Configure the app
  - Package
  - UseHttpSys
- HTTP.sys options (extremely incomplete list)
  - Max client connections
  - Max request body size override
- Configure URLs and ports (should prob be part of configuring the server)
- Don't use IIS/Express profile with VS (should be part of configuring the app)
Preregister URLs and HTTPS (should be part of configuring the server)
Additional resources

To make the topic flow in a step-by-step way, I restructured it to this ...

Intro
When to use
How to use
- Configure the app
  - Package
  - UseHttpSys
  - HTTP.sys options (complete list; address max client connections here)
  - Max request body size override
  - Don't use IIS/Express profile with VS
- Configure the server
  - Framework install
  - Configure URLs and ports (small duplication where it speaks to UrlPrefixes because the config can be done in both spots)
  - Preregister URLs and HTTPS
Additional resources

Updates Updates Updates Update

guardrex · 2018-02-27T18:03:02Z

@blowdart It's the changes to make-ssl-cert.md at the bottom of the file diffs ... scroll to the last one (https://github.com/aspnet/Docs/pull/5558/files).

Tratcher · 2018-03-01T00:12:00Z

aspnetcore/fundamentals/servers/httpsys.md

-[!code-csharp[](httpsys/sample/Startup.cs?name=snippet_Configure&highlight=9-10)]
-
-An exception is thrown if you try to configure the limit on a request after the application has started reading the request. There's an `IsReadOnly` property that tells you if the `MaxRequestBodySize` property is in read-only state, meaning it's too late to configure the limit.
+1. If the app should override [MaxRequestBodySize](/dotnet/api/microsoft.aspnetcore.server.httpsys.httpsysoptions.maxrequestbodysize) per-request, use the [IHttpMaxRequestBodySizeFeature](/dotnet/api/microsoft.aspnetcore.http.features.ihttpmaxrequestbodysizefeature):


Doesn't this belong inside the MaxRequestBodySize description?

I wish it could, but the code breaks badly inside a table cell. Also, there was the length of the code block to consider. Even if I could get it to work, it would be one heck of a large table cell. Therefore, I dropped it in down here with a conditional ("If the app should ...") to get the disinterested readers to just move past it.

Then pull all of MaxRequestBodySize out into its own section. It's confusing to split up.

Yeah ... I like it. I'll leave it in the table, but I'll bookmark link it down to its own section.

guardrex · 2018-03-01T00:21:19Z

ty @Tratcher

Paging Mr. @blowdart ... Mr. Dart 🎯, please pickup the nearest courtesy telephone. You only need to check the changes to make-ssl-cert.md at the bottom of the file diffs ... scroll to the last one (https://github.com/aspnet/Docs/pull/5558/files).

scottaddie · 2018-03-01T02:49:40Z

aspnetcore/fundamentals/servers/httpsys.md

-HTTP.sys is a [web server for ASP.NET Core](index.md) that runs only on Windows. It's built on the [Http.Sys kernel mode driver](https://msdn.microsoft.com/library/windows/desktop/aa364510.aspx). HTTP.sys is an alternative to [Kestrel](kestrel.md) that offers some features that Kestel doesn't. **HTTP.sys can't be used with IIS or IIS Express, as it's incompatible with the [ASP.NET Core Module](aspnet-core-module.md).**
+[HTTP.sys](/iis/get-started/introduction-to-iis/introduction-to-iis-architecture#hypertext-transfer-protocol-stack-httpsys) is a [web server for ASP.NET Core](xref:fundamentals/servers/index) that only runs on Windows. HTTP.sys is an alternative to [Kestrel](xref:fundamentals/servers/kestrel) and offers some features that Kestrel doesn't provide.
+
+**Important!** HTTP.sys is incompatible with the [ASP.NET Core Module](xref:fundamentals/servers/aspnet-core-module) and can't be used with IIS or IIS Express.


Use the "> [!IMPORTANT]" syntax for this, so it stands out a bit more.

scottaddie · 2018-03-01T02:51:23Z

aspnetcore/fundamentals/servers/httpsys.md


-The maximum number of concurrent open TCP connections can be set for the entire application with the following code in *Program.cs*:
+1. A package reference in the project file isn't required when using the [Microsoft.AspNetCore.All metapackage](xref:fundamentals/metapackage) ([nuget.org](https://www.nuget.org/packages/Microsoft.AspNetCore.All/)) (ASP.NET Core 2.0 or later). When not using the `Microsoft.AspNetCore.All` metapackage, add a package reference to [Microsoft.AspNetCore.Server.HttpSys](https://www.nuget.org/packages/Microsoft.AspNetCore.Server.HttpSys/).


It's best to just say "metapackage", since there's a new "Microsoft.AspNetCore.App" metapackage in 2.1.

Since there hasn't been agreement on the language yet for Replace ALL meta-package wit App Microsoft.AspNetCore.App - MD files only (#5314), perhaps we should wait. This topic will get swept up in the search for ".All" on the repo, so we know it will get addressed when #5314 is tackled.

scottaddie · 2018-03-01T02:55:28Z

aspnetcore/fundamentals/servers/httpsys.md


-If you use both `UseUrls` (or `urls` or ASPNETCORE_URLS) and `UrlPrefixes`, the settings in `UrlPrefixes` override the ones in `UseUrls`. For more information, see [Hosting](xref:fundamentals/hosting).
+1. Install the .NET Core or ASP.NET 4.x framework if the app is a [framework-dependent deployment](/dotnet/core/deploying/#framework-dependent-deployments-fdd).


Did you mean to say ".NET Framework" instead of "ASP.NET 4.x framework"?

scottaddie · 2018-03-01T02:56:35Z

aspnetcore/fundamentals/servers/httpsys.md


-HTTP.sys uses the [HTTP Server API UrlPrefix string formats](https://msdn.microsoft.com/library/windows/desktop/aa364698.aspx).
+   * **.NET Core** &ndash; If the app requires .NET Core, obtain and run the .NET Core installer from [.NET Downloads](https://www.microsoft.com/net/download/windows).
+   * **ASP.NET 4.x** &ndash; If the app requires ASP.NET 4.x, see [.NET Framework: Installation guide](/dotnet/framework/install/) to find installation instructions. Install the required ASP.NET 4.x framework. The installer for the latest ASP.NET 4.x framework can be found at [.NET Downloads](https://www.microsoft.com/net/download/windows).


Here again, I suspect you're talking about .NET Framework, not ASP.NET 4.x.

scottaddie · 2018-03-01T02:57:46Z

aspnetcore/fundamentals/servers/httpsys.md


-Both IIS and HTTP.sys rely on the underlying Http.Sys kernel mode driver to listen for requests and do initial processing. In IIS, the management UI gives you a relatively easy way to configure everything. However, you need to configure Http.Sys yourself. The built-in tool for doing that's *netsh.exe*. 
+   The settings in `UrlPrefixes` override `UseUrls`/`urls`/`ASPNETCORE_URLS` settings. Therefore, an advantage of `UseUrls`,`urls`, and the `ASPNETCORE_URLS` environment variable is that it's easier to switch between Kestrel and HTTP.sys. For more information on `UseUrls`, `urls`, and `ASPNETCORE_URLS`, see [Hosting](xref:fundamentals/hosting).


Add a space before urls

scottaddie · 2018-03-01T02:58:08Z

aspnetcore/fundamentals/servers/httpsys.md


-With *netsh.exe* you can reserve URL prefixes and assign SSL certificates. The tool requires administrative privileges.
+   HTTP.sys uses the [HTTP Server API UrlPrefix string formats](https://msdn.microsoft.com/library/windows/desktop/aa364698.aspx).


Is there a different link we can use? I'd prefer to avoid MSDN.

I looked when I was updating the links. Unfortunately, no. I can't find this content anywhere except on MSDN.

scottaddie · 2018-03-01T02:58:52Z

aspnetcore/fundamentals/servers/httpsys.md


-Here are some third-party tools that can be easier to use than the *netsh.exe* command line. These are not provided by or endorsed by Microsoft. The tools run as administrator by default, since *netsh.exe* itself requires administrator privileges.
+      * [Netsh Commands for Hypertext Transfer Protocol (HTTP)](https://technet.microsoft.com/library/cc725882.aspx)
+      * [UrlPrefix Strings](https://msdn.microsoft.com/library/windows/desktop/aa364698.aspx)


Is MSDN the only source of this info?

Unfortunately, that's correct ... MSDN or bust! 😢

scottaddie · 2018-03-01T03:00:14Z

aspnetcore/includes/make-x509-cert.md

+* [SelfCert](https://www.pluralsight.com/blog/software-development/selfcert-create-a-self-signed-certificate-interactively-gui-or-programmatically-in-net)
+* [OpenSSL](https://www.openssl.org/)
+
+On macOS and Linux, self-signed certificates can be created using [OpenSSL](https://www.openssl.org/).


You can probably remove the link on the 2nd occurrence of OpenSSL. You already linked to it in the list above.

True, but it reads "on Windows" and then "On mac and Linux." I'm concerned the Mac/Linux reader will just flat out skip that whole first bit and jump drop down to the "On macOS and Linux" bit.

Let me try a different setup of this content on the next commit that might fix it so that there's only one link to OpenSSL.

guardrex · 2018-03-01T03:25:08Z

@scottaddie ty ... updates made. 👍

blowdart · 2018-03-01T19:32:34Z

The only change I'd make is to put powershell first for windows. Making people using OpenSSL on Windows is just awful.

I'm not sure I'd recommend SelfCert either, we haven't reviewed it. https://gist.github.com/blowdart/1cb907b68ed56bcf8498c16faff4221c creates the cert correctly, and trusts it on the VS dev ports, so it's a good starting point.

Note that none of this will work with the 2.1 pieces, as there's an OID used for discovery - @javiercn will have details.

guardrex · 2018-03-01T23:30:20Z

@blowdart See how it looks now.

Windows first
- PS approach only
- I add your script as an unsupported example with a few touch-ups in the script's comments.
OpenSSL second

Both files are at the bottom of the file diffs: https://github.com/aspnet/Docs/pull/5558/files

Update

blowdart · 2018-03-01T23:34:05Z

LGTM now

guardrex · 2018-03-01T23:50:34Z

ty @blowdart

@Rick-Anderson Any CELA or support concerns over the markdown comment? ...

For an unsupported example, ..."

or the script comment? ...

THIS SCRIPT IS UNSUPPORTED BY MICROSOFT AND PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED.

* InvokeAsync for middleware class + note (#5584) * Servers > HTTP.sys UE pass (#5558) * Servers > HTTP.sys UE pass Updates Updates Updates Update * Move MaxRequestBodySize to a section * React to feedback * React to feedback Update * Shorten Kestrel doc title (#5588)

guardrex requested review from blowdart and Tratcher February 27, 2018 06:05

Servers > HTTP.sys UE pass

55590a8

Updates Updates Updates Update

guardrex force-pushed the guardrex/httpsys-update branch from 18c191c to 55590a8 Compare February 27, 2018 17:47

Tratcher reviewed Mar 1, 2018

View reviewed changes

Tratcher approved these changes Mar 1, 2018

View reviewed changes

guardrex requested a review from scottaddie March 1, 2018 00:18

Move MaxRequestBodySize to a section

275e35b

scottaddie reviewed Mar 1, 2018

View reviewed changes

React to feedback

ce22674

scottaddie approved these changes Mar 1, 2018

View reviewed changes

React to feedback

1d34443

Update

guardrex force-pushed the guardrex/httpsys-update branch from e2892b6 to 1d34443 Compare March 1, 2018 23:33

scottaddie requested a review from Rick-Anderson March 2, 2018 17:10

Rick-Anderson merged commit bef5541 into master Mar 2, 2018

Rick-Anderson deleted the guardrex/httpsys-update branch March 2, 2018 18:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Servers > HTTP.sys UE pass #5558

Servers > HTTP.sys UE pass #5558

guardrex commented Feb 27, 2018 •

edited

Loading

guardrex commented Feb 27, 2018

Tratcher Mar 1, 2018

guardrex Mar 1, 2018

Tratcher Mar 1, 2018

guardrex Mar 1, 2018

guardrex commented Mar 1, 2018 •

edited

Loading

scottaddie Mar 1, 2018

scottaddie Mar 1, 2018

guardrex Mar 1, 2018

scottaddie Mar 1, 2018

scottaddie Mar 1, 2018

scottaddie Mar 1, 2018

scottaddie Mar 1, 2018

guardrex Mar 1, 2018

scottaddie Mar 1, 2018

guardrex Mar 1, 2018

scottaddie Mar 1, 2018

guardrex Mar 1, 2018

guardrex commented Mar 1, 2018

blowdart commented Mar 1, 2018

guardrex commented Mar 1, 2018

blowdart commented Mar 1, 2018

guardrex commented Mar 1, 2018


		The maximum number of concurrent open TCP connections can be set for the entire application with the following code in Program.cs:
		1. A package reference in the project file isn't required when using the [Microsoft.AspNetCore.All metapackage](xref:fundamentals/metapackage) ([nuget.org](https://www.nuget.org/packages/Microsoft.AspNetCore.All/)) (ASP.NET Core 2.0 or later). When not using the `Microsoft.AspNetCore.All` metapackage, add a package reference to [Microsoft.AspNetCore.Server.HttpSys](https://www.nuget.org/packages/Microsoft.AspNetCore.Server.HttpSys/).


		If you use both `UseUrls` (or `urls` or ASPNETCORE_URLS) and `UrlPrefixes`, the settings in `UrlPrefixes` override the ones in `UseUrls`. For more information, see [Hosting](xref:fundamentals/hosting).
		1. Install the .NET Core or ASP.NET 4.x framework if the app is a [framework-dependent deployment](/dotnet/core/deploying/#framework-dependent-deployments-fdd).


		Both IIS and HTTP.sys rely on the underlying Http.Sys kernel mode driver to listen for requests and do initial processing. In IIS, the management UI gives you a relatively easy way to configure everything. However, you need to configure Http.Sys yourself. The built-in tool for doing that's netsh.exe.
		The settings in `UrlPrefixes` override `UseUrls`/`urls`/`ASPNETCORE_URLS` settings. Therefore, an advantage of `UseUrls`,`urls`, and the `ASPNETCORE_URLS` environment variable is that it's easier to switch between Kestrel and HTTP.sys. For more information on `UseUrls`, `urls`, and `ASPNETCORE_URLS`, see [Hosting](xref:fundamentals/hosting).


		With netsh.exe you can reserve URL prefixes and assign SSL certificates. The tool requires administrative privileges.
		HTTP.sys uses the [HTTP Server API UrlPrefix string formats](https://msdn.microsoft.com/library/windows/desktop/aa364698.aspx).

Servers > HTTP.sys UE pass #5558

Servers > HTTP.sys UE pass #5558

Conversation

guardrex commented Feb 27, 2018 • edited Loading

Doc structure overhaul

guardrex commented Feb 27, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

guardrex commented Mar 1, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

guardrex commented Mar 1, 2018

blowdart commented Mar 1, 2018

guardrex commented Mar 1, 2018

blowdart commented Mar 1, 2018

guardrex commented Mar 1, 2018

guardrex commented Feb 27, 2018 •

edited

Loading

guardrex commented Mar 1, 2018 •

edited

Loading