Troubleshooting a Web Site

Troubleshooting a web site is accomplished by configuring the web site to display application errors, configuring the web site to display environment variables, enabling web site diagnostics, and then analyzing web site application errors and diagnostic data to identify and resolve problems. This tutorial walks you through the process of creating and deploying a simple web site to Windows Azure, causing an error condition on the web site and then applying configuration and logging options to generate troubleshooting data that can be analyzed to identify and resolve the error.

Note

For purposes of this document,Web Siterefers to the host for a web application running on Windows Azure andweb siterefers to a running host instance.

What is Web Site Diagnostics?

Web Site diagnostics provides the following logging and tracing options:

Detailed Error Logging - Logs all errors generated by a web site.
Failed Request Tracing - Logs all failed client requests to a web site.
Web Server Logging - Logs all HTTP transactions on a web site using the W3C extended log file format.

Diagnostics log files are saved to an FTP site for download to a local computer.

Concepts

Concepts introduced in this article include:

Web Site development - Install and use Microsoft WebMatrix on a local computer to create a web site.
Creating and managing Web Sites on Windows Azure - Using the Windows Azure Management portal to create and configure a web site.
Web Site deployment - Deploying a web site from a local computer to Windows Azure.
Troubleshooting Web Sites using configuration options and diagnostics - Configuring web sites to display application errors and environment variables, configuring diagnostics for a web site, collecting diagnostic data and then analyzing the displayed application errors and diagnostics data to troubleshoot and resolve problems.

Install developer tools and create a web site on your local computer

Before discussing how to troubleshoot a web site we must first create a web site. This section walks through using Microsoft WebMatrix to create a simple web site and deploy the web site to Windows Azure.

Install Microsoft WebMatrix

Visit http://www.microsoft.com/web/webmatrix and click the Free Download button. This will run the Web Platform Installer which installs all the dependencies you need to run WebMatrix and then install WebMatrix.

Create a Web Site on your local computer with WebMatrix

To create a web site with WebMatrix follow these steps:

ClickStart,All Programs,Microsoft WebMatrixand then clickMicrosoft WebMatrixto display the WebMatrix Quick Start screen.
ClickTemplatesto display the available templates.
Select theStarter Sitetemplate, enter a value (e.g.AzureWebDiag) for the Site Name and then clickNext.

If the site is created successfully it will be opened for editing in the WebMatrix IDE:
Verify that an instance of the web site is running on your computer by clicking the URL for the site displayed in the WebMatrix IDE, your browser should then display the default page for the web site:

You have now successfully created a web site with WebMatrix.

Create a Web Site on Windows Azure

Before you can deploy your web site from WebMatrix to Windows Azure you must first create a web site on Windows Azure. This section walks through creating a web site on Windows Azure.

'Quick Create' a new Web Site on Windows Azure

Connect to the Windows Azure Portal and click New, Web Site, Quick Create.
Enter a name for the URL (e.g. AzureWebDiag), select an appropriate Region and then click Create Web Site.
After the web site has been created click the name of the web site as it is listed in the Name column of the Windows Azure portal's web sites page, this will open the QuickStart management page for the web site:

Create deployment user credentials

Web Sites support multiple deployment technologies including MSDeploy/Webdeploy, TFS, FTP and GIT. This tutorial will describe how to use FTP to deploy a web site from your developer computer to Windows Azure. Both GIT and FTP deployment require authentication with specific deployment user credentials that you generate from the web site management pages. If you have not already created deployment user credentials follow these steps:

Click Set up deployment credentials under the Publish your app heading on the QuickStart management page. This will display the Deployment Credentials dialog box. Then enter values for Username and Password and click the check mark to generate deployment user credentials.
Open the Dashboard management page for the web site and in the quick glance section you can verify that the web site is configured to use the deployment user credentials that you generated. Deployment user credentials for web sites are always specified using the syntax sitename\username:
Click the link displayed under Site URL to verify that you can access an instance of the web site from your browser. You should see a web page similar to the following:

Deploy the web site from the developer computer to Windows Azure

