Remote Debug ASP.NET on a Remote IIS Computer

To debug an ASP.NET application that has been deployed to IIS, install and run the remote tools on the computer where you deployed your app, and then attach to your running app from Visual Studio.

This guide explains how to set up and configure a Visual Studio ASP.NET MVC 4.8 application, deploy it to IIS, and attach the remote debugger from Visual Studio.

Prerequisites

Visual Studio 2019 or a later version is required to follow the steps shown in this article.

These procedures have been tested on these server configurations:

• Windows Server 2022 and IIS 10
• Windows Server 2012 R2 and IIS 8 (For Windows Server 2008 R2, the server steps are different)

Network requirements

The remote debugger is supported on Windows Server starting with Windows Server 2008 Service Pack 2. For a complete list of requirements, see Requirements.

App already running in IIS?

This article includes steps on setting up a basic configuration of IIS on Windows server and deploying the app from Visual Studio. These steps are included to make sure that the server has required components installed, that the app can run correctly, and that you're ready to remote debug.

• If your app is running in IIS and you just want to download the remote debugger and start debugging, go to Download and Install the remote tools on Windows Server.

• If you want help with ensuring your app is set up, deployed, and running correctly in IIS so that you can debug, follow all the steps in this article.

Create the ASP.NET 4.8 application on the Visual Studio computer

1. Create a new MVC ASP.NET application.

   In Visual Studio, choose File > Start window to open the Start window, and then choose Create a new project. In the search box, type asp.net framework, and then choose ASP.NET Web Application (.NET Framework). In the dialog box that appears, name the project MyASPApp, choose ASP.NET Framework 4.8, and then choose Create.

   Select MVC and choose Create.

2. Open the HomeController.cs file in the Controllers folder and set a breakpoint in the return View; statement in the Privacy method.

   In older templates, open the Privacy.cshtml.cs file and set a breakpoint in the OnGet method.

Install and Configure IIS on Windows Server

These steps show only a basic configuration of IIS. For more in-depth information or to install to a Windows Desktop machine, see Publishing to IIS or IIS 8.0 Using ASP.NET 3.5 and ASP.NET 4.5.

For Windows Server operating systems, use the Add Roles and Features wizard via the Manage link or the Dashboard link in Server Manager. On the Server Roles step, check the box for Web Server (IIS).

(Windows Server 2022) In the dialog box that appears, choose Add Features to add the IIS Management Console.

On the Role services step, select the IIS role services you desire or accept the default role services provided. If you want to enable deployment using publish settings and Web Deploy, make sure that the following features are selected:

• IIS Management Scripts and Tools
• Management Service
• IIS Management Console

Proceed through the confirmation steps to install the web server role and services. A server/IIS restart is not required after installing the Web Server (IIS) role.

Update browser security settings on Windows Server

If you're using an older version of Windows Server, you might need to add some domains as trusted sites to enable you to download some of the web server components. Add the trusted sites by going to Internet Options > Security > Trusted Sites > Sites. Add the following domains.

• microsoft.com
• go.microsoft.com
• download.microsoft.com
• iis.net

When you download the software, you might get requests to grant permission to load various web site scripts and resources. Some of these resources aren't required, but to simplify the process, select Add when prompted.

Install ASP.NET 4.8 on Windows Server

If you want more detailed information to install ASP.NET on IIS, see IIS 8.0 Using ASP.NET 3.5 and ASP.NET 4.5.

1. In the left pane of Server Manager, select IIS. Right-click the server and select Add Roles and Features.

2. In the wizard, advance to the Features section and install ASP.NET 4.8.

   

   Note

   If you are using Windows Server 2008 R2, install ASP.NET 4 instead using this command:

   C:\Windows\Microsoft.NET\Framework64\v4.0.30319\aspnet_regiis.exe -ir

3. Restart the system (or execute net stop was /y followed by net start w3svc from a command prompt to pick up a change to the system PATH).

Choose a deployment option

If you need help with deploying the app to IIS, consider these options:

• Deploy by creating a publish settings file in IIS and importing the settings in Visual Studio. In some scenarios, this is a fast way to deploy your app. When you create the publish settings file, permissions are automatically set up in IIS.

• Deploy by publishing to a local folder and copying the output by a preferred method to a prepared app folder on IIS.

(Optional) Deploy using a publish settings file

You can use this option to create a publish settings file and import it into Visual Studio.

Install and configure Web Deploy on Windows Server

