Learning how to host ASP.NET Core in IIS is an essential skill for .NET developers deploying production web applications on Windows Server environments. Unlike classic ASP.NET applications that ran entirely inside IIS's worker process, ASP.NET Core uses a fundamentally different hosting model. The application runs in its own process, and IIS acts as a reverse proxy — forwarding HTTP requests to the Kestrel web server running inside your app. Understanding this architecture is the first step toward a stable, high-performance deployment.
Learning how to host ASP.NET Core in IIS is an essential skill for .NET developers deploying production web applications on Windows Server environments. Unlike classic ASP.NET applications that ran entirely inside IIS's worker process, ASP.NET Core uses a fundamentally different hosting model. The application runs in its own process, and IIS acts as a reverse proxy — forwarding HTTP requests to the Kestrel web server running inside your app. Understanding this architecture is the first step toward a stable, high-performance deployment.
The foundation of IIS hosting for ASP.NET Core is the ASP.NET Core Module (ANCM), a native IIS module that bridges IIS and your application. ANCM handles process management, forwards requests, and monitors the health of your app process. Without ANCM installed on the server, IIS simply cannot route requests to an ASP.NET Core application. This module ships with the .NET Hosting Bundle, a single installer that packages the .NET Runtime, ASP.NET Core Runtime, and ANCM together — making server setup straightforward even on fresh machines.
There are two distinct hosting models you will encounter when deploying ASP.NET Core to IIS: in-process and out-of-process. In in-process hosting, your application runs inside the IIS worker process (w3wp.exe), which reduces network latency between IIS and Kestrel since there is no loopback communication. Out-of-process hosting launches a separate Kestrel process, and IIS proxies requests to it over localhost. In-process hosting generally delivers better throughput and is the default for ASP.NET Core 2.2 and later, making it the preferred choice for most production deployments.
Before diving into configuration, it helps to understand why developers choose IIS over running Kestrel directly exposed to the internet. IIS provides mature features that take years to replicate: port 80/443 sharing across multiple sites, integrated Windows Authentication, robust SSL/TLS certificate management through the IIS Manager UI, request filtering, IP address restrictions, and deep integration with the Windows Event Log for diagnostics. For enterprise environments already standardized on Windows Server and IIS administration, these capabilities make IIS a natural and practical choice for hosting asp.net core on iis.
Configuration in ASP.NET Core IIS deployments flows through two main files: the web.config file generated during publish and the application's Program.cs or Startup.cs code. The web.config file instructs IIS on which handler to use (aspNetCore), the path to your application DLL, the hosting model, and environment variables. Modern .NET 6+ applications using the minimal hosting model configure IIS integration automatically when the project targets the correct SDK, but knowing how to read and modify web.config manually is invaluable for troubleshooting deployment issues.
Security is another critical dimension of IIS hosting. ASP.NET Core applications running under IIS operate under the application pool identity, which is a low-privilege virtual account by default. Granting only the minimum necessary file system permissions to that identity — read on the application folder, read/write on the logs directory — limits the blast radius of any potential vulnerability. Pairing IIS with HTTPS using a certificate from a trusted authority, configuring HSTS headers, and enabling HTTP/2 are additional hardening steps that every production deployment should include.
This guide walks through every stage of the process, from installing the .NET Hosting Bundle on Windows Server to configuring application pools, troubleshooting common startup errors, and optimizing performance. Whether you are deploying your first ASP.NET Core app or migrating a legacy application from classic ASP.NET, the sections below provide the specific steps, configuration snippets, and diagnostic techniques you need to succeed in a real-world IIS environment.
Open Server Manager, click Add Roles and Features, and select Web Server (IIS). Ensure you include the Management Console sub-feature. On Windows 10/11 developer machines, use Turn Windows features on or off in Control Panel and check Internet Information Services.
Download the .NET Hosting Bundle from the official Microsoft download page. This single installer deploys the .NET Runtime, ASP.NET Core Runtime, and the ASP.NET Core Module (ANCM) for IIS. Always match the bundle version to your application's target framework — mismatches cause 500.30 startup errors.
Run dotnet publish -c Release -o ./publish from your project directory. This compiles the app, resolves NuGet dependencies, and generates a web.config file pre-configured for IIS. Copy the publish output to a folder on the server — typically under C:\inetpub\wwwroot\YourApp or a custom path.
In IIS Manager, create a new Application Pool. Set the .NET CLR Version to No Managed Code — ASP.NET Core manages its own runtime and does not use the classic CLR loaded by IIS. Choose Integrated pipeline mode. Name the pool descriptively, such as YourAppPool, so it is easy to identify in Task Manager.
Right-click Sites in IIS Manager and choose Add Website. Point the physical path to your publish folder, assign the application pool you just created, and configure the binding — HTTP on port 80, or HTTPS on port 443 with an SSL certificate. For sub-application deployments, add an Application under an existing site instead.
Browse to the site URL in a browser. Check the Windows Event Log under Application for ANCM-related entries if the site returns an error page. The stdout log configured in web.config is invaluable for startup failures — enable it temporarily by setting stdoutLogEnabled to true, then disable it after resolving the issue.
Configuring IIS correctly after installation is where many developers encounter their first real roadblocks. The most common mistake is creating an application pool with the .NET CLR Version set to .NET CLR Version 4.0, which is the default and correct choice for classic ASP.NET applications, but wrong for ASP.NET Core. Because ASP.NET Core does not rely on the IIS-hosted CLR, setting the CLR version to No Managed Code is mandatory. When the setting is wrong, you may see cryptic handler errors, or the application pool may simply not start correctly.
Application pool identity deserves careful attention in production environments. By default, new pools use the ApplicationPoolIdentity identity, a virtual account with limited privileges. This identity needs Read & Execute permissions on the application's publish folder and Read, Write, and Execute permissions on the folder you configure for stdout logs. If your application writes files, accesses a local database file, or reads certificates from the file system, you must explicitly grant the pool identity the appropriate NTFS permissions. Forgetting this step produces Access Denied errors that appear only at runtime, not during local testing.
The web.config file generated by dotnet publish contains the aspNetCore handler configuration that tells ANCM how to run your app. The processPath attribute specifies the executable to launch — for framework-dependent deployments this is dotnet and for self-contained deployments it is the application executable itself. The arguments attribute provides the path to the application DLL. The hostingModel attribute, set to inprocess or outofprocess, determines whether the app runs inside w3wp.exe or in a separate process. Changing these values incorrectly is a frequent source of 500.30 and 500.0 errors in new deployments.
Environment variables are a powerful feature of the ANCM configuration. Inside the aspNetCore element in web.config, you can add an environmentVariables section that injects key-value pairs into the application process at startup. This is the standard way to set ASPNETCORE_ENVIRONMENT to Production on the server without modifying any compiled code. You can also inject connection strings, Azure Key Vault URIs, or feature flags through environment variables, keeping sensitive configuration out of source control and allowing per-environment overrides without redeployment.
HTTPS configuration in IIS for ASP.NET Core applications involves two distinct concerns. First, you bind an SSL certificate to the IIS site on port 443 using IIS Manager or PowerShell. Second, you configure your ASP.NET Core middleware to use HTTPS redirection and HSTS headers, ensuring that clients are redirected from HTTP to HTTPS and that browsers remember to use HTTPS for future visits.
In production, calling app.UseHttpsRedirection() and app.UseHsts() in your pipeline handles this automatically. IIS handles TLS termination, so by the time a request reaches your Kestrel process, it is already decrypted — your app sees an http scheme internally even though the client connected via https.
Multiple ASP.NET Core applications can coexist on a single IIS server by using separate application pools and either separate sites on different ports or sub-applications under a shared site. The sub-application approach places your app at a URL path such as https://example.com/api. In this scenario your ASP.NET Core app must be aware of its path base. You configure this by calling app.UsePathBase("/api") before other middleware, ensuring that route matching and generated URLs account for the prefix. Missing this step causes links and redirects within the app to break because they omit the sub-application path.
Logging is an area that deserves its own attention during IIS configuration. The Windows Event Log captures ANCM startup and shutdown events, making it the first place to look when a site returns a 502.5 or 500.30 error. For application-level logging, ASP.NET Core's built-in logging infrastructure writes to providers you configure in appsettings.json or Program.cs. In IIS deployments, adding the Microsoft.Extensions.Logging.EventLog package and registering the EventLog provider sends your application logs to the Windows Event Log as well, giving you a unified location for both host-level and application-level diagnostics without needing a separate log aggregation tool during initial troubleshooting.
In-process hosting runs your ASP.NET Core application inside the IIS worker process (w3wp.exe), eliminating the loopback network hop that out-of-process hosting requires. This model is the default for ASP.NET Core 2.2 and later and typically delivers measurably higher request throughput — often 30% or more in benchmarks — because ANCM forwards requests directly to the IISHttpServer implementation rather than proxying to a separate Kestrel process. To enable it, set hostingModel="inprocess" in web.config.
One important implication of in-process hosting is that only one app can run per IIS worker process at a time. If your server runs multiple ASP.NET Core sites, each must have its own application pool to ensure process isolation. A crash in one application will recycle only that pool's worker process, leaving other sites unaffected. In-process hosting also means that IIS's built-in recycling and health-monitoring features apply directly to your application process, giving you automatic recovery without additional configuration.
Out-of-process hosting launches a separate Kestrel process that listens on an internal port, while IIS acts as a reverse proxy forwarding public traffic to that port. ANCM manages the lifecycle of the Kestrel process — starting it when IIS receives the first request and restarting it if it crashes. This model is required for ASP.NET Core 2.1 and earlier but remains a valid choice when you need finer control over the hosting environment or want to run the app under a different user account than the IIS pool identity.
The trade-off is an additional network hop on every request. Because IIS and Kestrel communicate over a loopback TCP connection, latency is minimal in practice, but at high request volumes the difference can become measurable. Out-of-process deployments are often easier to debug locally because you can start the Kestrel process independently and attach a debugger without IIS involvement. For microservices deployed behind a load balancer, the extra flexibility may outweigh the marginal performance cost.
When you publish an ASP.NET Core application for IIS, you choose between framework-dependent deployment (FDD) and self-contained deployment (SCD). Framework-dependent deployments are smaller in size because the .NET Runtime is not bundled with the app — the server must have the correct runtime version installed via the Hosting Bundle. This model simplifies patching because you update the runtime on the server once, and all hosted apps benefit automatically. The web.config processPath is set to dotnet for FDD.
Self-contained deployments bundle the entire .NET Runtime alongside your application, making the deployment package larger (often 60–100 MB) but eliminating the runtime dependency on the server. This is useful when you cannot control which runtime versions are installed or when you need to run multiple apps targeting different runtime versions on the same server. The web.config processPath points directly to your app's .exe in this model, and no Hosting Bundle installation is required on the target machine.
Setting the application pool .NET CLR Version to No Managed Code is the single most impactful configuration step for ASP.NET Core on IIS. Unlike classic ASP.NET, ASP.NET Core manages its own runtime — IIS does not need to load the CLR. Leaving this set to .NET CLR Version 4.0 causes handler conflicts and prevents ANCM from working correctly, leading to cryptic 500-series errors on the first request.
Troubleshooting a broken ASP.NET Core IIS deployment can feel overwhelming when you are staring at a generic 500 error page, but a systematic approach turns even the most opaque failures into solvable problems. The first tool to reach for is the Windows Event Log.
Open Event Viewer, navigate to Windows Logs > Application, and filter by source for IIS AspNetCore Module or W3SVC. ANCM writes detailed startup failure messages here, including the exact exception or configuration error that prevented the process from starting. In many cases, the event log message alone is sufficient to identify and fix the problem within minutes.
The 500.30 error code specifically indicates that the ANCM in-process handler failed to start the application. This almost always means one of three things: the wrong .NET Runtime version is installed on the server (the app targets .NET 8 but only .NET 6 runtime is present), the web.config processPath or arguments are incorrect, or the application threw an unhandled exception during startup before it could accept requests. Enabling stdout logging temporarily by setting stdoutLogEnabled="true" and stdoutLogFile=".\logs\stdout" in the aspNetCore element of web.config captures the full startup output, including any exception stack trace that the Event Log truncates.
The 502.5 error means the process specified in processPath could not be started at all. For framework-dependent deployments, this usually means the dotnet executable is not on the system PATH or the Hosting Bundle was not installed correctly. Running dotnet --version from an elevated command prompt in the application directory quickly confirms whether the runtime is accessible. For self-contained deployments, a 502.5 often means the application executable is missing from the publish output or the publish folder path in IIS Manager does not match where the files actually are on disk.
Permission errors are another major category of deployment failures. When the application pool identity lacks read access to the publish folder, IIS returns a 403.14 directory listing error or a 500 with an access denied message in the Event Log. When it lacks write access to the data protection key ring directory, ASP.NET Core's data protection system throws an exception on startup, causing a 500.30.
Granting IIS AppPool\YourAppPool (substituting your actual pool name) the appropriate NTFS permissions resolves these issues. Running icacls from an administrative command prompt is the fastest way to inspect and modify permissions without navigating the Windows Explorer security dialog.
HTTP 400 and 413 errors in IIS-hosted ASP.NET Core applications often stem from IIS's default request limits rather than application code. IIS applies a maximum URL length of 4,096 bytes and a maximum request entity body size of 30 MB by default.
If your application accepts file uploads or long query strings, you may need to adjust the maxAllowedContentLength setting in the system.webServer/security/requestFiltering section of web.config, as well as update the kestrel limits in your application code. Both layers must permit the request size — IIS will reject oversized requests before they even reach Kestrel if only the application limit is adjusted.
Connection timeout mismatches between IIS and long-running ASP.NET Core operations are a subtler but impactful class of problems. IIS has a default idle connection timeout of 120 seconds. If your application performs operations that take longer — such as large data exports, report generation, or video processing — IIS may close the connection before the application has finished responding, leaving the client with a truncated response or a connection reset error. Adjusting the connection timeout in the IIS site's Advanced Settings, or redesigning the operation to use a background job with polling, addresses this class of issue cleanly.
Finally, when the application runs correctly locally but fails on the server, comparing the two environments systematically is the fastest path to resolution. Check runtime version parity with dotnet --info, compare the web.config files, verify that all required environment variables and connection strings are present on the server, and confirm that any external services (databases, APIs, caches) are reachable from the server's network. A structured environment comparison eliminates the guesswork that turns a half-hour fix into a multi-hour debugging session for developers unfamiliar with IIS deployment nuances.
Optimizing the performance of an ASP.NET Core application running on IIS begins with choosing the right hosting model. As discussed earlier, in-process hosting eliminates the loopback network hop and is the default for good reason. But beyond the hosting model selection, IIS offers several configuration knobs that directly impact throughput and responsiveness. The application pool queue length, for example, determines how many requests IIS queues before returning a 503 Service Unavailable response. Increasing this value — cautiously, and paired with application-level capacity planning — prevents request shedding during brief traffic spikes on otherwise healthy servers.
HTTP compression is a high-leverage, low-effort performance optimization that IIS handles at the server level before responses reach the client. Enabling dynamic and static compression in IIS reduces the size of HTML, CSS, JavaScript, and JSON responses by 60–80% on average, significantly reducing time-to-first-byte for users on slower connections. In IIS Manager, navigate to Compression under the server or site level and enable both static and dynamic compression. ASP.NET Core's response compression middleware is an alternative, but offloading compression to IIS is generally more efficient because it uses highly optimized native code and can cache compressed static files.
HTTP/2 support in IIS 10 (Windows Server 2016 and later) provides substantial performance benefits for applications serving many simultaneous requests, including multiplexing multiple requests over a single TCP connection and header compression via HPACK. IIS enables HTTP/2 automatically for HTTPS connections when the browser supports it — no additional configuration is required. However, in-process ASP.NET Core applications only benefit from HTTP/2 when using IIS 10 or later, so upgrading older server OS versions is a prerequisite. You can verify HTTP/2 is active by checking the response headers for HTTP/2 in your browser's developer tools Network tab.
Application pool recycling is a double-edged feature. Regular recycling clears memory leaks and accumulated state, improving long-term stability. But each recycle causes the first request after startup to be slower because the application must reload, rebuild caches, and warm up JIT-compiled code.
Configuring a warm-up URL in IIS's Application Initialization module — available on IIS 8.0 and later — triggers a request to a specified URL immediately after a recycle, pre-warming the application before real users notice the delay. Install the Application Initialization feature through Server Manager and set the startMode attribute on the application pool to AlwaysRunning to keep the process alive even when idle.
Output caching at the IIS level complements ASP.NET Core's built-in response caching middleware. IIS can cache entire HTTP responses for static content and certain dynamic responses, serving them directly from kernel-mode memory without ever engaging the managed application pipeline. This dramatically reduces CPU load for cacheable pages. Configure output caching through the IIS Manager or web.config's system.webServer/caching section. Ensure your cache-busting strategy — whether through versioned URLs, ETags, or cache-control headers — is correctly implemented so that stale cached responses do not reach users after a deployment.
Connection draining is an often-overlooked IIS feature that prevents in-flight requests from being abruptly terminated during application pool recycling or planned maintenance. When connection draining is configured, IIS stops sending new requests to a worker process that is being recycled but allows existing requests to complete up to a configured timeout. For APIs and applications where abrupt request termination causes data corruption or poor user experience, enabling connection draining with a reasonable timeout (30–60 seconds) greatly improves the quality of zero-downtime deployments. Configure it under Advanced Settings > Connection Draining on the application pool.
Monitoring IIS-hosted ASP.NET Core applications in production requires visibility at multiple layers. IIS provides detailed access logs in W3C format that record every request's status code, bytes sent, time taken, and client IP. Enabling these logs and shipping them to a centralized log analysis tool gives you a server-level view of error rates, latency percentiles, and traffic patterns. At the application level, integrating Application Insights or OpenTelemetry gives you distributed traces, dependency call durations, exception telemetry, and custom metrics. Together, these two layers provide end-to-end observability that makes diagnosing production issues fast and evidence-driven rather than speculative.
Practical day-to-day management of ASP.NET Core on IIS is much smoother when you build good deployment habits from the start. Scripting your deployment process using PowerShell or a CI/CD tool like GitHub Actions or Azure DevOps eliminates manual steps that introduce inconsistency. A typical automated pipeline publishes the app with dotnet publish, copies the output to the server using Web Deploy or a simple file copy over a network share, and then performs an IIS application pool recycle via the appcmd.exe command-line tool or the WebAdministration PowerShell module. Automating these steps means every deployment is identical and auditable.
Web Deploy (MSDeploy) is Microsoft's official deployment technology for IIS and deserves a mention for teams that need atomic deployments with rollback capability. Web Deploy can publish directly from Visual Studio or the dotnet publish pipeline to a remote IIS server over HTTPS, handling file synchronization, application pool management, and connection string transformations in a single operation.
The Web Deployment Agent Service on the target server must be installed and running, and the deploying user needs appropriate permissions. While the initial setup takes an hour or two, the payoff is reliable, repeatable deployments that teams can trigger from a CI/CD system without RDP access to the server.
Configuration management is a recurring challenge in IIS-hosted deployments because web.config is generated from your project configuration at publish time but also serves as the live server configuration file. A common pattern is to commit a base web.config to source control that contains your development settings, then use Web Deploy's config transforms (web.Release.config) or environment-specific variable substitution in your CI/CD pipeline to inject production values — connection strings, application insights keys, environment names — during deployment. This keeps secrets out of source control while ensuring every build produces a correctly configured deployment artifact.
Blue-green deployments are achievable on a single IIS server by maintaining two application pools and two physical directories (blue and green), and switching IIS site bindings to point to the newly deployed directory after verifying it starts correctly. While more complex than a simple in-place deployment, this pattern eliminates downtime and provides an instant rollback path — switch bindings back to the previous directory if the new deployment exhibits problems. Automating the switch with PowerShell and the WebAdministration module makes this feasible even for small teams without dedicated infrastructure tooling.
Handling application secrets securely in IIS-hosted ASP.NET Core applications requires moving away from storing connection strings in web.config in plain text. The recommended production approach is to use Windows Data Protection API (DPAPI) through ASP.NET Core's data protection system, store secrets in environment variables configured on the application pool, or integrate with Azure Key Vault for cloud-connected deployments. The Microsoft.Extensions.Configuration.EnvironmentVariables package reads environment variables automatically, and setting them at the application pool level in IIS (Advanced Settings > Environment Variables) scopes them to that specific pool, preventing leakage to other applications on the same server.
Keeping the server patched and the Hosting Bundle up to date is a security and stability responsibility that IIS deployments share with any other server infrastructure. Microsoft releases .NET patches on the second Tuesday of each month (Patch Tuesday). Applying these patches requires downloading and installing the new Hosting Bundle version — the old ANCM is replaced automatically.
After installing a new bundle, perform an IIS reset (iisreset /noforce) to ensure the new ANCM version is loaded. Maintaining a test environment that mirrors production allows you to validate that your application works correctly on each new runtime patch before applying it to production servers.
Finally, documenting your IIS server configuration is an investment that pays off during incident response, disaster recovery, and onboarding new team members. Capture the application pool settings, site bindings, enabled IIS features, Hosting Bundle version, and any custom web.config settings in a runbook or infrastructure-as-code definition.
Tools like Desired State Configuration (DSC) or Ansible with Windows support can codify this configuration so that a replacement server can be provisioned to an identical state in minutes rather than hours of manual setup. Treating your IIS server configuration as code — not institutional knowledge held by one developer — is the mark of a mature, reliable deployment practice.