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

Update libuv references in Kestrel docs #6184

Merged
merged 12 commits into from
May 10, 2018
Merged

Update libuv references in Kestrel docs #6184

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
5cf79ff
Update libuv references in Kestrel docs
guardrex May 2, 2018
a993c84
React to feedback
guardrex May 2, 2018
80f6801
Move content into a section
guardrex May 3, 2018
7a4e92b
React to feedback
guardrex May 3, 2018
fce489c
React to feedback
guardrex May 9, 2018
ded0d1e
Remove 2.1 include
guardrex May 9, 2018
c2db7f5
Merge branch 'master' into guardrex/kestrel-libuv-updates
guardrex May 9, 2018
a64c358
Show both
guardrex May 10, 2018
3c178c0
Merge branch 'guardrex/kestrel-libuv-updates' of https://github.com/a…
guardrex May 10, 2018
79edfd8
Updates
guardrex May 10, 2018
e547864
Repair code block+highlights
guardrex May 10, 2018
1213555
Reverting tab controls to official guidance (AFAIK)
guardrex May 10, 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
5 changes: 5 additions & 0 deletions aspnetcore/fundamentals/servers/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,12 @@ An ASP.NET Core app runs with an in-process HTTP server implementation. The serv

ASP.NET Core ships two server implementations:

