Deploying ASP.NET MVC Applications to IIS Using Web Deploy

by

This technical guide outlines the process of deploying an ASP.NET MVC application to a remote IIS server using Web Deploy. Web Deploy (also known as MSDeploy) provides a streamlined method for deploying web applications without the need for manual file copying, making the deployment process more efficient and less error-prone.

Prerequisites

  • Visual Studio (2017 or later) installed on your development machine
  • IIS (Internet Information Services) installed on the target server
  • Administrative access to both machines
  • Your ASP.NET MVC application ready for deployment

Step 1: Install Web Deploy on Both Machines

On Your Development Machine

Web Deploy typically comes pre-installed with Visual Studio. If it’s not already installed:

  1. Download Web Deploy from the Microsoft Download Center
  2. Run the installer with default options
  3. Verify installation by checking if the Web Publishing feature is available in Visual Studio

On Your Target Server

  1. Download the Web Deploy installer on your development machine
  2. Transfer the installer to the target server using Remote Desktop file sharing
  3. Run the installer on the target server with the following options:
    • Select “Complete” installation
    • Ensure “IIS Deployment Handler” is selected
    • Install all prerequisites if prompted

Step 2: Configure the Web Deployment Service on the Target Server

  1. Open IIS Manager on the target server
  2. Select the server node in the left panel
  3. Double-click on “Management Service” in the Features View
  4. Configure the following settings:
    • Check “Enable remote connections”
    • Select “Windows credentials or IIS Manager credentials”
    • Keep the default port (8172)
    • Click “Apply” to save changes
  5. Start the service if it’s not already running by clicking “Start” in the Actions panel

Step 3: Configure Your Website for Deployment

  1. In IIS Manager, navigate to your website or create a new one:
    • Under “Sites”, locate or create your website
    • Ensure the website is properly configured with the correct application pool (set to the appropriate .NET Framework version)
  2. Right-click on the website and select “Deploy” > “Configure Web Deploy Publishing”
  3. In the configuration dialog:
    • Verify the Windows user that will have publishing permissions
    • Enter your SQL Server connection string if database deployment is needed
    • The publishing URL will be automatically generated (typically https://[servername]:8172/msdeploy.axd)
    • Specify a location to save the publish settings file
  4. Click “Setup” to generate the publishing profile

The publish settings file (.publishsettings) contains all the necessary connection information and credentials needed to deploy your application from Visual Studio.

Step 4: Transfer the Publish Settings File to Your Development Machine

  1. After generating the publish settings file, transfer it to your development machine:
    • Use Remote Desktop file sharing (enable drive sharing before connecting)
    • Your local drives will appear as network drives in the remote session
    • Copy the .publishsettings file to your local machine

Step 5: Import the Publish Profile in Visual Studio

  1. Open your ASP.NET MVC project in Visual Studio
  2. Right-click on your project in Solution Explorer and select “Publish…”
  3. In the Publish dialog, click “Import Profile…”
  4. Browse to the .publishsettings file you transferred from the server
  5. Visual Studio will import all the connection settings and create a publish profile

Step 6: Configure Deployment Settings

After importing the profile, review and configure additional settings:

  1. In the “Settings” tab:
    • Verify that the configuration is set to “Release”
    • Check the database publish options if applicable
    • Review the File Publish Options section:
      • Check “Remove additional files at destination” if you want to ensure a clean deployment
      • Select appropriate options for precompilation
  2. Save your settings

Step 7: Deploy Your Application

  1. Click the “Publish” button to start the deployment process
  2. Visual Studio will:
    • Build your application in Release mode
    • Package the files for deployment
    • Connect to the remote server
    • Deploy your application according to your settings
  3. Monitor the Output window in Visual Studio for progress and any errors
  4. When the deployment is complete, Visual Studio will show a success message and may open a browser to your deployed application

Step 8: Verify the Deployment

  1. On the server, open IIS Manager and verify that your application files have been deployed to the correct location
  2. Check the application pool to ensure it’s running
  3. Test your application by browsing to it on the server

Troubleshooting

If you encounter issues during deployment:

  • Connection Problems:
    • Verify that the Web Management Service is running on the target server
    • Check that port 8172 is not blocked by a firewall
    • Ensure the user credentials have sufficient permissions
  • Deployment Failures:
    • Check the Visual Studio Output window for detailed error messages
    • Verify that the application pool is correctly configured
    • Ensure the server has all required dependencies installed
  • Database Issues:
    • Verify the connection string is correct
    • Ensure the database user has appropriate permissions
    • Check that SQL Server is running and accessible

HTTP Error 500.19 – Configuration Section Locked

Symptom: You see an error message stating “This configuration section cannot be used at this path. This happens when the section is locked at a parent level.”

Solution:

  1. Open IIS Manager
  2. Select the server name (not a specific site)
  3. Double-click on “Feature Delegation”
  4. Find “Handler Mappings” in the list and change its value from “Read Only” to “Read/Write”
  5. Also do the same for “Modules” if needed
  6. Restart IIS or the application pool

HTTP Error 500.21 – Handler Has Bad Module

Symptom: You see an error message stating “Handler ‘ExtensionlessUrlHandler-Integrated-4.0’ has a bad module ‘ManagedPipelineHandler’ in its module list.”

Solution: This typically indicates ASP.NET is not fully installed or registered with IIS. Run the following command in an elevated Command Prompt:

dism /online /enable-feature /featurename:IIS-ASPNET45 /all

The /all flag is crucial as it ensures all the prerequisite features are also installed. This command enables the ASP.NET components needed for IIS to properly handle MVC routing.

ERR_CONNECTION_REFUSED for HTTPS

Symptom: When attempting to access your site via HTTPS, you receive a connection refused error.

Solution:

  1. Verify you have an HTTPS binding in IIS:
    • In IIS Manager, select your website
    • Click “Bindings…” in the right panel
    • Add an HTTPS binding on port 443 if missing
  2. Ensure you have an SSL certificate:
    • Create a self-signed certificate for testing (Server Certificates → Create Self-Signed Certificate)
    • Import a valid certificate for production use
  3. Check Windows Firewall:
    • Ensure port 443 is open
    • Add an inbound rule if necessary