This guide explains how to set up and configure a Visual Studio 2017 ASP.NET Core app, deploy it to IIS using Azure, and attach the remote debugger from Visual Studio.
The recommended way to remote debug on Azure depends on your scenario:
- To debug ASP.NET Core on Azure App Service, see Debug Azure apps using the Snapshot Debugger. This is the recommended method.
To debug ASP.NET Core on Azure App Service using more traditional debugging features, follow steps in this topic (see the section Remote debug on Azure App Service).
In this scenario, you must deploy your app from Visual Studio to Azure but you do not need to manually install or configure IIS or the remote debugger (these components are represented with dotted lines), as shown in the following illustration.
To debug IIS on an Azure VM, follow steps in this topic (see the section Remote Debug on an Azure VM). This allows you to use a customized configuration of IIS, but the setup and deployment steps are more complicated.
For an Azure VM, you must deploy your app from Visual Studio to Azure and you also need to manually install the IIS role and the remote debugger, as shown in the following illustration.
To debug ASP.NET Core on Azure Service Fabric, see Debug a remote Service Fabric application.
Be sure to delete the Azure resources that you create when you have completed the steps in this tutorial. That way you can avoid incurring unnecessary charges.
Debugging between two computers connected through a proxy is not supported. Debugging over a high latency or low bandwidth connection, such as dialup Internet, or over the Internet across countries is not recommended and may fail or be unacceptably slow. For a complete list of requirements, see Requirements.
Create the ASP.NET Core application on the Visual Studio 2017 computer
Create a new ASP.NET Core application. (Choose File > New > Project, then select Visual C# > Web > ASP.NET Core Web Application).
In the ASP.NET Core templates section, select Web Application.
Make sure that ASP.NET Core 2.0 is selected, that Enable Docker Support is not selected and that Authentication is set to No Authentication.
Name the project MyASPApp and click OK to create the new solution.
Open the About.cshtml.cs file and set a breakpoint in the
OnGetmethod (in older templates, open HomeController.cs instead and set the breakpoint in the
Remote Debug ASP.NET Core on an Azure App Service
From Visual Studio, you can quickly publish and debug your app to a fully provisioned instance of IIS. However, the configuration of IIS is preset and you cannot customize it. For more detailed instructions, see Deploy an ASP.NET Core web app to Azure using Visual Studio. (If you need the ability to customize IIS, try debugging on an Azure VM.)
To deploy the app and remote debug using Server Explorer
In Visual Studio, right-click the project node and choose Publish.
Choose Microsoft Azure App Service from the Publish dialog box, select Create New, and follow the prompts to publish.
For detailed instructions, see Deploy an ASP.NET Core web app to Azure using Visual Studio.
Open Server Explorer (View > Server Explorer), right-click on the App Service instance and choose Attach Debugger.
In the running ASP.NET application, click the link to the About page.
The breakpoint should be hit in Visual Studio.
That’s it! The rest of the steps in this topic apply to remote debugging on an Azure VM.
Remote Debug ASP.NET Core on an Azure VM
You can create an Azure VM for Windows Server and then install and configure IIS and the other required software components. This takes more time than deploying to an Azure App Service and requires that you follow the remaining steps in this tutorial.
First, follow all the steps described in Install and run IIS.
When you open port 80 in the Network security group, also open port 4022 for the Remote Debugger. That way, you won’t have to open it later.
Update browser security settings on Windows Server
Depending on your browser security settings, it may save you time to add the following trusted sites to your browser so you can easily download the software described in this tutorial. Access to these sites may be needed:
If you are using Internet Explorer, you can add the trusted sites by going to Internet Options > Security > Trusted Sites > Sites. These steps are different for other browsers. (If you need to download an older version of the remote debugger from my.visualstudio.com, some additional trusted sites are required to sign in.)
When you download the software, you may get requests to grant permission to load various web site scripts and resources. In most cases, these additional resources are not required to install the software.
Install ASP.NET Core on Windows Server
Install the .NET Core Windows Server Hosting bundle on the hosting system. The bundle will install the .NET Core Runtime, .NET Core Library, and the ASP.NET Core Module. For more in-depth instructions, see Publishing to IIS.
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).
(Optional) Install Web Deploy 3.6 on Windows Server
If you intend to deploy your applications with Web Deploy in Visual Studio, install the latest version of Web Deploy on the server.
Verify that Web Deploy is running correctly by opening Control Panel > System and Security > Administrative Tools > Services and make sure that Web Deployment Agent Service is running (the service name is different in older versions).
If the agent service is not running, start it. If it is not present at all, go to Control Panel > Programs > Uninstall a program, find Microsoft Web Deploy
. 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.
Configure ASP.NET Web site on the Windows Server computer
Open the Internet Information Services (IIS) Manager and go to Sites.
Right-click the Default Web Site node and select Add Application.
Set the Alias field to MyASPApp and the Application pool field to No Managed Code. Set the Physical path to C:Publish (where you will later deploy the ASP.NET project).
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.
(Optional) Publish and deploy the app using Web Deploy from Visual Studio
If you installed Web Deploy using the Web Platform Installer, you can deploy the app directly from Visual Studio.
Start Visual Studio with elevated privileges, and re-open the project.
This may be required to deploy your app using Web Deploy.
In the Solution Explorer, right-click the project node and select Publish.
For Select a publish target, select Microsoft Azure Virtual Machine and click Publish.
In the dialog box, select the Azure VM that you created previously.
Enter the correction configuration parameters for your Azure VM and IIS setup.
If a host name doesn’t resolve when you try to validate in the next steps in the Server text box, try the IP address. Make sure you use port 80 in the Server text box, and make sure that port 80 is open in the firewall.
Click Next, choose a Debug configuration, and choose Remove additional files at destination under the File Publish options.
Click Prev, and then choose Validate. If the connection setup validates, you can try to publish.
Click Publish to publish the app.
The Output tab will show you if publishing is successful, and your browser will open the app.
If you get an error mentioning Web Deploy, recheck the Web Deploy installation steps and make sure the correct ports are open are on the server.
If the app deploys successfully but doesn’t run correctly, recheck that both IIS and your Visual Studio project are using the same version of ASP.NET. If that is not the problem, there may be an issue with your IIS configuration or your Web site configuration. On the Windows Server, open the Web site from IIS for more specific error messages, and then recheck earlier steps.
(Optional) Publish and Deploy the app by publishing to a local folder from Visual Studio
If you’re not using Web Deploy, you must publish and deploy the app using the file system or other tools. You can start by creating a package using the file system, and then either deploy the package manually or use other tools like PowerShell, RoboCopy, or XCopy. In this section, we assume you are manually copying the package if you are not using Web Deploy.
In the Solution Explorer, right-click the project node and select Publish (for Web Forms, Publish Web App).
In the Publish dialog box, select Folder, click Browse, and create a new folder, C:Publish.
For a Web Forms app, choose Custom in the Publish dialog box, enter a profile name, and choose OK.
Visual Studio publishes the project to the folder. Progress shows in the Output window.
In the Publish dialog box, click the Settings link, and then select the Settings tab.
Set the configuration to Debug, select Delete all existing files prior to publish, and then click Save.
If you use a Release build, you disable debugging in the web.config file when you publish.
The application publishes a Debug configuration of the project to the local folder.
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.
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 filewarning in Visual Studio when you attempt to debug the process.
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
On the device or server machine that you want to debug (rather than the machine running Visual Studio), get the correct version of the remote tools.
Version Link Notes Visual Studio 2017 (latest version) Remote tools Always download the version matching your device operating system (x86 or x64). If enhanced security mode is enabled (Windows Server), you must add new trusted sites if prompted. Visual Studio 2017 (older) Remote tools Remote tools for earlier releases of Visual Studio 2017 are available from My.VisualStudio.com. If prompted, join the free Visual Studio Dev Essentials group, or sign in with your Visual Studio subscription ID. If enhanced security mode is enabled (Windows Server), you must add new trusted sites if prompted. Visual Studio 2015 Update 3 Remote tools If prompted, join the free Visual Studio Dev Essentials group, or sign in with your Visual Studio subscription ID. If enhanced security mode is enabled (Windows Server), you must add new trusted sites if prompted. Visual Studio 2015 (older) Remote tools If prompted, join the free Visual Studio Dev Essentials group, or sign in with your Visual Studio subscription ID. If enhanced security mode is enabled (Windows Server), you must add new trusted sites if prompted. Visual Studio 2013 Remote tools Download page in Visual Studio 2013 documentation Visual Studio 2012 Remote tools Download page in Visual Studio 2012 documentation
On the download page, choose the version of the tools that matches your operating system (x86, x64, or ARM) and download the remote tools.
We recommend you install the most recent version of the remote tools that matches your version of Visual Studio. Mismatched versions are not recommended. In addition, you must install the remote tools that have the same architecture as the operating system on which you want to install it. In other words, if you want to debug a 32-bit application on a remote computer running a 64-bit operating system, you must install the 64-bit version of the remote tools on the remote computer.
Surface 3 switched from ARM to x64 architecture. An ARM version of the remote tools is not available for Visual Studio 2017. For Visual Studio 2015, find the ARM version in the Visual Studio 2015 RTW download.
When you have finished downloading the executable, go to the next section and follow setup instructions.
If you try to copy the remote debugger (msvsmon.exe) to the remote computer and run it, be aware that the Remote Debugger Configuration Wizard (rdbgwiz.exe) is installed only when you download the tools. You may need to use the wizard for configuration later, especially if you want the remote debugger to run as a service. For more information, see (Optional) Configure the remote debugger as a service.
Set up the remote debugger on Windows Server
You must have administrative permissions on the remote computer.
Locate the Remote Debugger application. (Find msvsmon.exe in the location where it has been installed, or open the Start menu and search for Remote Debugger.)
If you are running the remote debugger on a remote server, you can right-click the Remote Debugger app and choose Run as administrator. If you are not running it on a remote server, just start it normally.
When you start the remote tools for the first time (or before you have configured it), the Remote Debugging Configuration dialog box appears.
If the Windows Service API is not installed (which happens only on Windows Server 2008 R2), choose the Install button.
Select the network types you want use the remote tools on. At least one network type must be selected. If the computers are connected through a domain, you must choose the first item. If the computers are connected through a workgroup or homegroup, you need to choose the second or third item as appropriate.
Choose Configure remote debugging to configure the firewall and start the tool.
When configuration is complete, the Remote Debugger window appears.
The remote debugger is now waiting for a connection. Make a note of the server name and port number that is displayed, because this must match the configuration you later use in Visual Studio.
When you are finished debugging and need to stop the remote debugger, click File > Exit on the window. You can restart it from the Start menu or from the command line:
<Visual Studio installation directory>Common7IDERemote Debugger<x86, x64, or Appx>msvsmon.exe.
If you need to add permissions for additional users, change the authentication mode, or port number for the remote debugger, see Configure the remote debugger.
Attach to the ASP.NET application from the Visual Studio computer
- On the Visual Studio computer, open the MyASPApp solution.
In Visual Studio, click Debug > Attach to Process (Ctrl + Alt + P).
In Visual Studio 2017, you can re-attach to the same process you previously attached to by using Debug > Reattach to Process… (Shift+Alt+P).
Set the Qualifier field to <remote computer name>:4022.
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
ipconfigin a command line to get the IPv4 address.
If you want to use the Find button, you may need to open UDP port 3702 on the server.
Check Show processes from all users.
Type the first letter of a process name to quickly find dotnet.exe (for ASP.NET Core).
Note: For an ASP.NET Core app, the previous process name was dnx.exe.
Open the remote computer’s website. In a browser, go to http://<remote computer name>.
You should see the ASP.NET web page.
In the running ASP.NET application, click the link to the About page.
The breakpoint should be hit in Visual Studio.
Troubleshooting: Open required ports on Windows Server
In most setups, required ports are opened by the installation of ASP.NET and the remote debugger. However, if you are troubleshooting deployment issues and the app is hosted behind a firewall, you may need to verify that the correct ports are open.
On an Azure VM, you must open ports through the Network security group.
- ۸۰ – Required for IIS
- ۴۰۲۲ – Required for remote debugging from Visual Studio 2017 (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:
- ۸۱۷۲ – (Optional) Required for Web Deploy to deploy the app from Visual Studio