Remote Debugging Windows Azure Cloud Services with Visual Studio 2012

This content presents a solution for remotely debugging Windows Azure cloud services using Visual Studio 2012. There are some details that have been left to a later update, like working through some of the limitations in the remote debugging tools for Visual Studio to target specific instances. I would appreciate feedback on the subject as comments in this post, and plan to provide some additional refinement to the code sample in a subsequent post.

Code Sample


Most of your Windows Azure development and debugging work can and will be done in the local emulator. Even though the emulator is close to the cloud environment, there are differences, and there are some situations that occasionally come up when remotely debugging your solution which is deployed and running in the cloud would be useful.

Although Intellitrace and tracing through Windows Azure Diagnostics are very helpful in resolving some of these issues, it is sometimes convenient to be able to simply attach to a deployed instance through remote debugging. Intellitrace also requires a redeployment since most people enable it when they need it, and quite often we have seen people waiting on multiple redeployments as they instrument the code with some additional tracing to narrow down and identify the issue.

Please share your reasons for wanting or needing remote debugging with cloud services as a comment on this post or provide some examples of how you have needed remote debugging.

Solution Overview

Visual Studio 2012 has a very nice remote debugging tool that utilizes WWSAPI to expose a remote debugger as a service endpoint. It simply requires an install, configuration, and available port which we will need to automate. In a nutshell, all we need to do is deploy the Visual Studio 2012 remote debugging tools with our instance, start it up, configure a port, we can attach the debugger, and that’s it. Easy enough.

In the sample project I have a simple little wrapper around the remote debugging tools to handle the install, configuration, and starting the remote debug service.  This can be found in the RemoteDebugManager.cs code file.

In RoleEntry OnStart event and configuration change events we check the “Debug.Enabled” cloud configuration setting to determine if we need to install and/or start the remote debug process or kill it. If the only setting changed for the role is the “Debug.Enabled” setting we can handle this and avoid recycling the instance.  So we can easily deploy our solution with remote debugging disabled and then enable it from the Windows Azure management console if we need it, without causing our instances to recycle.

When remote debugging is enabled in cloud configuration and the tools have not already been installed the debug manager will download and install the Visual Studio 2012 Remote Debugging Tools. The installation package is downloaded from our Windows Azure Storage account to a local resource. Once downloaded the installer is then executed with the “/install /norestart /quiet” arguments to perform a silent install of the tools.  After the installation completes, we then check to ensure the tools are installed, and then initialize the remote debugger with “/prepcomputer” argument which ensures WWSAPI is installed and makes some required firewall configuration changes for remote debugging service.

Once the service is installed now we simply need to start or stop is as needed. The current sample implementation just creates the remote debugger process with parameters to run it silently with some additional necessary configurations. When stopping the service we simply kill all processes for “msvsmon” on our instance.

How To: Windows Azure Cloud Services Remote Debugging

The following is a walk-through of running the sample code referenced.

Download the Sample Code

The code sample for this is available on MSDN Code Gallery.

Upload Remote Debugging Tools to Windows Azure Storage

Using your preferred Windows Azure Storage account tools you will need to upload the Visual Studio 2012 64-bit Remote Debugger tool to a Windows Azure Storage account (rtools_setup_x64.exe). This package can be found on Microsoft Download Center – By convention the solution looks for the installation in the ‘tools’ container of the configured storage account.  If you choose to upload to a different container you will need to make some changes to the code to match.

You could certainly choose to include the remote debugging tools in the solution package, but this increases the package size, and the approach we have taken allows us to simply pull the remote debugger in to the instance if and when we need it.

Configure the Solution

Assuming you already have a cloud service to deploy the sample solution to, there are really only a couple things you will need to configure; the host-name for the solution and the storage account connection string to the storage account you uploaded the tools to.  It is important that the hostname matches that used to attach to your instance.

Deploy the Solution

After you configure and build your solution you should be able to deploy it to your Windows Azure subscription and test it out. Once again you will need to ensure the service endpoint name used in the Visual Studio 2012 IDE to attach to the remote instance to be debugged matches that in the “Debug.HostName” cloud configuration setting. This is commonly your “” servicename, but could also be any other DNS name mapping used with your cloud service. In this example we are using our devops cloud service.  From the Windows Azure Management console you can turn remote debugging on and off after it has been deployed.

Attach to Your Process

You should be able to open Visual Studio 2012 on your development machine and attach to the cloud service instance with the instance containing the remote debugger installed and running. From Visual Studio 2012, select “Debug” from the main menu dropdown, and then “Attach to Process…”.  Select “Remote (no authentication)” from the “Transport” dropdown if you set Debug.IsAuthenticated to false, else set to “Default” and you can login using your remote desktop credentials ‘.\your-rdpuser’ in the dialog that comes up.  Enter the cloud service endpoint address in the “Qualifier” textbox. Hit enter… and eventually you should see a list of available processes to attach the debugger to. You may want to first open a browser and hit the endpoint to bring up our W3WP process to attach to when debugging web applications. If you missed this, you can open a browser to the site and just refresh the process list and you should then see your W3WP process available to attach to it.

Once you have attached to the process you are looking to debug; WaWorkerHost, W3WP, or WaIIsHost, etc… you can set a break point in your code and begin debugging.

Known Issues & Limitations

There are a number of limitations with the remote debugging implementation in this sample that could be worked around with some additional effort, but we have not had the time to address these items in this initial sample.

The current implementation only allows for a Single Role and Instance configured for remote debugging. I made some initial attempts to use instance endpoints in order to target specific role instances, but ran in to some limitations with the remote debugging tools and how it setup endpoints for the service. I do have some ideas as to how we can work around this, but will leave that for a later update.

Port 4016 is currently necessary for remote debugging. We cannot change the port number with the current implementation. There are some issues with the remote debugging tools in how it creates its endpoint when you specify a different port and host-name. Once again there are some workarounds to these limitations that we have considered and just have not found the time to address at the moment.

Elevated Runtime Execution of your role is currently required with this implementation of remote debugging. Once again, there are some ways to work around this one.

This current implementation only works with OS Family set to “2” ONLY. This is due to some strange exception when installing the remote debugger for which I have not bothered to work out the details for.

There is a firewall timeout Issue when connecting from Visual Studio 2012 that will throw and exception. If you attach, list the processes, then wait for 3 min before attempting to attach to one you will receive an exception.

With web roles you will need to send a web request to the instance in order to bring up the W3C Process before being able to attach and debug.

Leave a Reply