Debug an Azure Cloud Services (extended support) service in Visual Studio

To enable remote debugging for a cloud service (extended support)

1. Add an Endpoint to the ServiceDefinition.csdef for the default msvsmon port. For Visual Studio 2019, it's 4024.

   <Endpoints>
      <InputEndpoint name="RemoteDebug" protocol="tcp" port="4024" localPort="4024" />
   </Endpoints>
   

   Note

   Other versions of Visual Studio have different ports Remote Debugger Port Assignments.

2. Open the shortcut menu for the Azure project, and then select Publish.

3. Select the Staging environment and the Debug configuration.

   This is only a guideline. You can opt to run your test environments in a Production environment. However, you may adversely affect users if you enable remote debugging on the Production environment. You can choose the Release configuration, but the Debug configuration makes debugging easier.

   

4. Follow the usual steps described at Cloud Services (extended support), but select the Enable Remote Desktop for all roles checkbox.

   You'll be asked to create a username and password for the remote desktop user, which you'll need later to sign in to that virtual machine.

5. Advance to the next screen, review your settings, and when ready, click Publish and wait for the deployment to finish.

6. Sign in to Azure portal and navigate to the Cloud Service (extended support) that you want to debug.

7. Choose Roles and Instances in the left hand pane, then choose the role that you are interested in debugging remotely.

8. Click Connect in the Role Instance popout on the right and choose the Connect button to download a remote desktop file that will let you sign in to the virtual machine. Sign in using the credentials you created when you enabled remote desktop in a previous step.

   

9. On the Remote Azure virtual machine, install the Visual Studio 2019 Remote tools as described at Remote debugging.

10. From the desktop on the virtual machine, execute the command D:\Program Files (x86)\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\Remote Debugger\x64\msvsmon.exe. Be sure to run as Administrator.

11. Accept prompts to allow access through the firewall. You should see a message indicating that msvsmon.exe has started listening for connections.

12. In the Azure portal, open the resource group and get the public IP Address for the Cloud Service (extended support).

    

To attach the debugger to a cloud service (extended support) in Azure

1. Choose Debug > Attach to Process (or press Ctrl+Alt+P).

2. Keep connection type at Default.

3. Enter the connection target, using your IP address and port: {ipaddress}:4024.

4. Set Attach To to Automatic.

5. Sign in using the same credentials as remote desktop user.

6. Select Show process for all users. If you're debugging a worker role, attach to WaWorkerHost.exe; if you're debugging a web role, attach to the w3wp.exe process; for a Web API role, it's WaIISHost.exe.

7. Set breakpoints (navigate to the line, and press F9), access the site's public URL, and reproduce the scenario to debug.

To enable remote debugging for a cloud service (extended support)

1. Add an Endpoint to the ServiceDefinition.csdef for the default msvsmon port. For Visual Studio 2022, that's 4026; for Visual Studio 2019, it's 4024.

   <Endpoints>
      <InputEndpoint name="RemoteDebug" protocol="tcp" port="4026" localPort="4026" />
   </Endpoints>
   

   Note

   Other versions of Visual Studio have different ports Remote Debugger Port Assignments.

2. If you are targeting .NET 4.8, be sure to open the ServiceConfiguration.Cloud.cscfg file and check the value of the osFamily attribute on the ServiceConfiguration element when publishing Cloud Services (extended support). For a .NET 4.8 project, use osFamily="7".

3. Open the shortcut menu for the Azure project, and then select Publish.

4. Select the Staging environment and the Debug configuration.

   This is only a guideline. You can opt to run your test environments in a Production environment. However, you may adversely affect users if you enable remote debugging on the Production environment. You can choose the Release configuration, but the Debug configuration makes debugging easier.

   

5. Follow the usual steps described at Cloud Services (extended support), but select the Enable Remote Desktop for all roles checkbox.

   You'll be asked to create a username and password for the remote desktop user, which you'll need later to sign in to that virtual machine.

6. Advance to the next screen, review your settings, and when ready, click Publish and wait for the deployment to finish.

7. Sign in to Azure portal and navigate to the Cloud Service (extended support) that you want to debug.

8. Choose Roles and Instances in the left hand pane, then choose the role that you are interested in debugging remotely.

9. Click Connect in the Role Instance popout on the right and choose the Connect button to download a remote desktop file that will let you sign in to the virtual machine. Sign in using the credentials you created when you enabled remote desktop in a previous step.

   

10. On the Remote Azure virtual machine, install the Visual Studio 2022 Remote tools as described at Remote debugging.

11. From the desktop on the virtual machine, execute the command msvsmon.exe in the Visual Studio installation folder under Common7\IDE\Remote Debugger\x64. Be sure to run as Administrator.

12. Accept prompts to allow access through the firewall. You should see a message indicating that msvsmon.exe has started listening for connections.

    

13. In the Azure portal, open the resource group and get the public IP Address for the Cloud Service (extended support).

    

To attach the debugger to a cloud service (extended support) in Azure

1. Choose Debug > Attach to Process (or press Ctrl+Alt+P).

2. Keep connection type at Default.

3. Enter the connection target, using your IP address and port: {ipaddress}:4026.

4. Set Attach To to Automatic.

5. Sign in using the same credentials as remote desktop user.

