Deploying ASP.NET Core Apps to IIS with Tips and Best Practices

ASP.NET Core significantly evolves Microsoft's ASP.NET web application development platform. ASP.NET Core has been rebuilt from the ground up to provide a lean, modular, and high-performance framework for building modern web apps on Windows, Linux, and macOS.

Key architectural differences from classic ASP.NET include:

• Side-by-side versioning - multiple ASP.NET Core versions can run on the same machine
• Standalone and lightweight - Runs separately from IIS in a process called Kestrel
• Modular HTTP request pipeline - Built as a series of middleware components
• Integration of modern client-side frameworks and build tools

This new architecture means ASP.NET Core apps can be hosted on IIS like traditional ASP.NET apps and self-hosted on a process like Kestrel. However, hosting ASP.NET Core apps on IIS still provides benefits like:

• Ability to run side-by-side with existing ASP.NET applications
• Takes advantage of IIS scalability and security features
• Centralized management of apps through IIS Manager
• Support for Windows authentication and delegated auth
• Integration with Windows Server features like SSL certificates In this post, we'll go through the steps required to deploy ASP.NET Core applications to IIS on Windows Server successfully. We'll look at the IIS components needed, publishing and deploying the app, configuring IIS settings correctly, and some troubleshooting tips for common deployment issues.

Preparing Your ASP.NET Core App for IIS Deployment

Before deploying your ASP.NET Core application to IIS, there are a few key steps to ensure your application is properly configured and ready for a smooth deployment:

• Review your project's Target Framework Moniker (TFM) in the project file and ensure it is set to the desired ASP.NET Core version. This controls which .NET Core runtime your app will use.
• Set the Platform target in project settings to "Any CPU". This allows your app to run as 64-bit on 64-bit Windows servers, taking advantage of the full CPU and memory.
• Enable proxy load balancing in Startup.cs if needed, by calling app.UseForwardedHeaders() to process X-Forwarded-* headers from proxies and load balancers.
• Optionally set application pool name, .NET CLR version, and other IIS settings in the web.config file. This allows controlling IIS behavior without the UI.
• Ensure your app runs locally using the desired IIS Express version, matching the IIS version on your servers. Test with IIS admin rights.
• Set up logging providers like Serilog or NLog to enable logging of errors and application behaviour when running on IIS. Validate any external app dependencies are deployed with the app or referenced as part of publishing. Taking these steps will validate your ASP.NET Core app runs properly in an IIS environment and prevent issues once deployed. Let me know if you need any clarification or have additional questions!

Installing IIS Components for ASP.NET Core

Here are the key steps to cover when installing IIS components needed to host ASP.NET Core apps:

• Install the ASP.NET Core Hosting Bundle: This bundle includes the ASP.NET Core Module, which handles loading the .NET Core runtime and interfacing with IIS. You can install it via the Web Platform Installer or download an MSI installer directly.
• Install the appropriate .NET Core runtime: Your ASP.NET Core app will be built targeting a specific .NET Core runtime version, such as .NET Core 3.1 or .NET 6. The corresponding runtime needs to be installed on the IIS server.
• Enable IIS modules: Make sure common IIS modules like StaticFileModule, DefaultDocumentModule, DirectoryBrowsingModule etc. are installed and enabled for the application. These are required for serving static files and directory browsing.
• Install UrlRewrite Module: The IIS UrlRewrite module provides the ability to rewrite inbound request URLs and implement URL redirect rules. It allows implementing user-friendly URLs.
• Set application pool to No Managed Code: This runs the app pool without loading the CLR and prevents .NET Core apps from loading the incompatible .NET Framework runtime.
• Install ANCM V2: The ASP.NET Core Module v2 (ANCMv2) handles proxying requests to the Kestrel backend and is required for IIS hosting.
• Enable delegation: The delegation options need to be enabled for the application pool identity user account to allow it to access the app's file system and directories.
• Restart IIS: After installing components, IIS will need to be restarted for changes to take effect.

Publishing and deploying to IIS

Here are the key steps to explain for publishing and deploying an ASP.NET Core app to IIS:

