Getting Started with the Windows Azure Tools for Visual Studio

To install the Windows Azure Tools, on the menu bar, choose File, New, Project. From Installed Templates choose either the Visual Basic or Visual C# node, and then choose the Cloud node that contains a project template named Enable Windows Azure Tools.

Note
This template is only displayed in the list if you have not installed the Windows Azure Tools before on this computer.

To download the tools, choose the OK button.

A Windows Azure Tools tab is displayed.

To start the download, choose the Download Windows Azure Tools button. The web installer is now displayed. Follow the instructions provided by the web installer to install the latest version of the Windows Azure Tools and the Windows Azure SDK.

Note
Windows Azure Tools requires Internet Information Services (IIS) version 7 or later or IIS Express. To install IIS or IIS Express, use the Microsoft Web Platform Installer.

Start Visual Studio as an administrator.

To create a Windows Azure project, on the menu bar, choose File, New, Project.

In the C# and VB project templates that are displayed in Installed Templates, choose the Cloud template type that was updated. Choose Windows Azure Project. In the .NET Framework list, choose the target framework that you want to use.

Note
Visual Studio 2012 supports both the .NET Framework 4.5 and the .NET Framework 4, and Visual Studio 2010 supports both the .NET Framework 4 and the .NET Framework 3.5.

In the Name text box, enter the name for your project and choose the OK button.

The New Windows Azure Project dialog box is displayed.

To add a web role to the solution, choose ASP.NET Web Role and then choose the right arrow. You can add multiple web and worker roles to your Windows Azure solution.

The roles are displayed in the Windows Azure solution pane of the dialog box.

To rename WebRole1 to MyWebRole, move the pointer over WebRole1and choose the pencil icon on the right side. Type the new name and then choose the Enter button. (Keyboard: Tab to move the focus to WebRole1 and press F2 to edit.)

To create the new Windows Azure project, choose the OK button.

You now have a solution with the following two projects:

• A Windows Azure project
  
  
• A web role that is an ASP.NET web application
  
  

The Solution Explorer view will look similar to the following illustration:

To open default.aspx in design view, open the shortcut menu for the default.aspx file and then choose View Designer.

To open the toolbox, choose the Toolbox icon. To add a button to the page, open the shortcut menu for Button in the Toolbox view and choose Copy. In the editor window for Default.aspx choose Design, then open the shortcut menu and choose Paste. To add a click event handler for the button, double-click the new button that you added to the page.

In the click event handler named Button1_Click, add code that will upload some text to the blob service and add a diagnostics message. To add the required Windows Azure types, add the following using statements to default.aspx.cs:

using Microsoft.WindowsAzure;
using Microsoft.WindowsAzure.StorageClient;
using Microsoft.WindowsAzure.ServiceRuntime;

Add the following code to accomplish these tasks:

• Create a CloudStorageAccount instance from a connection string in the configuration settings
  
  
• Create a blob container
  
  
• Upload a text blob to that container
  
  
• Add a diagnostics message for a web role
  
  

protected void Button1_Click(object sender, EventArgs e)
{
    // Setup the connection to Windows Azure Storage
    var storageAccount = CloudStorageAccount.Parse(RoleEnvironment.GetConfigurationSettingValue("MyConnectionString"));
    var blobClient = storageAccount.CreateCloudBlobClient();
    // Get and create the container
    var blobContainer = blobClient.GetContainerReference("quicklap");
    blobContainer.CreateIfNotExist();
    // upload a text blob
    var blob = blobContainer.GetBlobReference(Guid.NewGuid().ToString());
    blob.UploadText("Hello Windows Azure");
    // log a message that can be viewed in the diagnostics tables called WADLogsTable
    System.Diagnostics.Trace.WriteLine("Added blob to Windows Azure Storage");
}

To add a breakpoint to the line of code you just added in the Button1_Click event handler, open the shortcut menu for the line of code “blob.UploadText("Hello Windows Azure");” and then choose Breakpoint, Insert Breakpoint.

Add code to set up the diagnostics monitor to transfer the logs every second and start the monitor. The diagnostics monitor uses a connection string that is added when you create the Windows Azure project. The following code must be added at the beginning of the OnStart method in WebRole.cs:

            //Get the configuration object
            DiagnosticMonitorConfiguration diagObj = DiagnosticMonitor.GetDefaultInitialConfiguration();

            //Set the service to transfer logs every second to the storage account
            diagObj.Logs.ScheduledTransferPeriod = TimeSpan.FromSeconds(1);

            //Start Diagnostics Monitor with the new storage account configuration
            DiagnosticMonitor.Start("Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString", diagObj);

Note
If you are debugging on the Windows Azure platform, you would not want to transfer the logs every second. This value is set this low for the purposes of the walkthrough only.

To build the project, open the shortcut menu for the Windows Azure project and then choose Build.

To see the build output, open the shortcut menu for the Windows Azure project and then choose Open Folder in Windows Explorer. Go to the bin\debug directory to view the build output.

To modify settings, choose a role under the Roles node for your Windows Azure project in Solution Explorer, open the shortcut menu for the role and choose Properties.

