Troubleshooting Azure Web Sites in Visual Studio
During development and testing of a web application, you can troubleshoot by running in debug mode or by using IntelliTrace. You can run in debug mode locally in IIS Express or remotely in an Azure Web Site. But for errors that occur only in production, the best way to debug might be by reviewing logs that application code or the web server creates. This tutorial shows how to use Visual Studio tools that help debug an application while it runs in an Azure Web Site, by running in debug mode remotely or by viewing application and web server logs.
- Which Azure site management functions are available in Visual Studio.
- How to use Visual Studio remote view to make quick changes in a remote web site.
- How to run debug mode remotely while a project is running in an Azure Web Site.
- How to create application trace logs and view them while the application is creating them.
- How to view web server logs, including detailed error messages and failed request tracing.
- How to send diagnostic logs to an Azure Storage account and view them there.
- Site configuration and management
- Remote view
- Remote debugging
- Diagnostic logs overview
- Create and view application trace logs
- View web server logs
- View detailed error message logs
- Download file system logs
- View storage logs
- View failed request logs
- Next steps
This tutorial works with the development environment, web project, and Azure Web Site that you set up in Getting started with Azure and ASP.NET. The code samples shown in this tutorial are for a C# MVC web application, but the troubleshooting procedures are the same for Visual Basic and Web Forms applications.
Remote debugging requires Visual Studio 2013 or Visual Studio 2012 with Update 4. The other features shown in the tutorial also work in Visual Studio 2013 Express for Web, and Visual Studio 2012 Express for Web.
The streaming logs feature only works for applications that target .NET Framework 4 or later.
Site configuration and management
Visual Studio provides access to a subset of the site management functions and configuration settings available in the management portal. In this section you'll see what's available.
If you aren't already signed in to Azure in Visual Studio, click the Connect to Azure button in Server Explorer.
An alternative is to install a management certificate that enables access to your account. The management certificate gives Server Explorer access to additional Azure services (SQL Database and Mobile Services). If you choose to install a certificate, right-click the Azure node in Server Explorer, and then click Manage Subscriptions in the context menu. In the Manage Azure Subscriptions dialog box, click the Certificates tab, and then click Import. Follow the directions to download and then import a subscription file (also called a .publishsettings file) for your Azure account.
If you download a subscription file, save it to a folder outside your source code directories (for example, in the Downloads folder), and then delete it once the import has completed. A malicious user who gains access to the subscription file can edit, create, and delete your Azure services.
For more information about connecting to Azure resources from Visual Studio, see Manage Accounts, Subscriptions, and Administrative Roles.
In Server Explorer, expand Azure, and then expand Web Sites.
Right-click the node for the web site that you created in Getting started with Azure and ASP.NET, and then click View Settings.
The Azure Web Site tab appears, and you can see there the site management and configuration tasks that are available in Visual Studio.
In this tutorial you'll be using the logging and tracing drop-downs. You'll also use remote debugging but you'll use a different method to enable it.
For information about the App Settings and Connection Strings boxes in this window, see Azure Web Sites: How Application Strings and Connection Strings Work.
If you want to perform a site management task that can't be done this window, you can click Full Web Site Settings to open a browser window to the management portal. For more information, see How to Configure Web Sites.
You typically deploy a site with the
customErrors flag in the Web.config file set to
RemoteOnly, which means you don't get a helpful error message when something goes wrong. For many errors all you get is a page like one of the following ones.
Server Error in '/' Application:
An error occurred:
The website cannot display the page
Frequently the easiest way to find the cause of the error is to enable detailed error messages, which the first of the preceding screenshots explains how to do. That requires a change in the deployed Web.config file. You could edit the Web.config file in the project and redeploy the project, or create a Web.config transform and deploy a debug build, but there's a quicker way: in Solution Explorer you can directly view and edit files on the remote site by using the remote view feature.
In Server Explorer, expand Azure, expand Web Sites, and expand the node for the web site you're deploying to.
You see nodes that give you access to the web site's content files and log files.
Expand the Files node, and double-click the Web.config file.
Visual Studio opens the Web.config file from the remote site and shows [Remote] next to the file name in the title bar.
Add the following line to the
Refresh the browser that is showing the unhelpful error message, and now you get a detailed error message, such as the following example:
(The error shown was created by adding the line shown in red to Views\Home\Index.cshtml.)
Editing the Web.config file is only one example of scenarios in which the ability to read and edit files on your Azure web site make troubleshooting easier.
If the detailed error message doesn't provide enough information, and you can't re-create the error locally, another way to troubleshoot is to run in debug mode remotely. You can set breakpoints, manipulate memory directly, step through code, and even change the code path.
Remote debugging does not work in Express editions of Visual Studio.
This section shows how to debug remotely using the project you create in Getting started with Azure and ASP.NET.
Open the web project that you created in Getting started with Azure and ASP.NET.
About() method and insert the following code in its place.
public ActionResult About()
string currentTime = DateTime.Now.ToLongTimeString();
ViewBag.Message = "The current time is " + currentTime;
Set a breakpoint on the
In Solution Explorer, right-click the project, and click Publish.
In the Profile drop-down list, select the same profile that you used in Getting started with Azure and ASP.NET.
Click the Settings tab, and change Configuration to Debug, and then click Publish.
After deployment finishes and your browser opens to the Azure URL of your site, close the browser.
For Visual Studio 2013: In Server Explorer expand Azure, expand Web Sites, right-click your web site, and click Attach Debugger.
The browser automatically opens to your home page running in Azure. You might have to wait 20 seconds or so while Azure sets up the server for debugging. This delay only happens the first time you run in debug mode on a web site. Subsequent times within the next 48 hours when you start debugging again there won't be a delay.
For Visual Studio 2012 with Update 4:
- In the Azure Management Portal, go to the Configure tab for your web site, and then scroll down to the Site Diagnostics section.
- Set Remote Debugging to On, and set Remote Debugging Visual Studio Version to 2012.
* In the Visual Studio Debug menu, click Attach to Process. * In the Qualifier box, enter the URL for your web site, without the
http:// prefix. * Select Show processes from all users. * When you're prompted for credentials, enter the user name and password that has permissions to publish the web site. To get these credentials, go to the Dashboard tab for your web site in the management portal and click Download the publish profile. Open the file in a text editor, and you'll find the user name and password after the first occurrences of userName= and userPWD=. * When the processes appear in the Available Processes table, select w3wp.exe, and then click Attach. * Open a browser to your site URL.
You might have to wait 20 seconds or so while Azure sets up the server for debugging. This delay only happens the first time you run in debug mode on a web site. Subsequent times within the next 48 hours when you start debugging again there won't be a delay.
Click About in the menu.
Visual Studio stops on the breakpoint, and the code is running in Azure, not on your local computer.
Hover over the
currentTime variable to see the time value.
The time you see is the Azure server time, which may be in a different time zone than your local computer.
Enter a new value for the
currentTime variable, such as "Now running in Azure".
Press F5 to continue running.
The About page running in Azure displays the new value that you entered into the currentTime variable.
Notes about remote debugging
Running in debug mode in production is not recommended. If your production site is not scaled out to multiple server instances, debugging will tie up traffic to your only web server instance. If you do have multiple web server instances, when you attach to the debugger you'll get a random instance, and you have no way to ensure that your browser requests will go to that instance. Also, you typically don't deploy a debug build to production, and compiler optimizations for release builds might make it impossible to show what is happening line by line in your source code. For troubleshooting production problems, your best resource is application tracing and web server logs.
Avoid long stops at breakpoints when remote debugging. Azure treats a process that is stopped for longer than a few minutes as an unresponsive process, and shuts it down.
While you're debugging, the server is sending data to Visual Studio, which could affect bandwidth charges. For information about bandwidth rates, see Azure Pricing.
Make sure that the
debug attribute of the
compilation element in the Web.config file is set to true. It is set to true by default when you publish a debug build configuration.
<compilation debug="true" targetFramework="4.5" />
<httpRuntime targetFramework="4.5" />
If you find that the debugger won't step into code that you want to debug, you might have to change the Just My Code setting. For more information, see Restrict stepping to Just My Code.
A timer starts on the server when you enable the remote debugging feature, and after 48 hours the feature is automatically turned off. This 48 hour limit is done for security and performance reasons. You can easily turn the feature back on as many times as you like. We recommend leaving it disabled when you are not actively debugging.
You can manually attach the debugger to any process. Not only can you debug the website process (w3wp.exe), but you can also debug other processes such as WebJobs. For more information about how to use debug mode in Visual Studio, see Debugging in Visual Studio.
Diagnostic logs overview
An ASP.NET application that runs in an Azure Web Site can create the following kinds of logs:
- Application tracing logs
The application creates these logs by calling methods of the System.Diagnostics.Trace class.
- Web server logs
The web server creates a log entry for every HTTP request to the site.
- Detailed error message logs
The web server creates an HTML page with some additional information for failed HTTP requests (those that result in status code 400 or greater).
- Failed request tracing logs
The web server creates an XML file with detailed tracing information for failed HTTP requests. The web server also provides an XSL file to format the XML in a browser.
Logging affects site performance, so Azure gives you the ability to enable or disable each type of log as needed. For application logs, you can specify that only logs above a certain severity level should be written. When you create a new web site, by default all logging is disabled.
Logs are written to files in a LogFiles folder in the file system of your web site. Web server logs and application logs can also be written to an Azure Storage account. You can retain a greater volume of logs in a storage account than is possible in the file system. You're limited to a maximum of 100 megabytes of logs when you use the file system. (File system logs are only for short-term retention. Azure deletes old log files to make room for new ones after the limit is reached.)
Create and view application trace logs
In this section you'll do the following tasks:
- Add tracing statements to the web project that you created in the earlier tutorial.
- View the logs when you run the project locally.
- View the logs as they are generated by the application running in Azure.
Add tracing statements to the application
Open Controllers\HomeController.cs, and replace the file contents with the following code in order to add
Trace statements and a
using statement for
public class HomeController : Controller
public ActionResult Index()
Trace.WriteLine("Entering Index method");
ViewBag.Message = "Modify this template to jump-start your ASP.NET MVC application.";
Trace.TraceInformation("Displaying the Index page at " + DateTime.Now.ToLongTimeString());
Trace.WriteLine("Leaving Index method");
public ActionResult About()
Trace.WriteLine("Entering About method");
ViewBag.Message = "Your app description page.";
Trace.TraceWarning("Transient error on the About page at " + DateTime.Now.ToShortTimeString());
Trace.WriteLine("Leaving About method");
public ActionResult Contact()
Trace.WriteLine("Entering Contact method");
ViewBag.Message = "Your contact page.";
Trace.TraceError("Fatal error on the Contact page at " + DateTime.Now.ToLongTimeString());
Trace.WriteLine("Leaving Contact method");
View the tracing output locally
Press F5 to run the application in debug mode.
The default trace listener writes all trace output to the Output window, along with other Debug output. The following illustration shows the output from the trace statements that you added to the
The following steps show how to view trace output in a web page, without compiling in debug mode.
Open the application Web.config file (the one located in the project folder) and add a
<system.diagnostics> element at the end of the file just before the closing
WebPageTraceListener lets you view trace output by browsing to
Add a trace element under
<system.web> in the Web.config file, such as the following example:
<trace enabled="true" writeToDiagnosticsTrace="true" mostRecent="true" pageOutput="false" />
Press CTRL+F5 to run the application.
In the address bar of the browser window, add trace.axd to the URL, and then press Enter (the URL will be similar to http://localhost:53370/trace.axd).
On the Application Trace page, click View Details.
The Request Details page appears, and in the Trace Information section you see the output from the trace statements that you added to the
trace.axd is only available locally. If you wanted to make it available from a remote site, you could add
localOnly="false" to the
trace element in the Web.config file, as shown in the following example:
<trace enabled="true" writeToDiagnosticsTrace="true" localOnly="false" mostRecent="true" pageOutput="false" />
trace.axd in a production site is generally not recommended for security reasons, and in the following sections you'll see an easier way to read tracing logs in an Azure Web Site.
View the tracing output in Azure
In Solution Explorer, right-click the web project and click Publish.
In the Publish Web dialog box, click Publish.
After Visual Studio publishes your update, it opens a browser window to your home page (assuming you didn't clear Destination URL on the Connection tab).
In Server Explorer, right-click your web site and select View Streaming Logs in Output Window.
The Output window shows that you are connected to the log-streaming service, and adds a notification line each minute that goes by without a log to display.
In the browser window that shows your application home page, click Contact.
Within a few seconds the output from the error-level trace you added to the
Contact method appears in the Output window.
Visual Studio is only showing error-level traces because that is the default setting when you enable the log monitoring service. When you create a new Azure Web Site, all logging is disabled by default, as you saw when you opened the site settings page earlier:
However, when you selected View Streaming Logs in Output Window, Visual Studio automatically changed Application Logging(File System) to Error, which means error-level logs get reported. In order to see all of your tracing logs, you can change this setting to Verbose. When you select a severity level lower than error, all logs for higher severity levels are also reported. So when you select verbose, you also see information, warning, and error logs.
In Server Explorer, right-click the web site, and then click View Settings as you did earlier.
Change Application Logging (File System) to Verbose, and then click Save.
In the browser window that is now showing your Contact page, click Home, then click About, and then click Contact.
Within a few seconds, the Output window shows all of your tracing output.
In this section you enabled and disabled logging by using Azure Web Site settings. You can also enable and disable trace listeners by modifying the Web.config file. However, modifying the Web.config file causes the app domain to recycle, while enabling logging via the web site doesn't do that. If the problem takes a long time to reproduce, or is intermittent, recycling the app domain might "fix" it and force you to wait until it happens again. Enabling diagnostics in Azure doesn't do this, so you can start capturing error information immediately.
Output window features
The Azure Logs tab of the Output Window has several buttons and a text box:
These perform the following functions:
- Clear the Output window.
- Enable or disable word wrap.
- Start or stop monitoring logs.
- Specify which logs to monitor.
- Download logs.
- Filter logs based on a search string or a regular expression.
- Close the Output window.
If you enter a search string or regular expression, Visual Studio filters logging information at the client. That means you can enter the criteria after the logs are displayed in the Output window and you can change filtering criteria without having to regenerate the logs.
View web server logs
Web server logs record all HTTP activity on the site. In order to see them in the Output window you have to enable them on the site and tell Visual Studio that you want to monitor them.
In the Azure Web Site Configuration tab that you opened from Server Explorer, change Web Server Logging to On, and then click Save.
In the Output Window, click the Specify which Azure logs to monitor button.
In the Azure Logging Options dialog box, select Web server logs, and then click OK.
In the browser window that shows the web site, click Home, then click About, and then click Contact.
The application logs generally appear first, followed by the web server logs. You might have to wait a while for the logs to appear.
By default, when you first enable web server logs by using Visual Studio, Azure writes the logs to the file system. As an alternative, you can use the management portal to specify that web server logs should be written to a blob container in a storage account. For more information, see the site diagnostics section in How to Configure Web Sites.
If you use the management portal to enable web server logging to an Azure storage account, and then disable logging in Visual Studio, when you re-enable logging in Visual Studio your storage account settings are restored.
View detailed error message logs
Detailed error logs provide some additional information about HTTP requests that result in error response codes (400 or above). In order to see them in the Output window, you have to enable them on the site and tell Visual Studio that you want to monitor them.
In the Azure Web Site Configuration tab that you opened from Server Explorer, change Detailed Error Messages to On, and then click Save.
In the Output Window, click the Specify which Azure logs to monitor button.
In the Azure Logging Options dialog box, click All logs, and then click OK.
In the address bar of the browser window, add an extra character to the URL to cause a 404 error (for example,
http://localhost:53370/Home/Contactx), and press Enter.
After several seconds the detailed error log appears in the Visual Studio Output window.
Control+click the link to see the log output formatted in a browser:
Download file system logs
Any logs that you can monitor in the Output window can also be downloaded as a .zip file.
In the Output window, click Download Streaming Logs.
File Explorer opens to your Downloads folder with the downloaded file selected.
Extract the .zip file, and you see the following folder structure:
- Application tracing logs are in .txt files in the LogFiles\Application folder.
- Web server logs are in .log files in the LogFiles\http\RawLogs folder. You can use a tool such as Log Parser to view and manipulate these files.
- Detailed error message logs are in .html files in the LogFiles\DetailedErrors folder.
(The deployments folder is for files created by source control publishing; it doesn't have anything related to Visual Studio publishing. The Git folder is for traces related to source control publishing and the log file streaming service.)
View storage logs
Application tracing logs can also be sent to an Azure storage account, and you can view them in Visual Studio. To do that you'll create a storage account, enable storage logs in the management portal, and view them in the Logs tab of the Azure Web Site window.
You can send logs to any or all of three destinations:
- The file system.
- Storage account tables.
- Storage account blobs.
You can specify a different severity level for each destination.
Tables make it easy to view details of logs online, and they support streaming; you can query logs in tables and see new logs as they are being created. Blobs make it easy to download logs in files and to analyze them using HDInsight, because HDInsight knows how to work with blob storage. For more information, see Hadoop and MapReduce in Data Storage Options (Building Real-World Cloud Apps with Azure).
You currently have file system logs set to verbose level; the following steps walk you through setting up information level logs to go to storage account tables. Information level means all logs created by calling
Trace.TraceError will be displayed, but not logs created by calling
Storage accounts offer more storage and longer-lasting retention for logs compared to the file system. Another advantage of sending application tracing logs to storage is that you get some additional information with each log that you don't get from file system logs.
In Server Explorer, right-click the web site, and then click Open in Management Portal.
In the management portal, click the Storage tab, and then click Create a Storage Account.
Enter a unique URL to use for the storage account, and then click Create Storage Account.
In the Visual Studio Azure Web Site window, click the Logs tab, and then click Configure Logging.
This opens the Configure tab in the management portal for your web site. Another way to get here is to click the Web Sites tab, click your web site, and then click the Configure tab.
In the management portal Configure tab, scroll down to the application diagnostics section, and then change Application Logging (Table Storage) to On.
Change Logging Level to Information.
Click Manage Table Storage.
In the Manage table storage for application diagnostics box, you can choose your storage account if you have more than one. You can create a new table or use an existing one.
In the Manage table storage for application diagnostics box click the check mark to close the box.
In the management portal Configure tab, click Save.
In the browser window that displays the application web site, click Home, then click About, and then click Contact.
The logging information produced by browsing these web pages will be written to the storage account.
In the Logs tab of the Azure Web Site window in Visual Studio, click Refresh under Diagnostic Summary.
The Diagnostic Summary section shows logs for the last 15 minutes by default. You can change the period to see more logs.
(If you get a "table not found" error, verify that you browsed to the pages that do the tracing after you enabled Application Logging (Storage) and after you clicked Save.)
Notice that in this view you see Process ID and Thread ID for each log, which you don't get in the file system logs. You can see additional fields by viewing the Azure storage table directly.
Click View all application logs.
The trace log table appears in the Azure storage table viewer.
(If you get a "sequence contains no elements" error, open Server Explorer, expand the node for your storage account under the Azure node, and then right-click Tables and click Refresh.)
This view shows additional fields you don't see in any other views. This view also enables you to filter logs by using special Query Builder UI for constructing a query. For more information, see Working with Table Resources - Filtering Entities in Browsing Storage Resources with Server Explorer.
To look at the details for a single row, right-click one of the rows, and then click Edit.
View failed request tracing logs
Failed request tracing logs are useful when you need to understand the details of how IIS is handling an HTTP request, in scenarios such as URL rewriting or authentication problems.
Azure Web Sites use the same failed request tracing functionality that has been available with IIS 7.0 and later. You don't have access to the IIS settings that configure which errors get logged, however. When you enable failed request tracing, all errors are captured.
You can enable failed request tracing by using Visual Studio, but you can't view them in Visual Studio. These logs are XML files. The streaming log service only monitors files that are deemed readable in plain text mode: .txt, .html, and .log files.
You can view failed request tracing logs in a browser directly via FTP or locally after using an FTP tool to download them to your local computer. In this section you'll view them in a browser directly.
In the Configuration tab of the Azure Web Site window that you opened from Server Explorer, change Failed Request Tracing to On, and then click Save.
In the address bar of the browser window that shows the web site, add an extra character to the URL and click Enter to cause a 404 error.
This causes a failed request tracing log to be created, and the following steps show how to view or download the log.
In Visual Studio, in the Configuration tab of the Azure Web Site window, click Open in Management Portal.
In the management portal, click Dashboard, and then click Reset your deployment credentials in the Quick Glance section.
Enter a new user name and password.
In the management portal Dashboard tab press F5 to refresh the page, and then scroll down to where you see Deployment / FTP User. Notice that the user name has the site name prefixed to it. When you log in, you have to use this full user name with the site name prefixed to it as shown here.
In a new browser window, go to the URL that is shown under FTP Host Name in the Dashboard tab of the management portal page for your web site. FTP Host Name is located near Deployment / FTP User in the Quick Glance section.
Log in using the FTP credentials that you created earlier (including the site name prefix for the user name).
The browser shows the root folder of the site.
Open the LogFiles folder.
Open the folder that is named W3SVC plus a numeric value.
The folder contains XML files for any errors that have been logged after you enabled failed request tracing, and an XSL file that a browser can use to format the XML.
Click the XML file for the failed request that you want to see tracing information for.
The following illustration shows part of the tracing information for a sample error.
You've seen how Visual Studio makes it easy to view logs created by an Azure Web Site. You might want to learn more about troubleshooting Azure Web Sites, tracing in ASP.NET applications, and analyzing web server logs.
Azure Web Site troubleshooting
For more information about troubleshooting Azure Web Sites (WAWS), see the following resources:
For help with a specific troubleshooting question, start a thread in one of the following forums:
Debugging in Visual Studio
For more information about how to use debug mode in Visual Studio, see the Debugging in Visual Studio MSDN topic and Debugging Tips with Visual Studio 2010.
If your web site uses an Azure Web API or Mobile Services back-end and you need to debug that, see Debugging .NET Backend in Visual Studio.
Tracing in ASP.NET applications
There are no thorough and up-to-date introductions to ASP.NET tracing available on the Internet. The best you can do is get started with old introductory materials written for Web Forms because MVC didn't exist yet, and supplement that with newer blog posts that focus on specific issues. Some good places to start are the following resources:
For error logging, an alternative to writing your own tracing code is to use an open-source logging framework such as ELMAH. For more information, see Scott Hanselman's blog posts about ELMAH.
Also, note that you don't have to use ASP.NET or System.Diagnostics tracing if you want to get streaming logs from Azure. The Azure Web Site streaming log service will stream any .txt, .html, or .log file that it finds in the LogFiles folder. Therefore, you could create your own logging system that writes to the file system of the web site, and your file will be automatically streamed and downloaded. All you have to do is write application code that creates files in the d:\home\logfiles folder.
Analyzing web server logs
For more information about analyzing web server logs, see the following resources:
Analyzing failed request tracing logs
The Microsoft TechNet web site includes a Using Failed Request Tracing section which may be helpful for understanding how to use these logs. However, this documentation focuses mainly on configuring failed request tracing in IIS, which you can't do in Azure Web Sites.
Debugging Cloud Services
If you want to debug an Azure Cloud Service rather than a Web Site, see Debugging Cloud Services.