ASP.NET Core on IIS - MSDN Documentation

Introduction to IIS and ASP.NET Core

Internet Information Services (IIS) is a highly extensible and secure web server from Microsoft. ASP.NET Core is a cross-platform, high-performance, open-source framework for building modern, cloud-enabled, Internet-connected applications. This document outlines the steps and considerations for deploying ASP.NET Core applications on IIS.

Prerequisites

IIS Installed: Ensure IIS is installed on your Windows server. This can be done via "Turn Windows features on or off".
.NET Hosting Bundle: Download and install the latest .NET Core Hosting Bundle which includes the IIS ASP.NET Core Module.
ASP.NET Core Application: A published ASP.NET Core application ready for deployment.

Deployment Steps

1. Publish Your ASP.NET Core Application

Before deploying, publish your application using the appropriate framework-dependent or self-contained deployment mode. For IIS, framework-dependent is generally recommended.

dotnet publish -c Release -o "C:\inetpub\wwwroot\YourAppName"

Replace C:\inetpub\wwwroot\YourAppName with your desired deployment path.

2. Configure IIS

Create a New IIS Website

Open IIS Manager.
Expand the server node, right-click on Sites, and select Add Website....
Site name: Enter a descriptive name (e.g., YourAppName).
Physical path: Browse to the publish directory you created in Step 1 (e.g., C:\inetpub\wwwroot\YourAppName).
Binding: Configure the binding information (e.g., port 80, a specific hostname).
Click OK.

Configure Application Pool

By default, a new application pool is created. Ensure it's configured correctly:

In IIS Manager, select the Application Pools node.
Find the application pool associated with your new site.
Right-click and select Basic Settings....
Ensure the .NET CLR Version is set to No Managed Code. This is crucial for ASP.NET Core as it runs out-of-process.
Verify the Pipeline mode is set to Integrated.

3. IIS ASP.NET Core Module Configuration

The .NET Hosting Bundle installs the IIS ASP.NET Core Module (ANCM), which manages the communication between IIS and your ASP.NET Core application. The ANCM is automatically configured for applications published with the correct structure.

Important: For ASP.NET Core 2.0 and later, the ANCM is usually configured automatically. If you encounter issues, manually check the web.config file in your application's publish directory. It should contain entries similar to this:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <remove name="aspNetCore"/>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet"
                  arguments=".\YourAppName.dll"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess">
        <environmentVariables>
          <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
        </environmentVariables>
      </aspNetCore>
    </system.webServer>
  </location>
</configuration>

Make sure arguments points to your application's entry point DLL. Adjust hostingModel as needed (inprocess or outofprocess).

Troubleshooting Common Issues

502 Bad Gateway: Often indicates the ASP.NET Core application failed to start. Check application logs, ensure the correct .NET version is installed, and verify the web.config configuration.
HTTP Error 500.30 - ANCM Failure: Check the stdoutLogEnabled and stdoutLogFile settings in web.config for detailed error messages.
Permissions: Ensure the IIS Application Pool identity has read and execute permissions on your application's deployment folder.

Advanced Configurations

Environment Variables

You can set environment variables for your ASP.NET Core application within the web.config file, which is useful for managing different deployment environments (e.g., Development, Staging, Production).

Logging

The ANCM provides options for logging. Enabling stdoutLogEnabled and specifying a stdoutLogFile can be invaluable for debugging startup issues.

HTTPS Configuration

Configure SSL bindings in IIS and ensure your ASP.NET Core application is set up to use HTTPS. You might need to adjust the ASPNETCORE_HTTPS_PORT environment variable or use a reverse proxy setup.