Deploy your ASP.NET Core Web Application in IIS

When we try to deploy an ASP.NET Core application using the self-hosted approach via the dotnetcore CLI, the result is a kind-of a windows service. You have your application running inside a terminal (or a command-prompt) window listening over a configured PORT for requests.

When you close this terminal (or the command-prompt) the application shuts down, which is kind-of meh when you want to run a production-grade API or Web application.

This approach is such that any request from outside world is received by the hosting web server (such as IIS, Ngnix or Apache) which internally routes the request to the application running inside a kestrel web server module.

This approach provides an additional layer of security and abstraction, in addition to making use of the additional features of a full-fledged web server such as IIS or Ngnix which offer much more such as server variables or preprocessing or others. For deploying an ASP.NET Core application to a webserver we require to install the below things to keep things going:

Here’s a step-by-step process to deploy your ASP.NET Core application in IIS :

  1. Configure IIS

By default IIS is turn off, so we need to enable it this feature by checking into the Turn Windows Feature On / Off.

2. Download and install the ASP.NET Core Web Hosting Bundle: this provides all the necessary modules required for communication between the IIS and the Kestrel in which the application resides and works. You can download the hosting bundle from the official ASP.NET website

3. Once the Hosting bundle is installed and the IIS is running, type inetmgr in the Run (Windows + R) window. The IIS manager window opens. Expand on the Server that shows up in the left panel and right click on Application Pools. Select Add Application Pool.

An Application Pool is an IIS Process on which the applications reside and execute. On the New Application Pool dialog, enter the app pool name and select “No Managed Code” from the list. And then click on Save. A new Process which can handle an ASP.NET Core application is now created. Now we shall create a new website and add it to the created app pool.

4. Copy the application executables into a folder on top of which we shall create a website in IIS. We obtain the binaries by publishing our application with the below command within the project directory.

> dotnet publish -c Release

This generates the executables into the output path under /bin/release/netcoreappX.Y/publish/ path.

Copy all that content into the path C:\inetpub\wwwroot\MyAspNetCoreApp\ folder. Observe that once we enable IIS in our hosting machine, the inetpub directory with all its sub directories is created. This is where the IIS manager operates by default for the web applications.

  1. Once the contents are copied, create a Website and use the Physical Path above to point for under which the web application operates.

In the left panel that shows server details, right click on the Sites folder and select Add Websites. This is a container in which the application executables reside and run. A dialog appears which is configuration for the to-be-created website.

Specify the website name and the Physical Path under which we have placed the executables just now. And click on “select” next to the Application Pools and select the App Pool we created previously. Click on Save to create the website, and now the executables run under the container website using the process as in the app pool. To check the website, click on Browse option that occurs on the right side panel.

Now we should see our readersApi application up and running similar to any website. If something goes wrong, we get the error screen with 502.5 error code.

How to troubleshoot a broken IIS Deployment? (502.5 errors)

For that, we can have a few extra steps within our code, to troubleshoot in such scenarios.

In Program.cs when we create the WebHostBuilder for building the application, we can add two extra chaining methods which can help provide the stacktrace for us.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
	// add additional chain methods which capture startup errors 
	.UseSetting("detailedErrors", "true")

or in the newer dotnetcore3.x we have

	.ConfigureWebHostDefaults(wb =>
			wb.UseSetting("detailedErrors", "true");

In either case, when we add CaptureStartupErrors() chain method to the WebHost, any errors which occur during the app startup is captured by the IIS and put into Logs which can be viewed via Windows Event Viewer. This can help in getting a clear picture of what is happening during the application startup.

Pro tip: If all of these fails, we can use the dotnet core CLI hack to run it as a self-hosted application and see for ourselves what has gone wrong. Within the physical directory of the executables, we can run:

dotnet ./readersapi.dll --urls= 

which can run the application as a self-hosted application under the url http://localhost:5000 or the http://ip-of-the-system:5000

This can easily help us troubleshoot the issues. But the downside is that this approach works only when we have total control over the hosting system environment.

But when we are deploying over to a remote host environment or a cloud environment such as Azure app service, the above two method chains help us accurately find the issues.

Related link :

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.