Digging in to the Windows Azure Service Package

What is the Service Package?  It is what contains the Service Definition for your Cloud Service along with the content and binaries for each of the roles.

It comes in 2 flavors.  The first being a folder structure with the extension csx.  For example if you look in the output folder of the Cloud Service project (bin\debug or bin\release) you will see the following:

Where the highlighted CloudService6.csx file is the folder structure version of the Service Package – the Service Definition file is located there.

The Service Configuration file is kept separate to the Service Package as it can be updated independently of the Service Package, for example to update setting values or increase/decrease the number of instance of each of your roles.

The folder version of the Service Package is the output of the Cloud Service project.  This is what is used to run the Cloud Service on the Development Fabric.

If you look in the WebRole and WorkerRole directories, you will see the content and binaries that will be used to run your roles.

The second flavor of the Service Package is the single file version (cspkg file extension), which is created when you publish the Cloud Service by right-clicking on the Cloud Service project and selecting “Publish…”

This is the file that you upload (along with the Service Configuration file) to the Windows Azure cloud to run your service.

The single file package is found in the Publish folder of the output directory of the Cloud Service project along with the Service Configuration file:

This is the directory that VS automatically opens up when you publish from the Cloud Service.

It is interesting to know about these two flavors of Service Packages so that you can know where to look to see what files are being packaged up and executed by the Development Fabric locally and/or Fabric in the cloud. 

The single file Service Package is zipped and encrypted so you won’t be able to browse through it unless you set an environment variable to package without encryption.

Note:  The steps to create an unencrypted package are for diagnostic purposes only and should not be used for production packages.  Additionally, the method is only intended for internal use, is not supported and may be changed at any time.  (enough of a disclaimer? :) )

With Visual Studio closed, create a new environment variable called: _CSPACK_FORCE_NOENCRYPT_ set the value to true.  This will look like this:

You can access the environment variables dialog from the advanced tab on the System Properties from the Advanced system settings task button on the left of: Control Panel\System and Maintenance\System.

Now startup Visual Studio, load a Cloud Service project and hit publish.  When you publish, you will see the following message in the output window:

C:\Program Files\MSBuild\Microsoft\Cloud Service\v1.0\Microsoft.CloudService.targets(0,0): warning : CloudServices44 : Forcing creation of unencrypted package.

Now, you can unzip your way through the single file Service Package.  Rename the service package to .zip and unzip.

Inside the first directory you can unzip the WebRole_*.cssx and WorkerRole_*.cssx files to reveal your worker and web role directories.

One thing to mention here is that you can deploy both unencrypted and encrypted versions of the Service Package to Windows Azure, although I'll reiterate that you should really only deploy the encrypted version of your package.

Hope this helps with diagnostic and debugging type activities – we are thinking about how we can make this easier in the tools.