.NET IIS Deployment

Introduction

Deploying your .NET application to Internet Information Services (IIS) is a common approach when hosting web applications on Windows servers. IIS (Internet Information Services) is Microsoft's web server that comes built into Windows operating systems. It provides a robust, secure, and scalable environment for hosting .NET applications.

In this guide, we'll walk through the process of deploying a .NET application to IIS, from preparing your application to configuring the server and maintaining your deployment. Whether you're deploying an ASP.NET Core, ASP.NET MVC, or other .NET web application, this guide will help you navigate the deployment process.

Prerequisites

Before we start with deployment, make sure you have:

• A .NET application ready for deployment
• Windows server with IIS installed (or Windows 10/11 with IIS enabled)
• Administrative access to the server
• .NET Core/.NET hosting bundle installed (for .NET Core/.NET applications)

Setting Up IIS

Installing IIS

If you don't have IIS installed already, you'll need to enable it:

1. On Windows Server:

   • Open Server Manager
   • Click "Add roles and features"
   • Select "Web Server (IIS)" role
   • Follow the wizard to complete installation

2. On Windows 10/11:

   • Go to Control Panel
   • Navigate to "Programs and Features" → "Turn Windows features on or off"
   • Check "Internet Information Services" and expand to select desired features
   • Click OK to install

Installing .NET Hosting Bundle

For .NET Core or .NET 5+ applications, you need to install the appropriate hosting bundle:

1. Download the hosting bundle for your .NET version from Microsoft's download page
2. Run the installer with administrative privileges
3. Follow the installation steps
4. Restart the server or IIS after installation

Preparing Your Application for Deployment

Publishing Your Application

Before deploying to IIS, you need to publish your application:

bash

# Using the .NET CLI
dotnet publish -c Release -o ./publish

# Using Visual Studio: Right-click project -> Publish -> Choose Folder target

The publish process creates a deployment-ready version of your application with all dependencies.

Understanding the Published Output

The published output will contain:

• Your application's DLLs
• Web.config or appsettings.json configuration files
• Static content (CSS, JS, images)
• Runtime dependencies

Creating an IIS Website

Now that your application is published, let's create a website in IIS:

1. Open IIS Manager (type inetmgr in the Run dialog)
2. In the Connections panel, right-click on "Sites" and select "Add Website"
3. Fill in the website details:
   • Site name: A meaningful name for your application
   • Physical path: The directory where your published files are located
   • Binding: Configure the hostname, IP address, and port
   • Click OK to create the website

Here's a visual representation of what you'll configure:

Site name: MyDotNetApp
Physical path: C:\inetpub\wwwroot\MyDotNetApp
Binding type: http
IP address: All Unassigned
Port: 80
Host name: mydotnetapp.local

Configuring Application Pools

Application pools isolate web applications from each other, providing better security and reliability:

1. In IIS Manager, click on "Application Pools"
2. Right-click and select "Add Application Pool"
3. Configure the pool settings:
   • Name: Match your website name for clarity
   • .NET CLR Version:
     • For .NET Framework: Choose appropriate version
     • For .NET Core/.NET: Select "No Managed Code" as .NET Core has its own runtime
   • Managed pipeline mode: Typically "Integrated"
4. Click OK to create the application pool
5. Go back to your website, right-click and select "Basic Settings"
6. Select the application pool you created and click OK

Web.config Configuration

The web.config file plays a crucial role in IIS deployment. For .NET Core/.NET 5+ applications, it's generated during publishing, but you may need to customize it.

For .NET Core/.NET 5+ Applications

Here's an example web.config for an ASP.NET Core application:

xml

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

For .NET Framework Applications

.NET Framework applications typically have more detailed web.config files:

xml

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.web>
    <compilation debug="false" targetFramework="4.8" />
    <httpRuntime targetFramework="4.8" />
  </system.web>
  <system.webServer>
    <modules runAllManagedModulesForAllRequests="true" />
  </system.webServer>
</configuration>

Setting Up Permissions

Proper permissions are crucial for your application to run correctly:

1. Locate your website's folder
2. Right-click on it and select "Properties"
3. Go to the "Security" tab
4. Click "Edit" and then "Add"
5. Add the appropriate IIS user:
   • For application pool identity: IIS AppPool\[YourAppPoolName]
   • For IIS_IUSRS group (all IIS applications)
6. Grant at least "Read" and "Execute" permissions
7. For folders requiring write access (like for file uploads), add "Modify" permissions

Testing Your Deployment

After setting up your website, it's time to test it:

1. Open a web browser on the server
2. Navigate to http://localhost
3. If you've set up a specific hostname, make sure it's in your hosts file (C:\Windows\System32\drivers\etc\hosts)
4. Verify that your application loads correctly

Common Deployment Scenarios

Deploying to a Sub-application

You might want to deploy your application as a sub-application under an existing website:

1. In IIS Manager, right-click on an existing website
2. Select "Add Application"
3. Set an alias (e.g., "myapp")
4. Select the physical path to your published files
5. Choose the application pool
6. Click OK