::: moniker range="<= aspnetcore-2.0"
* [Kestrel](xref:fundamentals/servers/kestrel) is a cross-platform HTTP server based on [libuv](https://github.com/libuv/libuv), a cross-platform asynchronous I/O library.
Copy link
Member

Choose a reason for hiding this comment

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

Is this a 1.x section? If not, I'd just drop everything after and including "based on". Maybe you could mention it's the default server, but that's covered almost immediately after this already.

::: moniker-end
::: moniker range=">= aspnetcore-2.1"
* [Kestrel](xref:fundamentals/servers/kestrel) is a cross-platform HTTP server based on managed sockets (`Microsoft.AspNetCore.Server.Kestrel.Transport.Sockets`), a cross-platform asynchronous I/O library. In versions of ASP.NET Core prior to 2.1, Kestrel is based on [libuv](https://github.com/libuv/libuv).
Copy link
Member

Choose a reason for hiding this comment

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

I also don't think discussion of the transport belongs here. If we must include it, I wouldn't call Microsoft.AspNetCore.Server.Kestrel.Transport.Sockets a cross-platform asynchronous I/O library. That's what libuv is, but the sockets transport is more limited. It's just a socket library that implements Kestrel's transport abstraction.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Sure, I can address that on the next commit.

Copy link
Member

Choose a reason for hiding this comment

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

I know we go into this in detail in the kestrel-specific doc, but I think it's still worth mentioning libuv is still an option for 2.1 here.

Copy link
Member

Choose a reason for hiding this comment

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

That, or just remove the transport discussion from the main server doc.

Copy link
Collaborator Author

@guardrex guardrex May 9, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

Yes, I think we should remove it. If I try to add that sentiment, it becomes perhaps a bit too complicated ...

Kestrel is a cross-platform HTTP server based on managed sockets (Microsoft.AspNetCore.Server.Kestrel.Transport.Sockets), a cross-platform asynchronous I/O library. In versions of ASP.NET Core prior to 2.1, Kestrel is based on libuv, which remains a viable alternative for 2.1 or later apps.

We can just go with this here ...

Kestrel is a cross-platform HTTP server based on managed sockets (Microsoft.AspNetCore.Server.Kestrel.Transport.Sockets), a cross-platform asynchronous I/O library.

::: moniker-end

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

Expand Down
24 changes: 21 additions & 3 deletions aspnetcore/fundamentals/servers/kestrel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
title: Kestrel web server implementation in ASP.NET Core
author: tdykstra
description: Learn about Kestrel, the cross-platform web server for ASP.NET Core based on libuv.
description: Learn about Kestrel, the cross-platform web server for ASP.NET Core.
manager: wpickett
ms.author: tdykstra
ms.custom: mvc
ms.date: 04/26/2018
ms.date: 05/02/2018
ms.prod: asp.net-core
ms.technology: aspnet
ms.topic: article
Expand All @@ -15,7 +15,7 @@ uid: fundamentals/servers/kestrel

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

Kestrel is a cross-platform [web server for ASP.NET Core](xref:fundamentals/servers/index) based on [libuv](https://github.com/libuv/libuv), a cross-platform asynchronous I/O library. Kestrel is the web server that's included by default in ASP.NET Core project templates.
Kestrel is a cross-platform [web server for ASP.NET Core](xref:fundamentals/servers/index). Kestrel is the web server that's included by default in ASP.NET Core project templates.

Kestrel supports the following features:

Expand Down Expand Up @@ -489,6 +489,24 @@ When using IIS, the URL bindings for IIS override bindings set by `UseUrls`. For

* * *

::: moniker range=">= aspnetcore-2.1"
## Transport configuration

With the release of ASP.NET Core 2.1, Kestrel's default transport is no longer based on Libuv but instead based on managed sockets. This is a breaking change for ASP.NET Core 2.0 apps upgrading to 2.1 that call [WebHostBuilderLibuvExtensions.UseLibuv](/dotnet/api/microsoft.aspnetcore.hosting.webhostbuilderlibuvextensions.uselibuv) and depend on either of the following packages:

* [Microsoft.AspNetCore.Server.Kestrel](https://www.nuget.org/packages/Microsoft.AspNetCore.Server.Kestrel/) (direct package reference)
* [Microsoft.AspNetCore.App](https://www.nuget.org/packages/Microsoft.AspNetCore.App/)

For ASP.NET Core 2.1 or later projects that use the `Microsoft.AspNetCore.App` metapackage and require the use of Libuv (the app calls [WebHostBuilderLibuvExtensions.UseLibuv](/dotnet/api/microsoft.aspnetcore.hosting.webhostbuilderlibuvextensions.uselibuv)), add a dependency for the [Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv](https://www.nuget.org/packages/Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv/) package to the app's project file:

```xml
<PackageReference Include="Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv"
Version="2.1.0" />
```
Copy link
Member

Choose a reason for hiding this comment

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

One more thing. Can we have a one-line snippet like this, but for the actual call to UseLibuv()?


No action is required when the [Microsoft.AspNetCore.All](xref:fundamentals/metapackage) metapackage is used and `UseLibuv` is called because the Libuv transport package is transitively referenced by the `Microsoft.AspNetCore.All` metapackage. Note that the ASP.NET Core 2.1 or later templates reference the [Microsoft.AspNetCore.App](https://www.nuget.org/packages/Microsoft.AspNetCore.App/) metapackage by default. The use of the `Microsoft.AspNetCore.All` metapackage isn't recommended for ASP.NET Core 2.1 or later apps.
Copy link
Member

Choose a reason for hiding this comment

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

I didn't realize that Microsoft.AspNetCore.All was deprecated. Maybe we shouldn't mention it at all and just tell people to reference Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv directly.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I believe they're phrasing it more along the lines of "not recommended" and "subject to future removal" at this time. That's why I slanted the language in this way (i.e., not use the word "depreciated" there). *they = @DamianEdwards in Standup remarks.

Copy link
Contributor

Choose a reason for hiding this comment

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

This is a good point. I'm not sure this is a recommendation we actually need to make yet. But even if we do, this seems like information that belongs on the metapackage doc, not here.

Copy link
Member

Choose a reason for hiding this comment

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

Since this section only displays for ASP.NET Core 2.1+, we shouldn't reference the older ".All" metapackage. That will really slim down this paragraph.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I think it would be best in a migration topic, but I don't see TO-2.1 content in the migration area.

This para has taken a lot of heat. 😄 lol I'd prefer to cut it at 3.0; but since everyone else dislikes it, I'll cut it.

::: moniker-end

### URL prefixes

When using `UseUrls`, `--urls` command-line argument, `urls` host configuration key, or `ASPNETCORE_URLS` environment variable, the URL prefixes can be in any of the following formats.
Expand Down