NGINX for ASP.NET Core In-Depth

There are only two things a web server needs to be……..really fast…..and secure.

Muhammad Rehan Saeed


NGINX (Pronounced engine-x) is a popular open source web server. It can act as a reverse proxy server for TCP, UDP, HTTP, HTTPS, SMTP, POP3, and IMAP protocols, as well as a load balancer and a HTTP cache.

NGINX in fact overtook Apache as the most popular web server among the top 1000 websites. After playing with it for a while now, I have to say that I can see why.

There are two flavours of NGINX. The first is the open source version which is free, the other is called NGINX Plus and provides some more advanced features (all of which can be replicated with open source plugins but with a lot effort) and proper support but at the cost of a few thousand dollars.

There is a Windows version of NGINX but I wouldn’t recommend using it for real as it doesn’t perform as well as the Linux version and it’s not as well tested. You can however use it to tryout NGINX.

Alternatively, if you are running on Windows 10 Anniversary Update, you can install Bash for Windows and install the linux version. However the process is not that straightforward. Again, the caveat is that it can only be used for testing and not in production.


NGINX has no UI, it’s all command line driven but don’t let that put you off, the CLI interface only has three commands you actually need:

  1. Check my NGINX config (nginx -t).
  2. Load my NGINX config (nginx -s reload).
  3. By default the nginx.conf file is located in the NGINX installation folder. You can use that file or your own using (nginx -c [nginx.conf File Path]).

IIS on the other hand does have a UI and what a travesty it is. It hasn’t really changed for several years and really needs a usability study to hack it to pieces and start again.

The command line experience for IIS is another matter. It has very powerful IIS extensions you can install and the latest version of IIS even has an API that you can use to make simple HTTP calls to to update it.

Configuration is where NGINX shines. It has a single super simple nginx.conf file which is pretty well documented. IIS is also actually pretty simple to configure if you only rely on the web.config file.

Setting up NGINX

The ASP.NET Core Documentation site has some very good documentation on how to get started on Ubuntu. Unfortunately, it’s not as simple as just installing NGINX using ‘apt-get install nginx’, there are a few moving parts to the process and a lot more moving parts if you want to install any additional modules.

If you’re on Windows, as I mentioned earlier you have the options of installing NGINX using Bash for Windows 10 Anniversary Update but I couldn’t get this working. Alternatively you can download the NGINX executable for Windows. If you do this, beware that NGINX tries to start on port 80 and there are a number of things that use that port already on Windows:

  1. Skype uses port 80 (Why?), turn it off in the advanced settings.
  2. Turn off IIS.
  3. Stop the SQL Server Reporting Services service.

Once you have NGINX setup, you need to run your ASP.NET Core app using the Kestrel web server. Why does ASP.NET Core use two web servers? Well Kestrel is not security hardened enough to be exposed on the internet and it does not have all of the features that a full blown web server like IIS or NGINX has. NGINX takes the role of a reverse proxy and simply forwards requests to the Kestrel web server. One day this may change. Reliably keeping your ASP.NET Core app running in Linux is also described in the ASP.NET Core Documentation.

Aiming For The Perfect Config File

You’ve got NGINX running, all you need now is a nginx.conf file to forward requests from the internet to your ASP.NET Core app running using the Kestrel web server.

I’ve taken the time to combine the recommendations from the HTML5 Boilerplate project, the ASP.NET 5 NGINX Documentation, the NGINX Docs and my own experience to build the nginx.config (and mime.types file) file below specifically for the best performance and security and to target .NET Core apps.

Not only that but I’ve gone to extreme lengths to find out what every setting actually does and have written short comments describing each and every setting. The config file is self describing, from this point forward it needs no explanation.

NGINX Modules

Like IIS, NGINX has modules that you can add to it, to provide extra features. There are a number of them out there. I’ve listed two that I care about and you should too.

Installing modules is best done by downloading the NGINX source, as well as the modules you need and then compiling the application. There is a feature called dynamic modules which lets you dynamically load additional separate modules after installing NGINX but the link suggests third party modules may not be supported so I didn’t try it out.

HTTP 2.0

The ngx_http_v2_module module lets you use HTTP 2.0. HTTP 2.0 gives your site a very rough ~3-5% performance boost and thats before using any of it’s more advanced features which not many people are using yet.

Brotli Compression

The ngx_brotli module lets NGINX use the Brotli compression algorithm. If you haven’t heard about Brotli, you should take note. Brotli is a compression algorithm built by Google and is perhaps set to take over from GZIP as the compression algorithm of the web. It’s already fully supported on Firefox, Chrome and Opera with only Edge lagging behind.

Depending on how much extra CPU power you are wanting to use (it can max out your CPU at the highest compression levels, which could DoS your site if someone makes too many requests, so be careful what compression level you choose), Brotli can compress files and save you around 10-20% bandwidth over what GZIP can do! Those are some significant savings.

ASP.NET MVC Boilerplate

I’ve updated the ASP.NET MVC Boilerplate project template, so you can now choose the web server (IIS or NGINX) you want to use. If you choose to use NGINX, you can have it pre-configured just for you, right out of the box.

ASP.NET MVC Boilerplate Web Server Feature lets you choose from ISS or NGINX.


The main reason, I’ve been taking a serious look at NGINX is hard cash. Running Linux servers in the cloud can costs around half the price of a Windows server. Also, you can nab yourself some pretty big performance wins by using the modules I’ve listed.

There are some interesting overlaps between ASP.NET Core and NGINX. Both can be used to serve static files, HTTP headers, GZIP files etc. I think ASP.NET Core is slowly going to take on more of the role that traditionally was the preserve of the web server.

The cool thing is that because ASP.NET Core is just C#, we’ll have a lot of power to configure things using code. NGINX lets you do more advanced configuration using the Lua language and soon even in JavaScript but putting that logic in the app where it belongs and where you can do powerful things makes sense to me.