What is Web Listener web server in ASP.NET Core

What is Web Listener web server in ASP.NET Core?

WebListener is a web server for ASP.NET Core that runs only on Windows. It's built on the Http.Sys kernel mode driver. WebListener is an alternative to Kestrel that can be used for direct connection to the Internet without relying on IIS as a reverse proxy server. In fact, WebListener can't be used with IIS or IIS Express, as it isn't compatible with the ASP.NET Core Module.

Although WebListener was developed for ASP.NET Core, it can be used directly in any .NET Core or .NET Framework application via the Microsoft.Net.Http.Server NuGet package.

WebListener supports the following 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

View or download sample code (how to download)

When to use WebListener

WebListener is useful for deployments where you need to expose the server directly to the Internet without using IIS.

Weblistener communicates directly with the Internet

Because it's built on Http.Sys, WebListener doesn't require a reverse proxy server for protection against attacks. Http.Sys is mature technology that protects against many kinds of attacks and provides the robustness, security, and scalability of a full-featured web server. IIS itself runs as an HTTP listener on top of Http.Sys.

WebListener is also a good choice for internal deployments when you need one of the features it offers that you can't get by using Kestrel.

Weblistener communicates directly with your internal network

How to use WebListener

Here's an overview of setup tasks for the host OS and your ASP.NET Core application.

Configure Windows Server

  • Install the version of .NET that your application requires, such as .NET Core or .NET Framework 4.5.1.

  • Preregister URL prefixes to bind to WebListener, and set up SSL certificates

If you don't preregister URL prefixes in Windows, you have to run your application with administrator privileges. The only exception is if you bind to localhost using HTTP (not HTTPS) with a port number greater than 1024; in that case administrator privileges aren't required.

For details, see How to preregister prefixes and configure SSL later in this article.

  • Open firewall ports to allow traffic to reach WebListener.

You can use netsh.exe or PowerShell cmdlets.

There are also Http.Sys registry settings.

Configure your ASP.NET Core application


public​​ static​​ void​​ Main(string[] args)


 ​​ ​​ ​​​​ Console.WriteLine("Running demo with WebListener.");


 ​​ ​​ ​​​​ var​​ config =​​ new​​ ConfigurationBuilder()

 ​​ ​​ ​​ ​​ ​​ ​​ ​​​​ .AddCommandLine(args)

 ​​ ​​ ​​ ​​ ​​ ​​ ​​​​ .Build();


 ​​ ​​ ​​​​ var​​ builder =​​ new​​ WebHostBuilder()

 ​​ ​​ ​​ ​​ ​​ ​​ ​​​​ .UseContentRoot(Directory.GetCurrentDirectory())

 ​​ ​​ ​​ ​​ ​​ ​​ ​​​​ .UseConfiguration(config)

 ​​ ​​ ​​ ​​ ​​ ​​ ​​​​ .UseStartup<Startup>()

 ​​ ​​ ​​ ​​ ​​ ​​ ​​​​ .UseWebListener(options =>

 ​​ ​​ ​​ ​​ ​​ ​​ ​​​​ {

 ​​ ​​ ​​ ​​ ​​ ​​ ​​ ​​ ​​ ​​ ​​​​ options.ListenerSettings.Authentication.Schemes = AuthenticationSchemes.None;

 ​​ ​​ ​​ ​​ ​​ ​​ ​​ ​​ ​​ ​​ ​​​​ options.ListenerSettings.Authentication.AllowAnonymous =​​ true;

 ​​ ​​ ​​ ​​ ​​ ​​ ​​​​ });


 ​​ ​​ ​​​​ var​​ host = builder.Build();

 ​​ ​​ ​​​​ host.Run();


  • Configure URLs and ports to listen on

By default ASP.NET Core binds to http://localhost:5000. To configure URL prefixes and ports, you can use the UseURLs extension method, the urls command-line argument or the ASP.NET Core configuration system. For more information, see Hosting.

Web Listener uses the Http.Sys prefix string formats. There are no prefix string format requirements that are specific to WebListener.


Top-level wildcard bindings (http://*:80/ and http://+:80) should not be used. Top-level wildcard bindings can open up your app to security vulnerabilities. This applies to both strong and weak wildcards. Use explicit host names rather than wildcards. Subdomain wildcard binding (for example, *.mysub.com) doesn't have this security risk if you control the entire parent domain (as opposed to *.com, which is vulnerable). See rfc7230 section-5.4 for more information.


Make sure that you specify the same prefix strings in UseUrls that you preregister on the server.

  • Make sure your application isn't configured to run IIS or IIS Express.

In Visual Studio, the default launch profile is for IIS Express. To run the project as a console application you have to manually change the selected profile, as shown in the following screen shot.

Select console app profile

How to use WebListener outside of ASP.NET Core

There are also Http.Sys registry settings.

Here's a code sample that demonstrates WebListener use outside of ASP.NET Core:


var​​ settings =​​ new​​ WebListenerSettings();



using​​ (WebListener listener =​​ new​​ WebListener(settings))


 ​​ ​​ ​​​​ listener.Start();


 ​​ ​​ ​​​​ while​​ (true)

 ​​ ​​ ​​​​ {

 ​​ ​​ ​​ ​​ ​​ ​​ ​​​​ var​​ context =​​ await​​ listener.AcceptAsync();

 ​​ ​​ ​​ ​​ ​​ ​​ ​​​​ byte[] bytes = Encoding.ASCII.GetBytes("Hello World: "​​ + DateTime.Now);

 ​​ ​​ ​​ ​​ ​​ ​​ ​​​​ context.Response.ContentLength = bytes.Length;

 ​​ ​​ ​​ ​​ ​​ ​​ ​​​​ context.Response.ContentType =​​ "text/plain";


 ​​ ​​ ​​ ​​ ​​ ​​ ​​​​ await​​ context.Response.Body.WriteAsync(bytes,​​ 0, bytes.Length);

 ​​ ​​ ​​ ​​ ​​ ​​ ​​​​ context.Dispose();

 ​​ ​​ ​​​​ }


Preregister URL prefixes and configure SSL

Both IIS and WebListener 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, if you're using WebListener you need to configure Http.Sys yourself. The built-in tool for doing that's netsh.exe.

The most common tasks you need to use netsh.exe for are reserving URL prefixes and assigning SSL certificates.

NetSh.exe isn't an easy tool to use for beginners. The following example shows the bare minimum needed to reserve URL prefixes for ports 80 and 443:


netsh http add urlacl url=http://+:80/ user=Users

netsh http add urlacl url=https://+:443/ user=Users

The following example shows how to assign an SSL certificate:


netsh http add sslcert ipport= certhash=MyCertHash_Here appid={00000000-0000-0000-0000-000000000000}".

Here is the official reference documentation:

The following resources provide detailed instructions for several scenarios. Articles that refer to HttpListener apply equally to WebListener, as both are based on Http.Sys.

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.

  • http.sys Manager provides UI for listing and configuring SSL certificates and options, prefix reservations, and certificate trust lists.

  • HttpConfig lets you list or configure SSL certificates and URL prefixes. The UI is more refined than http.sys Manager and exposes a few more configuration options, but otherwise it provides similar functionality. It cannot create a new certificate trust list (CTL), but can assign existing ones.

For generating self-signed SSL certificates, Microsoft provides command-line tools: MakeCert.exe and the PowerShell cmdlet New-SelfSignedCertificate. There are also third-party UI tools that make it easier for you to generate self-signed SSL certificates:


(Visited 178 times, 1 visits today)

Leave a Reply

Your email address will not be published. Required fields are marked *