Controlling your instances in the Windows Azure Compute Emulator

This is a follow-up post for a question I answered on StackOverflow. There might be times where you would want to control the instances in the emulator as if you were really running in Windows Azure. Increasing the number of instances, decreasing the number of instances, reacting on a configuration change or even killing a few instances to test the resiliency of your application. Even though this isn’t really documented, you can do all of these things with the emulator.

Increasing or decreasing the number of instances

In real life you would use the Service Management API to modify the Service Configuration or you would modify it through the portal. Now in the emulator you can do the same thing. After building the cloud project in Visual Studio you’ll see a ServiceConfiguration.cscfg file under bin\Debug|Release. By opening the file with any tekst editor you can simply change the number of instances here. In this file I increased the number of instances from 1 to 3:

If you change this value after starting the application you’ll be able to update the running deployment with the tool csrun.exe (this tool allows you to update a running deployment in the emulator). You can find csrun.exe under C:\Program Files\Microsoft SDKs\Windows Azure\Emulator or simply open the Windows Azure Command Prompt) and this is how you should call it:

We know where to find the ServiceConfiguration.cscfg (under bin\Debug|Release). But what about the deployment ID? Take a look at the Compute Emulator (your application must be running), in this screenshot you can see that this deployment is called deployment17(31). So when calling csrun.exe I should use 31 as deployment ID.

To update the number of instances I simply modify the ServiceConfiguration.cscfg (change the count from 1 to 3) and execute the following command:

Wait a few seconds and you’ll see that the number of instances changed:

In order to make all of this work with the emulator you’ll need to start the application without debugging. If you do choose to start the application with the debugger (by pressing F5 for example) you’ll see that any new instances you add simply won’t work. That’s why it’s important to start the application without debugging.

Shutting down / Killing instances

When you run your application in the emulator it starts 1 Web Role (WaIISHost.exe) / Worker Role (WaWorkerHost.exe) process per instance:

When you kill one of these processes it’s as if you killed an instance. After switching back to the emulator you’ll see that the icon of that specific instance you killed changed color and the logs will show that the state of the instance is Unknown/Destroyed:

When the debugger is attached you’ll see this happen and the instance will never restart, allowing you to test scenarios where you suddenly loose one or more instances. If the debugger is not attached this will all happen very fast and the instance will restart right away (in Visual Studio you can choose to start without debugging).

Handling the RoleEnvironment.Changing event in the emulator

You might also want to test how your application reacts when a setting is changed. Maybe you’re caching a connection string somewhere and you need to update it whenever someone changes the setting through the Management Portal. Handling a configuration change is possible with the RoleEnvironment.Changing and  RoleEnvironment.Changed events. Typically you handle these events in the WebRole.cs/WorkerRole.cs files:

In order to trigger the RoleEnvironment.Changing event (the Changed event doesn’t seem to go off) you’ll need to modify the ServiceConfiguration.cscfg and change a setting under the ConfigurationSettings element. After modifying the configuration file, simply update the running deployment using csrun.exe. But here again, this will only work if you started the application without debugger.

Exploring how to handle this event can be troublesome if you can’t even debug. That’s why you might want to output some information to the emulator. In case you didn’t know, you can use the DevelopmentFabricTraceListener class to output your logs in the emulator. Here is some sample code that will create a DevelopmentFabricTraceListener and write to the emulator whenever an instance starts or if the Changing event was raised. It’s important to note that the DevelopmentFabricTraceListener will only work with the local emulator (that’s why I added the check for IsEmulated).

Whenever the application starts or the configuration changes you can see this in the emulator:


About Sandrino Di Mattia

Sandrino Di Mattia is a Customer Success Engineer at Auth0 and a Microsoft Azure MVP.