What is the use of UseIISIntegration in C# Asp.net Core?

In ASP.NET Core applications, UseIISIntegration() is a crucial method used to configure the application to work with Internet Information Services (IIS) as a reverse proxy server. This method enables proper communication between IIS and the internal Kestrel web server that hosts your ASP.NET Core application.

How ASP.NET Core Hosting Works

ASP.NET Core applications use a WebHost object that serves as both the application container and web server. The WebHostBuilder is used to configure and create this WebHost with various server options.

Syntax

Following is the syntax for using UseIISIntegration() in the WebHostBuilder −

var host = new WebHostBuilder()
    .UseKestrel()
    .UseIISIntegration()
    .UseStartup<Startup>()
    .Build();

What UseKestrel() and UseIISIntegration() Do

UseKestrel() − Registers the IServer interface for Kestrel as the internal web server that will host your ASP.NET Core application. Kestrel is a cross-platform, high-performance HTTP server.

UseIISIntegration() − Configures the application to work with IIS as a reverse proxy in front of Kestrel. This method specifies settings such as which port Kestrel should listen on, how to handle forwarded headers, and other integration details.

Example

using System;
using System.IO;
using Microsoft.AspNetCore.Hosting;

public class Program {
    public static void Main(string[] args) {
        var host = new WebHostBuilder()
            .UseKestrel()
            .UseContentRoot(Directory.GetCurrentDirectory())
            .UseIISIntegration()
            .UseStartup<Startup>()
            .Build();
        
        Console.WriteLine("Starting web host...");
        host.Run();
    }
}

public class Startup {
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env) {
        if (env.IsDevelopment()) {
            app.UseDeveloperExceptionPage();
        }
        
        app.UseRouting();
        app.UseEndpoints(endpoints => {
            endpoints.MapGet("/", async context => {
                await context.Response.WriteAsync("Hello World from ASP.NET Core with IIS Integration!");
            });
        });
    }
}

The output when running this application would show −

Starting web host...
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.

Out-of-Process Hosting Model

Until ASP.NET Core 2.2, ASP.NET Core applications were hosted out-of-process in IIS, creating two separate processes −

• w3wp.exe − The IIS worker process that handles incoming HTTP requests
• dotnet.exe − The ASP.NET Core process running the Kestrel web server

In this scenario, UseIISIntegration() is essential for proper communication between these two processes. IIS acts as a reverse proxy, forwarding requests to Kestrel and returning responses to the client.

Modern ASP.NET Core Hosting

Starting with ASP.NET Core 2.2, Microsoft introduced in-process hosting where the application runs directly inside the IIS worker process, eliminating the need for a separate dotnet.exe process. However, UseIISIntegration() is still used for configuration when deploying to IIS environments.

Example with CreateDefaultBuilder

using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Hosting;

public class Program {
    public static void Main(string[] args) {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder => {
                webBuilder.UseStartup<Startup>();
                // UseIISIntegration() is included automatically in CreateDefaultBuilder
            });
}

Conclusion

UseIISIntegration() is essential for configuring ASP.NET Core applications to work properly with IIS as a reverse proxy. It handles the communication setup between IIS and Kestrel, manages port configuration, and ensures proper header forwarding for applications deployed in IIS environments.