This will display the property pages for the web role. Every role-level element and attribute in the service definition and service configuration files can be edited using the property pages.

Important

If you want to run your Windows Azure application locally to debug it and you also want to publish your application to Windows Azure, this typically requires different values for the settings for your roles. For example, you might want to run four instances of a role in Windows Azure, but just one instance when you debug in your local environment. You can now have multiple service configurations in your Windows Azure project that enable you to define these different values. You can then select which one you want to use. For more information about how to do this, see Configuring a Windows Azure Project

To make changes for all the service configurations, in the Service Configuration list choose All Configurations.

To change the instance count, in the Instance count text box type 2.

To move to the Settings tab, choose Settings. (Keyboard: Tab to Configuration and then choose the down arrow.)

To configure Visual Studio to use the local storage emulator when you run or debug your Windows Azure application, you must add the connection string that you used in the button click event handler. Use the following steps to do this:

1. On the Settings tab choose the Add Setting button.

2. In the Name text box, type MyConnectionString.

3. In the Type combo box, choose Connection String.

4. Choose the ellipsis in the Value text box. The Storage Account Connection String dialog box is displayed. Choose Use the Windows Azure storage emulator and then choose the OK button.

5. On the toolbar, choose the Save icon.

At the end of this walkthrough when you are ready to publish to Windows Azure, you can use this Settings tab to change the value for this connection string for the Cloud service configuration (called ServiceConfiguration.Cloud.cscfg) to use a Windows Azure storage account. You can then use this service configuration when you publish this Windows Azure application.

On the menu bar, choose Debug, Start Debugging (Keyboard: F5).

Important

If the Windows Azure project is not set as your startup project, the following error occurs when you click the button to trigger the breakpoint: External component has thrown an exception. The reason that the error occurs is because the development fabric must be initialized in order to invoke the Windows Azure API calls. To set the Windows Azure project as the startup project, open the shortcut menu for your Windows Azure project and choose Set as Startup Project.

The storage emulator and the compute emulator for Visual Studio are started. These emulators enable you to run and debug your Windows Azure application locally before you publish it to Windows Azure.

Note
A Windows Azure icon is displayed in the notification area that enables you to view the compute emulator UI and the storage emulator UI, or to shut down these services.

If you are using the storage emulator for the first time, the Development Storage Initialization dialog box is displayed. When the initialization process is complete, choose the OK button to close the dialog box.

The browser starts automatically and points to the ASP.NET web site.

To manage your local deployments, open the shortcut menu for the Windows Azure icon in the notification area and then choose Show Compute Emulator UI.

The Windows Azure Compute Emulator is displayed.

Choose MyWebRole to display the instances of the web role, as shown in the following illustration. Choose a specific instance to view only that individual instance.

Note
There are two instances of the web role because the instance count was set to 2 for the role. Either instance can process a request.

To trigger the breakpoint that you set in the debugger, choose the button that you created.

To step through the lines of code until you have uploaded the text to the blob and logged the message to the diagnostics table, press F10 three times.

To view the data that you added to the blob, on the menu bar choose View, Server Explorer. Open the Windows Azure Storage node in the tree, and then choose the Development, Blobs node. Double-click the quicklap node, as displayed in the following illustration:

The data in the blob is displayed in the quicklab tab.

To view the data, double-click an entry displayed in the list.

To view the diagnostics messages that you logged, on the menu bar choose View, Server Explorer if it is not already visible. Open the Windows Azure Storage node in the tree, and then choose the Development, Tables node. Double-click the WADLogsTable node.

The diagnostics messages are displayed in the WADLogsTable tab. The data for the message is the last column in the table.

To view the activity log for Windows Azure, on the menu bar choose View, Other Windows, Windows Azure Activity Log. The activity log allows you to track the status of long-running operations. You will see an entry corresponding to the text blob you downloaded.

If you are using the storage emulator, open the shortcut menu for the Windows Azure icon in the notification area and then choose Show Storage Emulator UI to bring up the following dialog, which will allow you to control the running storage services as well as reset all data.

Follow these steps if you have to change any connection strings in your application to use Windows Azure storage services:

1. In Solution Explorer, open the shortcut menu for the web role in your Windows Azure project that accesses the storage services and choose Properties.

2. In the property pages for the role, choose the Settings tab.

3. To modify the service configuration settings only for the Cloud configuration, in the Service Configuration list choose Cloud. You can then use this service configuration when you publish your Windows Azure application.

4. To modify any connection string settings, choose the … button next to the setting.

   The Create Storage Connection String dialog box appears.

5. Under Connect using, choose the Your subscription option.

6. In the Subscription list, choose your subscription. If the list doesn't contain the subscription that you want, choose the Download Publish Settings link.

7. In the Account name list, choose your storage account name.

   Windows Azure Tools obtains storage account credentials automatically by using the .publishsettings file. To specify your storage account settings manually, get your storage account name and primary key from the Management Portal, and then choose Manually entered credentials.