Now that you have created a web site on Windows Azure and generated the necessary deployment user credentials you can deploy the web site from your developer computer to Windows Azure. To deploy a web site to Windows Azure using FTP you can use one of several FTP clients available for download on the Internet or you can deploy directly from your development environment if the application supports FTP publishing. Since WebMatrix supports FTP publishing, follow these steps to publish the web site you created in WebMatrix to Windows Azure:

Open the web site that you created with WebMatrix.
From the default view of the web site displayed in the WebMatrix IDE, click the Publish button to display the Publish Your Site window and click the Enter settings link under the I already have a hosted web site.
Enter the following values in thePublish Settingsdialog box:
- Protocol: Select FTP
- Server: Specify the URL listed under FTP Hostname on the web site's Dashboard management page.
- Site path: site/wwwroot
- User name: Specify the account listed under Deployment User on the web site's Dashboard management page.
- Password: Specify the password for the deployment user that you created for the web site.
- Destination URL: Specify the URL listed under Site URL on the web site's Dashboard management page.
- Save password: Check this option to save the deployment user password.
- Validate Connection: Click this to verify that WebMatrix can connect to the FTP host using the specified parameters.
Click Save and a Publish Compatibility window is shown. Click Continueto perform the compatibility tests.
Click the Continue button again to initiate deployment of the local web site to Windows Azure. WebMatrix will calculate what files have changed since the last time the web site was published (all of them since this is the first time the web site has been published to Windows Azure) and display a Publish Preview dialog box:
Select the checkbox next to the file StarterSite.sdf and click Continue to initiate deployment to Windows Azure.
After publishing is complete click the link displayed under Site URL from the Dashboard management page to open the an instance of the web site from your browser. You should see a web page similar to the following:

Enable diagnostics for the web site

Enable diagnostics for web sites on the Configure management page. Under the Diagnostics section of the Configure management page you can enable or disable the following logging and tracing options:

Web Server Logging - Turn on Web Server logging to save web site logs using the W3C extended log file format.
Detailed Error Messages - Turn on logging of detailed error messages to capture all errors generated by instances of the web site.
Failed Request Tracing - Turn on failed request tracing to capture information for failed client requests.

Set all logging and tracing options for the web site to On and click the Save icon at the bottom of the page.

Verify connectivity to the FTP site where log files are stored

Connect to the FTP site where diagnostic data is stored using parameters from the web site's Dashboard management page. Open the FTP site listed under Diagnostics Logs using the Deployment User account credentials you created earlier. Consider using an FTP client such as FileZilla to download log files. An FTP client typically provides more flexibility than a web browser for connnecting to and downloading files from an FTP site.

Register an account on the web site

Follow these steps to register an account on the web site:

Open the web site from your browser and click Register in the top right corner of the default web page. You will be directed to registration page similar to the following:
Enter an email address and password and click Register. After you register you will be redirected to the default web page and you will be logged on with the e-mail account that you specified on the registration page:

Introduce an error condition on the web site

Before downloading and analyzing diagnostic data from a web site it will be useful to modify the web site to cause an error to occur. Follow the steps below to cause an error condition and configure the web site to display application errors.

Rename the Web Site user account database file

The web site is configured to store account registration information in the file StarterSite.sdf. To introduce an error condition on instances of the web site, rename the file StarterSite.sdf to StarterSite.bak on the deployed web site:

On the Dashboard page for the web site, click the FTP Host Name under the Quick Glance section. This will start an instance of Internet Explorer. Press the ALT key and select the View menu. Next select Open FTP site in Windows Explorer.
Navigate to the /site/wwwroot/App_Data/ directory,
Rename the file StarterSite.sdf to StarterSite.bak. After renaming the file Windows Azure web sites will be unable to access the user account database, causing an error to occur whenever clients connect to instances of the web site.

Configure the Web Site to display application errors

The default mode of the ASP.NET customErrors configuration setting is RemoteOnly, which prevents application errors from being displayed. To configure the web site to display application errors create a web.config file and set the mode attribute of customErrors to Off:

Open the web.config file located in the root directory of your web site. Open the file with Notepad (or any editor you like) and add the following XML inside the <system.web> elements:
```
<customErrors mode="Off"/>
```
If you are unsure of the location of your web site, open WebMatrix and right-click AzureWebDiag and select Show in File Explorer.

Note
When an ASP.NET web site running on Windows Azure is not configured to display application errors, a web page similar to the following is displayed if an application error occurs:

Display environment variables for a web site

For purposes of troubleshooting it is may be useful to know the values of a web site's environment variables. To display environment variables for .NET or PHP web sites, first paste the following code into Notepad and then save to the web site root directory with the specified file names:

environment.aspx

<script language="C#" runat="server">
public void Page_Load(Object sender, EventArgs E)
{
    System.Collections.DictionaryEntry dictEntry = default(System.Collections.DictionaryEntry);
    Response.Write("<html><head><title></title></head><body></body>");
    Response.Write("<table border=1>");
    Response.Write("<tr><td colspan=2><font color='red'>Environment variables</font></td></tr>");
    Response.Write("<tr><td>Key</td><td>Value</td></tr>");

    foreach (DictionaryEntry dictEntry_loopVariable in Environment.GetEnvironmentVariables())
    {
       dictEntry = dictEntry_loopVariable;
       Response.Write("<tr><td>" + (dictEntry.Key.ToString()) + 
       "</td><td>" + (dictEntry.Value.ToString()) + "</td></tr>");
    }
    Response.Write("</table><br><br>");
    Response.Write("<table border=1>");
    Response.Write("<tr><td colspan=2><font color='blue'>Server Variables</font></td></tr>");
    Response.Write("<tr><td>Key</td><td>Value</td></tr>");

    int loop1, loop2;
    NameValueCollection coll;

    // Load ServerVariable collection into NameValueCollection object.
    coll=Request.ServerVariables;

    // Get names of all keys into a string array. 
    String[] arr1 = coll.AllKeys;

    for (loop1 = 0; loop1 < arr1.Length; loop1++) 
    {
        Response.Write("<tr>");
        Response.Write("<td>" + arr1[loop1] + "</td>");
        String[] arr2=coll.GetValues(arr1[loop1]);

        for (loop2 = 0; loop2 < arr2.Length; loop2++) 
        {
            Response.Write("<td>" + Server.HtmlEncode(arr2[loop2]) + "</td>");
        }
        Response.Write("</tr>");
    }
    Response.Write("</table>");
}
</script>

environment.php

<?php
echo "<pre>";
print_r($_SERVER);
echo "</pre>";
?>

When you add the file environment.aspx to a .NET web application or the file environment.php to a PHP web application, after you have deployed your web site to Windows Azure you can browse to these files to view values assigned to a web site's environment variables.

Deploy the updated Web Site to Windows Azure

Click Publish in the WebMatrix IDE. WebMatrix will calculate any changes made to files since the last time you published and display the changes in a dialog box similar to the following:
Click Continue to initiate transfer of these files to Windows Azure.
After publishing is complete click the link displayed under Site URL from the Dashboard management page to open the web site from your browser. You should see a web page similar to the following:

Download diagnostic log files to your local computer

Now that you have introduced an error condition on the web site, you can download the resulting diagnostic log files to your local computer for analysis. To ensure that web site diagnostics creates all of the log files specified under the Diagnostics section of the web site's Configure management page, refresh your browser once or twice to ensure that the error occurs. Follow these steps to download the diagnostic log files to your local computer:

Open the web site's Dashboard management page and make note of the FTP site listed under Diagnostics Logs and the account listed under Deployment User. The FTP site is where the log files are located and the account listed under Deployment User is used to authenticate to the FTP site.
Consider using an FTP client such as FileZilla to connect to the FTP site. An FTP client provides greater ease of use for specifying credentials and viewing folders on an FTP site than is typically possible with a browser. The screenshot below was taken from the FileZilla FTP client when connecting to the FTP site where the log files for the AzureWebDiag web site are stored. The FTP host name and deployment user credentials are highlighted in red. To copy the contents of the remote FTP folder on the right to the local folder on the left, click to select the folder on the left then right-click the folder on the right and select Download from the shortcut menu that is displayed:
Open the folder on the left with Windows Explorer to access the log files that you downloaded:

Analyze web site log files

Basic analysis of the different log file types can be performed as follows:

Log File	Analyze with
Detailed error logging	Open .htm files from the /LogFiles/DetailedErrors/ folder.
Failed request tracing	Open .xml files from the /LogFiles/W3SVC#########/ folder.
Web server logging	Use Log Parser 2.2 to analyze .log files from the /LogFiles/http/RawLogs/ folder.