• Publish the application: Use the dotnet publish command to compile your app and package all the necessary files and dependencies into a publish folder. This creates a ready-to-deploy bundle.
• Copy publish folder to a web server: The published folder can be copied to the web server using tools like Robocopy, PowerShell, FTP/SFTP, or as part of CI/CD pipelines like Azure DevOps.
• Grant file permissions: If using file system publishing, the app pool's user account will need read/execute permissions on the app folder and files. Access can be granted directly or via an ACL.
• Configure app pool: A new app pool in IIS needs to be configured for the ASP.NET Core app with proper settings for .NET CLR version, 32/64-bit, Managed Pipeline mode, etc.
• Set virtual directory: Configure a virtual directory or IIS website that points to the deployed app folder. Bind it to the newly created app pool.
• Warm up the app: Make an initial request to the app to allow the CLR and dependencies to load. The first request will be slow.
• Configure autoscaling: Using the Application Request Routing (ARR) plugin is recommended to add autoscaling capabilities as the app scales.
• Set up CI/CD pipeline: Automate publishing and deployment by setting up a continuous integration pipeline with tools like Azure DevOps. Make sure to use IIS web.config settings where applicable to control IIS behavior.

Configuring the IIS Application

Here are some key steps to explain when configuring an ASP.NET Core application deployed to IIS:

• Add the application as a website or virtual directory in IIS Manager. This will create the binding with the hostname and ports.
• Set the application pool the IIS site is running under. This should be a dedicated app pool for the ASP.NET Core app with proper config settings.
• In the application pool, configure the .NET CLR version to match the app's target .NET Core runtime. Also, set 32 vs 64-bit.
• In web.config, add the aspNetCore section for IIS integration settings. Set the processPath to point to the app's .dll.
• Configure the stdoutLogEnabled and stdoutLogFile elements to enable and configure logging to file from ASP.NET Core.
• For apps listening on non-standard ports, add and set up the HTTP protocol mapping in web.config.
• Enable proxy settings like forwarded headers and configuring proxy IP/domain ranges in web.config if sitting behind a proxy.
• Add rewrite rules for URL redirect/rewriting in the system.webServer section of web.config.
• Make sure Windows,anonymous authentication is enabled appropriately. Disable any unneeded IIS modules.
• Confirm the application pool identity has proper permissions to the app folder using ACLs.
• Load up the IIS site and verify ASP.NET Core app loads. Check logs for any errors.

Troubleshooting Common IIS Deployment Issues

Here are some common troubleshooting tips for issues when deploying ASP.NET Core apps to IIS:

• 401 Unauthorized errors: Check that Windows Authentication is enabled in IIS and that the application pool identity has NTFS permissions to the app folder.
• 500.30 In-Process Start Failure errors: Ensure the proper .NET Core runtime is installed and that the app pool is set to No Managed Code. Check app pool identity has access.
• App immediately stops or recycles: Adjust idle timeout settings in the app pool advanced settings. Ensure memory limits are adequate.
• Errors loading .NET Core DLLs: Confirm the .NET Core runtime version matches what the app is targeting. Repair/reinstall the .NET Core Hosting Bundle if needed.
• HTTP Error 502.5 - Process Failure: Increase process model recycling limits for the app pool. Check AppEvent log for worker process crashes.
• HTTP Error 500.19 Internal Server Error: Check for syntax errors in web.config, including invalid characters.
• App needs hot restart on config changes: Enable the IIS Application Initialization module to rerun the app when web.config is changed.
• Enable failed request tracing: This provides detailed debugging information on IIS errors at the platform handler level.
• Check IIS modules are added and integrated properly with the ASP.NET Core Module for IIS interoperability.
• Compare with a known good baseline config: Diff web.config and IIS settings against a working reference site.

Conclusion

Deploying ASP.NET Core applications to IIS offers an exceptional hosting environment, perfect for scaling and robustness on Windows servers. This process, however, necessitates meticulous configuration of IIS components like the ASP.NET Core Module and careful adjustment of application pool settings to align with the app's target framework. Adhering to best practices during the publication of the distributable app, granting precise file permissions, meticulous configuration of the IIS site directory, and precise configuration of web.config values are pivotal for ensuring a seamless deployment experience. If you need expert assistance, consider hiring .NET Core developers to streamline the process.

The advanced logging and tracing capabilities inherent in IIS facilitate the troubleshooting of common challenges such as application errors, instability, and crashes. By tailoring the IIS configuration to align harmoniously with your ASP.NET Core app, developers can optimize the benefits of IIS's administration, security features, and management advantages, thereby creating a foundation for deploying enterprise-grade .NET applications. By meticulously following the outlined steps for installation, configuration, and troubleshooting, developers can confidently host ASP.NET Core-based solutions on IIS while leveraging the full potential of ASP.NET Development.