8. You must choose one of the following options to determine how the service will access the storage account:

   • Use HTTP. This is the standard option. For example, http://<account name>.blob.core.windows.net.
     
     
   • Use HTTPS for a secure connection. For example, https://<accountname>.blob.core.windows.net.
     
     
   • Specify custom endpoints for each of the three services. You can then type these endpoints into the field for the specific service.
     
     

     Note

     If you create custom endpoints this allows you to create a more complex connection string. When you use this string format, you can specify storage service endpoints that include a custom domain name that you have registered for your storage account with the Blob service. In addition, you can grant access only to blob resources in a single container through a shared access signature. For more information about how to create custom endpoints, see How to Configure Connection Strings.

9. To save these connection string changes, choose the OK button.

   After you save these changes, you can build and run your Windows Azure application from within Visual Studio using this service configuration that you updated and verify that it works as expected against the Windows Azure storage services. For more information about how to select a service configuration to run and debug locally, see How to: Configure a Windows Azure Project with Visual Studio.

To publish your application, open the shortcut menu for the Windows Azure Project that contains your role in Solution Explorer. Then choose Publish, as shown in the following illustration:

The Publish Windows Azure Application dialog box appears.

If you've never used the wizard, choose the Sign In To Download Credentials link, sign in to the portal when prompted, provide your Windows Azure user name and password, and then save the settings to a file. You'll import the settings file in the next step.

Warning
The settings file contains certificate information. Save the file to a secure location.

Choose the Import button to populate the subscription list.

Note
The settings file has a .publishsettings extension.

In the Choose your subscription list, choose the subscription to use for this deployment.

If you choose <Manage…>, you can create, edit, or delete subscriptions.

When you're satisfied with your subscription information, choose the Next button to open the Settings page, and then choose the Common Settings tab.

In the Environment list, choose the deployment environment that's used to host your cloud service.

You can deploy to an environment that's empty or that another deployment is using.

In the Build configurationlist, choose the configuration you want, such as Release.

In the Service configuration list, choose Cloud.

To configure remote desktop connections for this deployment environment so that you can connect to the virtual machine that's running each instance of a role, choose the Configure Remote Desktop connections link.

For more information, see Using Remote Desktop with Windows Azure Roles.

Choose the Advanced Settings tab.

On the Storage account list, choose the account to use to upload the service package to this account as part of the deployment process.

Note
This storage account doesn't have to be the storage account that you plan to use for the data for your application.

If you don't want to automatically overwrite an existing deployment when you publish a new build of your application, select the Deployment update check box.

For more information about deployment update settings, see Publish Windows Azure Application Wizard.

A default name is created for your deployment. To change this name, you can enter a new name or amend the default name in Deployment label. This name is used in the Management Portal.

To append the date and time to the label for the deployment, select the Append current date and time check box.

To enable IntelliTrace for this deployment, select the Enable IntelliTrace check box.

IntelliTrace provides debugging information for your application that you can use to step through your code from Visual Studio Ultimate. For more information, see Debugging Using IntelliTrace.

Note
You can enable IntelliTrace only when you publish your application from Visual Studio Ultimate.

To enable profiling for this deployment to determine the performance of your Windows Azure application, select the Enable profiling check box. Profiling provides performance information for your application. For more information about how to configure the settings for profiling, see Testing the Performance of a Cloud Service.

Important
You can enable either IntelliTrace or profiling when you publish your Windows Azure application. You cannot enable both.

(Optional) If you are publishing from Visual Studio and you have installed the latest version of the Windows Azure tools, you can also enable Web Deploy for all your web roles. For the requirements and the detailed steps to do this, see To Enable Web Deploy When You Publish Your Application.

To publish your Windows Azure application, choose the Publish button. Visual Studio starts the deployment process. You can see the progress of the deployment from the Windows Azure Activity Log window. This log is automatically displayed when the deployment process starts. You can expand the line item in the activity log to show detailed information, as shown in the following illustration:

(Optional) To cancel the deployment process, open the shortcut menu for the line item in the activity log and choose Cancel and remove. This stops the deployment process and deletes the deployment environment from Windows Azure.

Note
To remove this deployment environment after it has been deployed, you must use the Management Portal.

(Optional) After your role instances have started, Visual Studio automatically shows the deployment environment in the Windows Azure Compute node in Server Explorer. From here you can see the status of the individual role instances. For more information about how to use Server Explorer to view your deployments, see Viewing the State of a Cloud Service using Server Explorer.

The following illustration shows the role instances while they are still in the Initializing state:

To access your application after deployment, choose the arrow next to your deployment when a status of Completed is displayed in the Windows Azure Activity log. To start a browser with your application, choose the hyperlink that is displayed in the deployment details.

To view IntelliTrace logs, open the shortcut menu for the instance for which you want to view them and choose View IntelliTrace logs, as shown in the following illustration:

The logs will be collected for that instance, uploaded to the blob service, and then downloaded and opened in Visual Studio.

With the log opened in Visual Studio, you can make use of the Visual Studio IntelliTrace debugging features to debug your hosted service. For more information about how to use IntelliTrace, see Debugging with IntelliTrace.