6. Select Show process for all users. If you're debugging a worker role, attach to WaWorkerHost.exe; if you're debugging a web role, attach to the w3wp.exe process; for a Web API role, it's WaIISHost.exe.

7. Set breakpoints (navigate to the line, and press F9), access the site's public URL, and reproduce the scenario to debug.

Limitations of remote debugging in Azure

Remote debugging has the following limitations:

• With remote debugging enabled, you can't publish a cloud service in which any role has more than 25 instances.

• The debugger uses ports 30400 to 30424, 31400 to 31424 and 32400 to 32424. If you try to use any of these ports, you won't be able to publish your service, and one of the following error messages will appear in the activity log for Azure:

  • Error validating the .cscfg file against the .csdef file. The reserved port range 'range' for endpoint Microsoft.WindowsAzure.PlugIns.RemoteDebugger.Connector of role 'role' overlaps with an already defined port or range.
  • Allocation failed. Retry later, try reducing the VM size or number of role instances, or try deploying to a different region.

Debugging Azure App Service

You can debug programs that run in Azure App Service by using the Attach to Process dialog in Visual Studio.

To debug a Windows Azure App Service

1. Under Debug, select Attach to Process.

2. Change Connection type to Microsoft Azure App Services, then select Find...

3. In the dialog box that opens, select the Subscription name.

   

   Note

   You need to be signed in to a Microsoft Account with access to the subscription that contains your Azure App Service.

4. Filter the view by either Resource Group or Resource Type, or search by name.

5. Next, select the App Service you want to debug then select Ok.

   This enables remote debugging on your App Service and shows you a list of available processes to attach to.

   

6. Select the process you want to attach to and then choose Attach to start debugging.

Debugging Azure Virtual Machines

You can debug programs that run on Azure Virtual Machines by using Server Explorer in Visual Studio. When you enable remote debugging on an Azure virtual machine, Azure installs the remote debugging extension on the virtual machine. Then, you can attach to processes on the virtual machine and debug as you normally would.

To debug an Azure virtual machine

1. In Server Explorer, expand the Virtual Machines node and select the node of the virtual machine that you want to debug.

2. Open the context menu and select Enable Debugging. When asked if you're sure if you want to enable debugging on the virtual machine, select Yes.

   Azure installs the remote debugging extension on the virtual machine to enable debugging.

   

   

3. After the remote debugging extension finishes installing, open the virtual machine's context menu and select Attach Debugger...

   Azure gets a list of the processes on the virtual machine and shows them in the Attach to Process dialog box.

   

4. In the Attach to Process dialog box, select Select to limit the results list to show only the types of code you want to debug. You can debug 32-bit or 64-bit managed code, native code, or both.

   

5. Choose the processes you want to debug on the virtual machine and then select Attach. For example, you might choose the w3wp.exe process if you wanted to debug a web app on the virtual machine. See Debug One or More Processes in Visual Studio and Azure Role Architecture for more information.

Create a web project and a virtual machine for debugging

Before publishing your Azure project, you might find it useful to test it in a contained environment that supports debugging and testing scenarios, and where you can install testing and monitoring programs. One way to run such tests is to remotely debug your app on a virtual machine.

Visual Studio ASP.NET projects offer an option to create a handy virtual machine that you can use for app testing. The virtual machine includes commonly needed endpoints such as PowerShell, Remote Desktop, and WebDeploy.

To create a web project and a virtual machine for debugging

1. In Visual Studio, create a new ASP.NET Web Application.

2. In the New ASP.NET Project dialog, in the Azure section, select Virtual Machine in the dropdown list box. Leave the Create remote resources checkbox selected. Select OK to proceed.

   The Create virtual machine on Azure dialog box appears.

   

   Note

   You'll be asked to sign in to your Azure account if you're not already signed in.

3. Choose the various settings for the virtual machine and then select OK. See Virtual Machines for more information.

   The name you enter for DNS name will be the name of the virtual machine.

   

   Azure creates the virtual machine and then provisions and configures the endpoints, such as Remote Desktop and Web Deploy.

4. After the virtual machine is fully configured, select the virtual machine's node in Server Explorer.

5. Open the context menu and select Enable Debugging. When asked if you're sure if you want to enable debugging on the virtual machine, select Yes.

   Azure installs the remote debugging extension to the virtual machine to enable debugging.

   

   

6. Publish your project as outlined in How to: Deploy a Web Project Using One-Click Publish in Visual Studio. Because you want to debug on the virtual machine, on the Settings page of the Publish Web wizard, select Debug as the configuration. This makes sure that code symbols are available while debugging.

   

7. In the File Publish Options, select Remove additional files at destination if the project was already deployed at an earlier time.

8. After the project publishes, on the virtual machine's context menu in Server Explorer, select Attach Debugger...

   Azure gets a list of the processes on the virtual machine and shows them in the Attach to Process dialog box.

   

9. In the Attach to Process dialog box, select Select to limit the results list to show only the types of code you want to debug. You can debug 32-bit or 64-bit managed code, native code, or both.

   

10. Choose the processes you want to debug on the virtual machine and then select Attach. For example, you might choose the w3wp.exe process if you wanted to debug a web app on the virtual machine. See Debug One or More Processes in Visual Studio for more information.