Aspnetcore.docs: Fundamentals/servers/weblistener "WebListener"

[Tratcher]

Port this doc from Katana: http://katanaproject.codeplex.com/wikipage?title=Selfhosting

• Register prefixes so you don't have to run the app as admin
• https cert setup

[Tratcher]

Here's a description of WebListener that can also be added to the doc: https://github.com/aspnet/ServerTests/issues/42

[tdykstra]

The blog post by Neel Bhatt is well done, here's a proposed outline for the new doc that follows a similar organization and expands on it:

What is WebListener

• Server for .NET Core
  
  
  
  • WebListener is a Windows HTTP server built on the Http.Sys kernel mode driver. It exposes a number of Http.Sys features previously only available in IIS.
  
  
  • Built on Microsoft.Net.Http.Server which can be used independently outside of ASP.NET Core
  
  
• Features
  
  
  
  • Windows Authentication
  
  
  • Port sharing
  
  
  • HTTPS with SNI
  
  
  • HTTP/2 over TLS (Windows 10)
  
  
  • Direct file transmission
  
  
  • Response caching
  
  
  • WebSockets (Windows 8)
  
  
• Supported Windows versions
  
  
  
  • Windows 7 and Windows Server 2008 R2 and later
  
  

When to use it

• For use on Windows, when
  
  
  
  • you want to expose the server directly to the internet and you don't want to use IIS, or
  
  
  • you need any of the features listed above.
  
  
• Recommended for edge deployment because it's built on the existing Http.Sys HTTP stack. Http.Sys is mature technology that protects against many kinds of attacks. Kestrel is newer, hasn't had a chance to develop as many protective features yet.
• Not compatible with ASP.NET Core Module, so can't be used with IIS even if you wanted to.
• Example scenario: Azure Service Fabric
  
  
  
  • can use Kestrel for internal microservice to microservice communications on private network (kestrel faster), should use WebListener for directly externally facing microservice layer.
  
  
  • if a cluster is not on a closed private virtual network, should use WebListener for the inter-service communication as they are open to other things contacting them on their "internal" ports.
  
  
  • For details link to SF docs
  
  

How to use it in ASP.NET Core apps

• Install Microsoft.AspNetCore.Server.WebListener
  
  
  
  • Installs dependency Microsoft.Net.Http.Server
  
  
• Main code
  
  
  
  • Remove UseKestrel and UseIISIntegration and add UseWebListener
  
  
  • Specify options in code, e.g. NTLM and AllowAnonymous
  
  
  • Code sample here
  
  
• Specify options in Http.sys registry keys
  
  
  
  • For configuring things such as timeouts
  
  
  • Some of these can be configured in-process but the defaults are in the registry
  
  
  • Link to https://support.microsoft.com/en-us/kb/820129
  
  
• Register prefixes so you don't have to run the app as admin
  
  
  
  • Get content from http://katanaproject.codeplex.com/wikipage?title=Selfhosting
  
  
• Set up SSL certificates
  
  
  
  • SSL setup out of process for WL, vs. in-process for Kestrel
  
  
  • Get content from http://katanaproject.codeplex.com/wikipage?title=Selfhosting
  
  
• Don't run in IIS
  
  
  
  • In VS the default launch profile is for IIS Express, but you can change it to the alternate console profile.
  
  

How to use outside of ASP.NET Core

• Install Microsoft.Net.Http.Server NuGet package
• Code sample here

[tdykstra]

@danroth27 the Katana content that we're porting to Docs refers to third-party tools that are unsupported but are easier to work with than netsh command line, also links to third-party blogs. Is it OK to retain this info when we port the content?

[danroth27]

@tdykstra I think that's fine

[timomta]

Here are my step-by-step notes for running a WebListener console server on Windows Server Core 2016. This was done with a VM, but could be used in a Docker for Windows container environment.

PowerShell to create a self-signed cert
New-SelfSignedCertificate -CertStoreLocation Cert:\LocalMachine\My -DnsName server0.contoso.com
Cert created with the thumbprint: C74235968895ECA9C9D50703D30CE17A7D3AEEFF

PowerShell to create a GUID to use as AppId
New-guid
Guid created: 921328e8-5cdf-4b7f-a3cc-4e50147d1521

Standard cmd Prompt commands to create the Url ACLs (80 and 443)
netsh http add urlacl url=https://+:443/ user=Users
netsh http add urlacl url=http://+:80/ user=Users

Standard cmd Prompt command to associate the cert thumb print and App Id (created above) with port 443
netsh http add sslcert ipport=0.0.0.0:443 certhash=C74235968895ECA9C9D50703D30CE17A7D3AEEFF appid={921328e8-5cdf-4b7f-a3cc-4e50147d1521}
Note: If you run the above from PowerShell rather than cmd, you may need to escape some characters to get it to work

PowerShell to Download .Net Core to the machine
Invoke-WebRequest "https://go.microsoft.com/fwlink/?LinkID=827524" -OutFile .\DotNetCoreSetup.exe -UseBasicParsing

Install .Net Core from the cmd line
.\DotNetCoreSetup.exe /install /quiet /log .\log.txt

PowerShell to Restart the computer after the install
Restart-Computer
Note: You don't need to restart, but it is a pain if you don't let the machine pick up the environment changes

PowerShell to Open the Firewall Ports and Allow Traffic to WebListener
New-NetFirewallRule -DisplayName 'HTTP(S) Inbound' -Profile @('Domain', 'Private') -Direction Inbound -Action Allow -Protocol TCP -LocalPort @('80', '443')

Copy and Run Your App on the Machine
Create a directory for your application
Copy your application into it
Type 'dotnet restore' from the cmd line
Type 'dotnet run' from the cmd line

Final Note
Make sure the .UseUrls("http://+:80", "https://+:443") call matches the URL ACLs you created with netsh earlier.
If this is not done, you may receive a 503 Service Unavailable from the web server.

[timomta]

Wrote a post on it here: https://blogs.msdn.microsoft.com/timomta/2016/11/04/how-do-i-set-up-a-net-core-weblistener-with-ssl/

[Tratcher]

Url configuration: https://msdn.microsoft.com/en-us/library/windows/desktop/aa364698(v=vs.85).aspx

[mikaelm12]

Thanks for the blog post @timomta !