Web Deploy provides additional configuration features that enable the creation of the publish settings file from the UI.

1. If you did not already install IIS Management Scripts and Tools, install it now.

   Go to Select server roles > Web Server (IIS) > Management Tools, and then select the IIS Management Scripts and Tools role, click Next, and then install the role.

   

   The scripts and tools are required to enable the generation of the publish settings file.

   Make sure you also install the Management Service and IIS Management Console (they may be already installed).

2. On Windows Server, download Web Deploy 4.0.

3. Run the Web Deploy installation program, and make sure you select Complete installation instead of a typical installation.

   With a complete installation, you get the components you need to generate a publish settings file. (If you choose Custom instead, you can see the list of components, as shown in the following illustration.)

   

4. (Optional) Verify that Web Deploy is running correctly by opening Control Panel > System and Security > Administrative Tools > Services, and then make sure that:

   • Web Deployment Agent Service is running (the service name is different in older versions).

   • Web Management Service is running.

   If one of the agent services is not running, restart the Web Deployment Agent Service.

   If the Web Deployment Agent Service is not present at all, go to Control Panel > Programs > Uninstall a program, find Microsoft Web Deploy <version>. Choose to Change the installation and make sure that you choose Will be installed to the local hard drive for the Web Deploy components. Complete the change installation steps.

Create the publish settings file in IIS on Windows Server

1. Close and reopen the IIS Management Console to show updated configuration options in the UI.

2. In IIS, right-click the Default Web Site, choose Deploy > Configure Web Deploy Publishing.

   

   If you don't see the Deploy menu, see the preceding section to verify that Web Deploy is running.

3. In the Configure Web Deploy Publishing dialog box, examine the settings.