Now your application will be available at http://yourmaindomain/myapp.

Setting Up HTTPS with SSL

For secure communication, you should enable HTTPS:

1. Obtain an SSL certificate (either from a certificate authority or create a self-signed certificate)
2. In IIS Manager, select your website
3. Click "Bindings" in the Actions panel
4. Click "Add" to add a new binding
5. Select "https" from the Type dropdown
6. Select your SSL certificate
7. Click OK

Type: https
IP address: All Unassigned
Port: 443
Host name: mydotnetapp.local
SSL certificate: [Select your certificate]

Configuring URL Rewrite Rules

URL rewriting can be useful for clean URLs or redirecting HTTP to HTTPS:

1. Install the URL Rewrite module for IIS if not already installed
2. In IIS Manager, select your website
3. Double-click the URL Rewrite icon
4. Click "Add Rule(s)" in the Actions panel

Here's an example web.config snippet for HTTP to HTTPS redirection:

xml

<system.webServer>
  <rewrite>
    <rules>
      <rule name="HTTPS Redirect" stopProcessing="true">
        <match url="(.*)" />
        <conditions>
          <add input="{HTTPS}" pattern="^OFF$" />
        </conditions>
        <action type="Redirect" url="https://{HTTP_HOST}/{R:1}" redirectType="Permanent" />
      </rule>
    </rules>
  </rewrite>
</system.webServer>

Troubleshooting Common Issues

Application Pool Crashes

If your application pool keeps crashing:

1. Check the Windows Event Viewer for error details
2. Verify your application's dependencies
3. Ensure correct .NET version is installed
4. Check permissions on application folders

500 Internal Server Errors

When you see generic 500 errors:

1. Enable detailed error messages in IIS
   • Select your site in IIS Manager
   • Double-click "Error Pages"
   • Click "Edit Feature Settings"
   • Select "Detailed errors"
2. Check application logs
3. Review the Windows Event Viewer

502.5 Process Failure

This typically occurs in .NET Core applications when the process can't start:

1. Make sure the .NET Hosting Bundle is installed
2. Verify application pool settings
3. Check if your app runs from command line with dotnet YourApp.dll
4. Look for logs in the logs directory of your application

Best Practices for IIS Deployment

1. Use deployment automation: Tools like GitHub Actions, Azure DevOps, or Jenkins can automate your deployment process

2. Implement proper logging: Configure application logging to help troubleshoot issues:

csharp

// Program.cs in ASP.NET Core
builder.Host.ConfigureLogging(logging =>
{
    logging.ClearProviders();
    logging.AddConsole();
    logging.AddEventLog();
    logging.AddFile("logs/app-{Date}.log");
});

3. Set up health checks: Implement health check endpoints to monitor your application's status

4. Configure appropriate recycling: Set up application pool recycling based on your application's needs

5. Set up monitoring: Use tools like Application Insights or other monitoring solutions

Deployment Scripts and Automation

To automate your deployment process, you can create PowerShell scripts:

powershell

# Example PowerShell deployment script
param (
    [string]$WebsiteName = "MyDotNetApp",
    [string]$SourcePath = "C:\Builds\MyDotNetApp\publish\",
    [string]$DestinationPath = "C:\inetpub\wwwroot\MyDotNetApp\"
)

# Stop the website
Write-Host "Stopping website $WebsiteName..."
Stop-WebSite -Name $WebsiteName

# Copy files
Write-Host "Copying files from $SourcePath to $DestinationPath..."
if (Test-Path $DestinationPath) {
    Remove-Item -Path "$DestinationPath\*" -Recurse -Force
}
else {
    New-Item -ItemType Directory -Path $DestinationPath -Force
}
Copy-Item -Path "$SourcePath\*" -Destination $DestinationPath -Recurse -Force

# Start the website
Write-Host "Starting website $WebsiteName..."
Start-WebSite -Name $WebsiteName

Write-Host "Deployment complete!"

Summary

Deploying .NET applications to IIS provides a robust hosting environment for your web applications. In this guide, we've covered:

• Setting up IIS and installing the necessary components
• Publishing your .NET application
• Creating websites and application pools in IIS
• Configuring proper permissions and settings
• Setting up SSL and URL rewriting
• Troubleshooting common issues
• Best practices and automation

By following these steps, you should be able to successfully deploy your .NET application to IIS and ensure it runs reliably in a production environment.

Additional Resources

• Official Microsoft Documentation on IIS Hosting
• .NET Core Hosting Bundle
• IIS URL Rewrite Module
• Application Request Routing for IIS

Exercises

1. Deploy a simple ASP.NET Core application to IIS and configure it to use HTTPS.
2. Create a PowerShell script that automates the deployment process for your application.
3. Set up URL rewrite rules to redirect all traffic from HTTP to HTTPS.
4. Configure your application to use a custom application pool with specific recycling settings.
5. Implement logging in your application and configure it to write logs to a specific folder accessible by IIS.