Remote debug your Azure App Service Web App


I created a sample ASP.NET application that you can download from here that contains a slow running request, a handled and an unhandled exception.

UPDATE: I wrote an article here about remote debugging in Visual Studio 2017 and ASP.NET Core here, titled "Remote debug your Azure App Service 2017 including ASP.NET Core", JIC you are interested.

To configure and remote debug your Microsoft Azure App Service Web App, you will need to perform the following:

  • Have a Web App deployed to the Azure platform
  • Attach the remote debugger to the Web App
  • Confirm the remote debugger is attached to the W3WP process
  • Set the break points
  • Execute the process which is rendering the exception, performing slow or in an unexpected manner
  • Debugging other technologies

Attach the remote debugger to the Web App

Within Visual Studio open the Cloud Explorer, expand the Web Apps, right-click the Web App you want to attach to and click Attach Debugger, as shown in Figure 1.  You can download Cloud Explorer here or install it from within Visual Studio by selecting Tools -> Extensions and Updates..., then search for Cloud Explorer.

image

Figure 1, attach a remote debugger to a Microsoft Azure App Service Web App

If you have not already enabled the remote debugging application setting, it will be done for you when you attach the debugger for the first time.  You can see the setting in the portal as illustrated in Figure 2.

image

Figure 2, Enable Remote Debugging for a Microsoft Azure App Service Web App

If your Web App uses an IP based SSL certificate you might get this exception:

System.Runtime.InteropServices.COMException (0x89710023): Unable to connect to the Microsoft Visual Studio Remote Debugger named ‘***’.  The Visual Studio 2015 Remote Debugger (MSVSMON.EXE) does not appear to be running on the remote computer. This may be because a firewall is preventing communication to the remote computer. Please see Help for assistance on configuring remote debugging.

Without going into much detail, what you have to do is get the IP address of your KUDU console, which I describe here and use that IP address for the *.azurewebsites.net hostname you are remote debugging by adding the IP HOSTNAME combination to the HOSTS file.

Confirm the remote debugger is attached to the W3WP process

After the Web App opens in the browser return to Visual Studio and click on Debug –> Attach to Process….  Then select the Web App to which you want to debug from the Qualifier drop down as shown in Figure 3.

image

Figure 3, attach the debugger to the desired Web App and process

Note that you can compare the PID of the W3WP process within the Available Processes list with the PID of the W3WP process seen in the process explorer in KUDU.  See Figure 4.

image

Figure 4, compare W3WP PID between Visual Studio and Kudu process explorer

Once confirmed move on and start debugging.

Set the break points

When you attach the debugger to your Web App it will open the Web App in you browser.  Leave the browser open but change the focus to Visual Studio and set your breakpoints just like you would when debugging locally.

  • Debug must be = true
  • Remote debugging requires symbols and there are no symbols for ASP.NET Web Sites, they exist only for ASP.NET Projects, so if you get this error when setting a break point, you will not be able to remote debug: “The breakpoint will not currently be hit.  No symbols have been loaded for this document.”  (SEO TAG: debug break points not hit when remote debugging)

As shown in Figure 5, set a break point to troubleshoot the code.

image

Figure 5, set break points to remote debug the Microsoft Azure App Service Web App

Navigate back to the browser where your Web App is displayed, the example code Web App looks like this:

image

Execute the process which is rendering the exception, performing slow or in an unexpected manner

Just like when debugging locally, as I have set a break point on the CallSlowExternalAPI() method in the buttonSlow_Click() method, when I click on the Slow button it breaks at that point and I can step through the code to see why and where the code is slow.  See Figure 6 which illustrates the break in the execution of the code.

image

Figure 6, debug break points is hit when remote debugging

That’s it.  Happy debugging.

Debugging other technologies

IISNODE using Node inspector here.

PHP using display_errors here.

Notes about debugging

Have a look at the section "Notes about debugging" here.

  • It is not recommended to run debug mode in production, because running in debug mode will prevent the web server from responding to other requests.
  • Avoid long stops at breakpoints.
  • Make sure debug=true, check out my other article about that here and here.
  • After 48 hours, the remote debug feature is automatically turned off.