View results of detailed error logging

Web site log files include formatting functionality for viewing Detailed Error logging results. Use a web browser to open any .htm files saved to the /LogFiles/DetailedErrors/ folder:

View Detailed Errors

Detailed error logging results also include recommendations for resolving errors including links to relevant Microsoft Knowledge base articles.

View results of failed request tracing

Web site log files provide formatting functionality for viewing failed request tracing results. Use a web browser to open any .xml files saved to the /LogFiles/W3SVC#########/ folder:

Failed Request Tracing

Failed request tracing for web site is based upon the failed request tracing functionality available with IIS 7.5.

Analyze web server logs

Web site logs record all HTTP transactions using the W3C extended log file format and are saved to the /LogFiles/http/RawLogs/ folder. Web site logs can be analyzed using using Log Parser 2.2:

Log Parser Command Window

For more information about Log Parser 2.2 see Download Log Parser 2.2

Troubleshoot the AzureWebDiag web site

This section describes how someone might engage in troubleshooting a web site using the information that is available after you configure the web site to display errors and enable web site tracing and logging.

Using logging and tracing information to troubleshoot Web Site problems

For purposes of troubleshooting the error caused by renaming the file startersite.sdf file to startersite.bak, web server logging, detailed error messge logging and failed request tracing do not provide a single definitive cause and resolution to the problem. The logging and tracing files did however rule out several possible causes by clearly indicating that an HTTP Status code of 500 Internal Server Error was generated on the web site when clients connected to it. This provides a high level of confidence that the problem is unrelated to unsuitable authorization headers (HTTP 401 Unauthorized), bad request syntax (HTTP 400 Bad Request) or numerous other HTTP 3xx, 4xx and 5xx status codes. According to HTTP 1.1 Status Definitions, an HTTP Status code of 500 Internal Server Error indicates that "The server encountered an unexpected condition which prevented it from fulfilling the request".

Using detailed web site errors to troubleshoot Web Site problems

Addition troubleshooting should focus on the error messages displayed as a result of modifying the web.config file or possibly by analyzing the web site's environment variables.

If we look at the detailed error message created on the web site we can see that an unhandled exception was thrown by the following method call in Line 2 of the file _AppStart.cshtml:

WebSecurity.InitializeDatabaseConnection("StarterSite", "UserProfile", "UserId", "Email", true);

The error's Description: is "An unhandled exception occurred during the execution of the current web request. Please review the stack trace for more information about the error and where it originated in the code."

Exception Details: listed for the error are "System.InvalidOperationException: Connection string "StarterSite" was not found."

If we examine the stack trace displayed under the error we can see that the error originated from a call to the InitializeDatabaseConnection() method of the WebMatrix.WebData.WebSecurity class described at WebSecurity.InitializeDatabaseConnection Method.

Since the InitializeDatabaseConnection Method is only using 5 parameters we determine that the overloaded InitializeDatabaseConnection() method described in the topic WebSecurity.InitializeDatabaseConnection Method (String, String, String, String, Boolean) is being called.

Since the Exception details indicate that 'Connection string "StarterSite" was not found', we can have a look at the definition for the connectionStringname parameter:

connectionStringName Type: System.String
The name of the connection string for the database that contains user information. If you are using SQL Server Compact, this can be the name of the database file (.sdf file) without the .sdf file name extension.

This parameter definition provides a clue as to the cause of the error. According to Connecting to a SQL Server or MySQL Database in WebMatrix, "WebMatrix includes SQL Server Compact, which is a lightweight version of Microsoft SQL Server that lets you create databases for your web sites. When you create a database, it's added as an .sdf file in the App_Data folder of your web site." Since this web site does use SQL Server Compact and the value specified for the connectionStringName parameter is StarterSite, the InitializeDatabaseConnection() method is looking for the file StarterSite.sdf in the web site's \root\App_Data\ directory.

Checking the web site's \root\App_Data\ directory we can verify that there is no file named StarterSite.sdf, since of course we renamed it to StarterSite.bak. After renaming this file back to startersite.sdf the InitializeDatabaseConnection() method is able to find the file that it was expecting and the web site works as expected.