Debugging a Cloud Service locally with either Emulator or Emulator Express

As Cloud Services are more like a black-box runtime about which we don't (and shouldn't) need to know anything. However, we should know how they behave different from (or according to) a common IIS installed on a common Windows Server virtual machine.

Tip

The very first versions of Cloud Services had strict restrictions on the interactions with OS, permitted by applications. They had to run in a mode called Microsoft Azure Partial Trust, which isolated an application from the underlying operating system, to prevent the defects and bugs in the code from causing failures in the entire OS. Today, there is no longer an option to isolate an application as a result of developers' continuous requests to let them have control of the VMs under their services.

Despite the capability to access the underlying operating system, it is strongly recommended that you use only the application resources and not rely on false friends such as filesystem, folders structures, and so on. In fact, due to the nature of the PaaS model, the configuration of the operating system as well as the operating system itself could change without any control by the user, but for maintenance or deprecation purposes.

Finally, in the real Azure environment, there are some features available through the Service Runtime API, which is available only when the code is running on Azure or to let developers test their code locally, onto a local emulator shipped with the Microsoft Azure SDK.

The Emulator creates a logical representation of the Azure topology into the machine that runs it. If our service was composed of two web roles and one worker role, for example, the Emulator will start three separate processes in which the application code will behave exactly as it runs on the real platform (with some soft exceptions, which are not discussed in this book). As it needs to open network ports and change some OS settings, the Emulator needs to be started as an administrator. Hence, to start it by simply debugging in Visual Studio, VS itself should be started as an admin. Emulator Express, on its side, runs in a user mode that does not require elevation but has some limitations in terms of emulation coverage.

Getting ready

In this recipe we will explore the debugging options of a Cloud Service using the (full) Emulator and Emulator Express, using the previously created Cloud Service, WAHelloWorld.

How to do it…

In order to explain the differences between the two emulators, we divided it into three parts. Start an elevated Visual Studio window (as an administrator), and proceed as follows:

Note

Part 1: choosing the emulator to use during debugging

1. In the Solution Explorer, right-click on the Azure wrapper project (Cloud Service) and choose Properties (or just select the project and press Alt + Enter).
2. In the page that just opened, select the Web tab.
3. In the Local Development Server options group, choose Use IIS Express.
4. In the Emulator options group, choose Use Full Emulator.

   Note

   Part 2: debugging a worker role using the (full) Emulator

5. Locate the Roles folder under the WAHelloWorld wrapper project.
6. Right-click on the WorkerHelloWorld project and go to the properties page.
7. In the Configuration tab, locate the Instance count box and set the value to 2.
8. Go to the WorkerHelloWorld project, and open the WorkerRole.cs file.
9. Locate the lines with the while (true) block and put a breakpoint on the following code:

   Trace.TraceInformation("Working", "Information");

10. Right-click on the Azure wrapper project (WAHelloWorld), and click on Set as StartUp Project.
11. Press F5 or select Debug. Start debugging on the main menu.

    Tip

    At this point, if you run VS in the user mode, you will be prompted with the message, The Microsoft Azure compute emulator must be run elevated. If so, close VS and right-click on the VS icon; then, run it as the administrator. Repeat the preceding step.

12. Wait for a few seconds while you are shown the Starting the Microsoft Azure Debugging Environment window.

    Tip

    The first time you run the Emulator, Windows will probably ask you to open some ports on the firewall, because the Emulator needs to run Web Services.

13. After about 10 seconds, VS breaks on the tracing line twice, once per running worker.

    Note

    Part 3: understand the compute Emulator interface

14. During debugging, locate the Microsoft Azure Emulator icon in the system tray.
15. Right-click on it and choose Show Compute Emulator UI.
16. In the Microsoft Azure Compute Emulator (full) window, expand all the items in the tree and click on one of the two green balls.
17. Read the log of the instance, which includes the text sent by our code in the tracing line used earlier.
18. Shut down the deployment by stopping debugging, closing the browser, or clicking on the stop icon in the Emulator UI on the current deployment.

How it works…

In part one, from steps 1 to 4, we chose which Emulator to use in debugging. In the Cloud Service properties, we also find these tabs:

• Application: This shows the current version of the SDK used by the project
• Build Events: This lets you customize the pre/post build actions
• Development: This lets you choose some options related to debugging and emulator
• Web: This lets you choose which Emulator (Express or Full) to use and which IIS server set to run

In part two, from steps 5 to 7, we customized the number of simultaneous running instances of the WorkerHelloWorld code. On the configuration page, there is a lot of information and a lot of custom points to edit, which we will see later in the chapter.

In step 9, we set a breakpoint on a line of code previously created by the VS wizard process, as shown in the previous recipe. In step 11, VS prepared the project package and started the Emulator.

Tip

If you use Remote Desktop Services (RDS) in conjunction with Visual Studio to develop your Microsoft Azure projects, it is not necessary that only one instance of the Full Emulator will run on a machine at a point of time. Instead, multiple instances of the Emulator Express can run on a machine at the same time, letting you and your team debug on the same machine remotely.

In step 12, Azure Emulator picked the configuration from the wrapper project and set up virtual instances, deploying our custom code to them. The Emulator started a runner for each instance declared: one for the WebHelloWorld site and two for the WorkerHelloWorld worker.

In step 13, the code stopped twice, as there were two instances deployed to the Emulator. If we deployed 10 instances, the debugger would stop 10 times.

Tip

If you want to perform advanced debugging by temporarily freezing concurrent worker threads, you can use the Threads window. You can access this window by navigating to Debug | Windows | Threads. Locate the thread ID; then, right-click on it and choose Freeze.

In part 3, in steps 14, 15, and 16, we opened the Compute Emulator UI. In the system tray icon context menu, we also noticed the capability to open the Storage Emulator UI and to shut down both the emulators (compute/storage). This feature will be very useful in the upcoming chapters when we talk about storage.

In the final steps, we use the Emulator UI to monitor the parallel workers. In the main windows, we can see the deployment slot with the roles, each one with its own instances. If there are different behaviors between instances, we can monitor the output in the terminal-like window, where it redirects all the tracing output of the worker thread (in both web and worker roles).

There's more…

As the emulator not only emulates the compute engine (web and worker roles) but also the storage engines (which we will see in the upcoming chapters), it is in fact composed of the following:

• Compute Emulator
• Storage Emulator

These two are always referred to as just one, the Azure Emulator. It is also possible to prevent the Storage Emulator from being started during debugging by performing the following steps:

1. Open the Properties page of the Azure wrapper project.
2. In the Development tab, set the Start Microsoft Azure storage emulator option to False.

   Tip

   When debugging your code in a (full) Emulator environment with multiple instances running at the same time, be aware that your code will run in the same AppDomain. This is the main difference between the real and Emulator environment (where the code runs on different machines), and this could cause runtime unexpected behaviors. If you use one or more static classes with static fields, this would result in an unavoidable behavior of shared memory between virtual instances. To actually test this sort of scenario, you should write custom code to differentiate virtual instances, relying on something that is related to the instance name (for example, through the Service Runtime API or using the thread references).

See also

Have a look at the following MSDN links to get additional information:

• More information about running the Emulator at http://msdn.microsoft.com/en-us/library/azure/hh403990.aspx
• Differences between the "real" Azure and the emulated environment at http://msdn.microsoft.com/en-us/library/azure/gg432960.aspx