Comments (7)

  1. Michael Quinlan says:

    Hi Benjamin,

    thanks for all the articles you’ve published! I’m having an issue connecting the remote debugger to my App Service. I click on on “attach debugger” and just after the screen displays “Finding process to attach to..” I get a prompt for windows credentials (see link to screenshot below). I’ve tried the credentials in the publish profile I used to successfully publish the app but to no avail. Can you point me in the right direction.

    Thanks in advance

    Mick

    1. @Michael, this is usually caused by a corporate global policy by the network admins. AFAIK it has to do with the ‘Send LM & NTLM – use NTLMv2 session security if negotiated’ policy. At the moment that authentication policy, in this context is not supported. You should try making the connection from a workstation which is not part of your corporate network just to confirm this. You might also ask your admins set your policy to ‘send NTLMv2 response only’ instead of the previously mentioned policy. Making changes like that is serious, please test diligently.

  2. If you get prompted for credentials, try entering in your publishing profile credentials.

  3. Conner says:

    “Without going into much detail, what you have to do is get the IP address of your KUDU console, which I describe here and use that IP address for the *.azurewebsites.net hostname you are remote debugging by adding the IP HOSTNAME combination to the HOSTS file.”

    How exactly to do this part?

    1. Luke says:

      Yes please could you go into more detail…

      I’m struggling to connect to azure web app with IP based SSL

    2. I am facing the same problem. Can anyone explain the detailed steps for this?
      Thanks!

  4. Flip-Oh says:

    I did the following (instructions are for a Windows PC):

    Get the IP address:
    1. Open a command prompt on your PC (Start > type “cmd” > Right-Click > Run As Administrator). You don’t actually need the Admin rights to get the IP, but I always run it like this, just to make sure I’m able to do everything I need.
    2. type “ping appname.scm.azurewebsites.net” (where appname is the name of your app on Azure) and press Enter. Notice the .scm in the address!
    3. In the command prompt, something like this will be shown: “Pinging appname.scm.azurewebsites.net [xx.xxx.xxx.xxx] with 32 bytes of data:”. The xx.xxx.xxx.xxx is the IP address you need.

    Now edit the hosts file:
    1. Open Windows Explorer and go to C:\Windows\System32\drivers\etc\. This is where you’ll find the hosts file.
    2. Copy the hosts file to your desktop. (it cannot be edited straight in the etc folder because of windows file protection)
    3. Open the hosts file with Notepad. It should look something like this:

    # Copyright (c) 1993-2009 Microsoft Corp.
    #
    # This is a sample HOSTS file used by Microsoft TCP/IP for Windows.
    #
    # This file contains the mappings of IP addresses to host names. Each
    # entry should be kept on an individual line. The IP address should
    # be placed in the first column followed by the corresponding host name.
    # The IP address and the host name should be separated by at least one
    # space.
    #
    # Additionally, comments (such as these) may be inserted on individual
    # lines or following the machine name denoted by a ‘#’ symbol.
    #
    # For example:
    #
    # 102.54.94.97 rhino.acme.com # source server
    # 38.25.63.10 x.acme.com # x client host

    # localhost name resolution is handled within DNS itself.
    # 127.0.0.1 localhost
    # ::1 localhost

    4. At the end of the file, on a new line, add the following line:

    xx.xxx.xxx.xxx appname.azurewebsites.net

    5. If you have custom domains set up for your app, you need to add these too (each on a new line):

    xx.xxx.xxx.xxx yourcustomsubdomain.yourcustomdomain.com
    xx.xxx.xxx.xxx yourcustomsubdomain2.yourcustomdomain2.com

    6. Save the changes to the hosts file. Then copy it back to the C:\Windows\System32\drivers\etc\ folder, replacing the existing one. Windows will tell you that admin permissions are needed to replace the file. Click Continue.
    7. Sometimes a reboot is needed for the hosts changes to take effect. If you don’t feel like rebooting you could also try “ipconfig /flushdns” in the command prompt and some people say you also need to restart the DNS Client service (which I both did, just to make sure).

    Your remote debugging should be working now.

Skip to main content