4. Click Setup.

   In the Results panel, the output shows that access rights are granted to the specified user, and that a file with a .publishsettings file extension has been generated in the location shown in the dialog box.

   <?xml version="1.0" encoding="utf-8"?>
   <publishData>
     <publishProfile
       publishUrl="https://myhostname:8172/msdeploy.axd"
       msdeploySite="Default Web Site"
       destinationAppUrl="http://myhostname:80/"
       profileName="Default Settings"
       publishMethod="MSDeploy"
       userName="myhostname\myusername" />
   </publishData>
   

   Depending on your Windows Server and IIS configuration, you see different values in the XML file. Here are a few details about the values that you see:

   • The msdeploy.axd file referenced in the publishUrl attribute is a dynamically generated HTTP handler file for Web Deploy. (For testing purposes, http://myhostname:8172 generally works as well.)

   • The publishUrl port is set to port 8172, which is the default for Web Deploy.

   • The destinationAppUrl port is set to port 80, which is the default for IIS.

   • If, in later steps, you are unable to connect to the remote host from Visual Studio using the host name, test the server's IP address in place of the host name.

     Note

     If you are publishing to IIS running on an Azure VM, you must open an inbound port for Web Deploy and IIS in the Network Security group. For detailed information, see Open ports to a virtual machine.

5. Copy this file to the computer where you are running Visual Studio.

Import the publish settings in Visual Studio and deploy

1. On the computer where you have the ASP.NET project open in Visual Studio, right-click the project in Solution Explorer, and choose Publish.

   If you have previously configured any publishing profiles, the Publish pane appears. Click New or Create new profile.

2. Select the option to import a profile.

   In the Publish dialog box, click Import Profile.

   

3. Navigate to the location of the publish settings file that you created in the previous section.

4. In the Import Publish Settings File dialog, navigate to and select the profile that you created in the previous section, and click Open.

   Click Finish to save the publishing profile, and then click Publish.

   Visual Studio begins the deployment process, and the Output window shows progress and results.

   If you get an any deployment errors, click More Actions > Edit to edit settings. Modify settings and click Validate to test new settings. If the host name is not found, try the IP address instead of the host name in both the Server and Destination URL fields.

   

After the app deploys successfully, it should start automatically. If the app doesn't start after deployment, start the app in IIS to verify that it runs correctly.

When you're ready, switch to a debug configuration.

(Optional) Deploy by publishing to a local folder

You can use this option to deploy your app if you want to copy the app to IIS using PowerShell, RoboCopy, or you want to manually copy the files.

Configure the ASP.NET Web site on the Windows Server computer

1. Open Windows Explorer and create a new folder, C:\Publish, where you later deploy the ASP.NET project.

2. If it's not already open, open the Internet Information Services (IIS) Manager. (In the left pane of Server Manager, select IIS. Right-click the server and select Internet Information Services (IIS) Manager.)

3. Under Connections in the left pane, go to Sites.

4. Select the Default Web Site, choose Basic Settings, and set the Physical path to C:\Publish.

5. Right-click the Default Web Site node and select Add Application.

6. Set the Alias field to MyASPApp, accept the default Application Pool (DefaultAppPool), and set the Physical path to C:\Publish.

7. Under Connections, select Application Pools. Open DefaultAppPool and set the Application pool field to ASP.NET v4.0 (ASP.NET 4.5 isn't an option for the Application pool).

8. With the site selected in the IIS Manager, choose Edit Permissions, and make sure that IUSR, IIS_IUSRS, or the user configured for the Application Pool is an authorized user with Read & Execute rights.

   If you don't see one of these users with access, go through steps to add IUSR as a user with Read & Execute rights.

Publish and Deploy the app by publishing to a local folder from Visual Studio

You can also publish and deploy the app using the file system or other tools.

For ASP.NET 4.8, make sure the web.config file lists the correct version of .NET.

• If you're targeting ASP.NET 4.8, make sure this version value is listed in the web.config file:

      <system.web>
        <compilation debug="true" targetFramework="4.8" />
        <httpRuntime targetFramework="4.8" />
        <httpModules>
          <add name="ApplicationInsightsWebTracking" type="Microsoft.ApplicationInsights.Web.ApplicationInsightsHttpModule, Microsoft.AI.Web" />
        </httpModules>
      </system.web>
      ```
  
  

• If you install ASP.NET 4 instead of 4.8, the version value should be specified as 4.0 in the web.config file.

Follow these steps to publish and deploy the app:

1. In the Solution Explorer, right-click the project node and select Publish (for Web Forms, Publish Web App).

   If you have previously configured any publishing profiles, the Publish pane appears. Click New profile.

2. In the Publish dialog box, select Folder, click Browse, and create a new folder, C:\Publish.

   

   Click Finish to save the publish profile.

   

   Click Finish to save the publish profile.

3. Switch to a debug configuration.

   Choose Edit to edit the profile, and then choose Settings. Choose a Debug configuration, and then choose Remove additional files at destination under the File Publish options.

   

   Note

   If you use a Release build, you disable debugging in the web.config file when you publish.

4. Click Publish.

   The application publishes a Debug configuration of the project to the local folder. Progress shows in the Output window.

5. Copy the ASP.NET project directory from the Visual Studio computer to the local directory configured for the ASP.NET app (in this example, C:\Publish) on the Windows Server computer. In this tutorial, we assume you are copying manually, but you can use other tools like PowerShell, Xcopy, or Robocopy.

   Caution

   If you need to make changes to the code or rebuild, you must republish and repeat this step. The executable you copied to the remote machine must exactly match your local source and symbols. If you do not do this you will receive a cannot find or open the PDB file warning in Visual Studio when you attempt to debug the process.

6. On the Windows Server, verify that you can run the app correctly by opening the app in your browser.

   If the app doesn't run correctly, there may be a mismatch between the version of ASP.NET installed on your server and your Visual Studio machine, or you may have an issue with your IIS or Web site configuration. Recheck earlier steps.

Download and Install the remote tools on Windows Server

Download the version of the remote tools that matches your version of Visual Studio.

On the remote device or server that you want to debug on, rather than the Visual Studio machine, download and install the correct version of the remote tools from the links in the following table.

• Download the most recent update of the remote tools for your version of Visual Studio. Earlier remote tools versions aren't compatible with later Visual Studio versions. (For example, if you're using Visual Studio 2019, download the latest update of the remote tools for Visual Studio 2019. In this scenario, don't download the remote tools for Visual Studio 2022.)
• Download the remote tools with the same architecture as the machine you're installing them on. For example, if you want to debug x86 applications on a remote computer running an x64 operating system, install the x64 remote tools. To debug x86, ARM, or x64 applications on an ARM64 operating system, install the ARM64 remote tools.

You can run the remote debugger by copying msvsmon.exe to the remote computer, rather than installing the remote tools. However, the Remote Debugger Configuration Wizard (rdbgwiz.exe) is available only when you install the remote tools. You may need to use the wizard for configuration if you want to run the remote debugger as a service. For more information, see (Optional) Configure the remote debugger as a service.

Set up the remote debugger on Windows Server

1. On the remote computer, find and start the Remote Debugger from the Start menu.

   If you don't have administrative permissions on the remote computer, right-click the Remote Debugger app and select Run as administrator. Otherwise, just start it normally.

   If you are planning to attach to a process which is running as an administrator, or is running under a different user account (such as IIS), right-click the Remote Debugger app and select Run as administrator. For more information, see Run the remote debugger as an administrator.

2. The first time you start the remote debugger (or before you have configured it), the Remote Debugging Configuration wizard appears.

   In most scenarios, choose Next until you get to the Configure the Windows Firewall page of the wizard.

   

   

   If the Windows Web Services API is not installed, which happens only on Windows Server 2008 R2, select the Install button.

3. Select at least one network type you want to use the remote tools on. If the computers are connected through a domain, you must choose the first item. If the computers are connected through a workgroup or homegroup, choose the second or third item as appropriate.

   Next, select Finish to start the remote debugger.

   Next, select Configure remote debugging to start the remote debugger.

4. When configuration is complete, the Remote Debugger window appears.

   

   

   The remote debugger is now waiting for a connection. Use the server name and port number shown to set the remote connection configuration in Visual Studio.

To stop the remote debugger, select File > Exit. You can restart it from the Start menu, or from the command line:

<Remote debugger installation directory>\msvsmon.exe

For information on running the remote debugger as a service, see Run the remote debugger as a service.

Attach to the ASP.NET application from the Visual Studio computer

4. Select Refresh.

   You should see some processes appear in the Available Processes window.

   If you don't see any processes, try using the IP address instead of the remote computer name (the port is required). You can use ipconfig in a command line to get the IPv4 address.

   If you want to use the Find button, you might need to open outbound UDP port 3702 on the server.

5. Check Show processes from all users.

6. Type the first letter of a process name to quickly find w3wp.exe for ASP.NET 4.5.

   If you have multiple processes showing w3wp.exe, check the User Name column. In some scenarios, the User Name column shows your app pool name, such as IIS APPPOOL\DefaultAppPool. If you see the App Pool, an easy way to identify the correct process is to create a new named App Pool for the app instance you want to debug, and then you can find it easily in the User Name column.

   

   

7. Select Attach.

8. Open the remote computer's website. In a browser, go to http://<remote computer name>.

   You should see the ASP.NET web page.

9. In the running ASP.NET application, select the link to the Privacy page.

   The breakpoint should be hit in Visual Studio.

   If you're unable to attach or hit the breakpoint, see Troubleshoot remote debugging.

Troubleshooting IIS deployment

• If you can't connect to the host using the host name, try the IP address instead.
• Make sure the required ports are open on the remote server.
• Verify that the version of ASP.NET used in your app is the same as the version you installed on the server. For your app, you can view and set the version in the Properties page. To set the app to a different version, that version must be installed.
• If the app tried to open, but you see a certificate warning, choose to trust the site. If you already closed the warning, you can edit the publishing profile, a *.pubxml file, in your project and add the following element (for test only): <AllowUntrustedCertificate>true</AllowUntrustedCertificate>
• After it's deployed, start the app in IIS to test that it deployed correctly.
• Check the Output window in Visual Studio for status information, and check your error messages.

Open required ports on Windows Server

In most setups, required ports are opened by the installation of ASP.NET and the remote debugger. However, you might need to verify that ports are open.

Required ports:

• 80: Required for IIS.

• 4024: Required for remote debugging from Visual Studio 2019 (see Remote Debugger Port Assignments for more information).

• UDP 3702: (Optional) Discovery port enables you to the Find button when attaching to the remote debugger in Visual Studio.

In addition, these ports should already be opened by the ASP.NET installation:

• 8172: (Optional) Required for Web Deploy to deploy the app from Visual Studio.

Open a port

1. To open a port on Windows Server, open the Start menu, search for Windows Defender Firewall or Windows Firewall with Advanced Security.

   For Windows Defender Firewall, choose Advanced settings.

2. Then choose Inbound Rules > New Rule > Port. Choose Next and under Specific local ports, enter the port number, select Next, then Allow the Connection, select Next, and add the name (IIS, Web Deploy, or msvsmon) for the Inbound Rule.

   If you want more details on configuring Windows Firewall, see Configure the Windows Firewall for Remote Debugging.

3. Create more rules for the other required ports.