Local Storage on Windows Azure

12/20/2009 This post has been updated to be consistent with the latest version of the Azure SDK. The primary changes are from RoleManager to RoleEnvironment and the addition of a new cleanOnRoleRecycle attribute to the schema definition for LocalStorage.

Windows Azure Storage supports several types of storage: tables, queues and blogs. These can be accessed RESTfully over a network by applications resident either in the cloud or on client machines. However, Windows Azure also supports the concept of local storage which can be accessed using standard .Net Stream operations and which does not require network access.

Local storage is created by a role instance and is only accessible by the instance that created it. This means that one instance of a web role or worker role can not access the local storage of another instance even of the same role. For example, in a simple application with one instance of a worker role and one instance of a web role the two instances have no access to the local storage of the other role.

Local Storage is defined using the LocalStorage element of the Service Definition file. This element has two attributes:

  • name – a unique name for the store
  • cleanOnRoleRecycle – (optional) specifies whether or not the local store is cleared when the role is recycled
  • sizeInMB – the desired size of the local store (minimum 1MB, maximum 20GB during CTP)

For example:

<?xml version=”1.0″ encoding=”utf-8″?>
<ServiceDefinition name=”LocalStorageDemo” xmlns=”http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceDefinition”&gt;
  <WebRole name=”WebRole”>
      <!– Must use port 80 for http and port 443 for https when running in the cloud –>
      <InputEndpoint name=”HttpIn” protocol=”http” port=”80″ />
    <LocalStorage name=”WebRoleStorage” sizeInMB=”5″ cleanOnRoleRecycle=”false”/>
  <WorkerRole name=”WorkerRole”>
    <LocalStorage name=”WorkerRoleStorage” sizeInMB=”20″ cleanOnRoleRecycle=”true”/>

In this example, local storage has been defined for both the web role and the worker role.

UPDATE 3/25/2010 Note that it is possible to declare more than one piece of named local storage for a given role in the Service Definition file.

In a presentation at PDC 20009, Dianne O’Brien stated the following as the maximum size of local storage (sizeInMB) for the various Azure instance sizes when Azure goes live:

Azure instance size Maximum size of local storage
Small 250GB
Medium 500GB
Large 1000GB
Extra-Large 2000GB


The local storage definition in the Service Definition file is accessed using the RoleEnvironment.GetLocalResource() method declared:

public static LocalResource GetLocalResource(String localResourceName);

localResourceName is the name attribute from the LocalStorage element in the relevant web or worker role definition in the Service Definition file. This would be either WebRoleStorage or WorkerRoleStorage when using the example Service Definition file given above. Note that a RoleException will be raised by an attempt to access a localStorageName not defined for the role.

The returned LocalResource is declared:

public interface LocalResource {
    Int32 MaximumSizeInMegaBytes { get; }
    String Name { get; }
    String RootPath { get; }

Name is the local storage name from the Service Definition file passed in as the localResourceName parameter. RootPath is the root path in the file system where the local storage will reside. In the Development Fabric, MaximumSizeInMegaBytes is set to 0.

The following is a basic example of using local storage:

protected void UseLocalStorage()
    String workerRoleStorageName = “WorkerRoleStorage”;
    String workerRoleFileName = “WorkerRoleStorage.txt”;
    LocalResource localResource =
    String path = localResource.RootPath +
          workerRoleFileName ;
    FileStream writeFileStream = File.Create(path);
    using (StreamWriter streamWriter = new StreamWriter(
        streamWriter.Write(“Testing worker role storage”);

    String fileContents = String.Empty;
    FileStream readFileStream =File.Open(path, FileMode.Open);
    using (StreamReader streamReader =
         new StreamReader(readFileStream))
       fileContents = streamReader.ReadToEnd();

This example accesses the Service Definition File, as given earlier, to retrieve the local storage definition, then creates a file in local storage and writes some text to it. Finally, it reads the text from the file into String.

Local storage is not deployed with the published package. Consequently, it must be created independently by each deployed instance using it. Local storage is not shared by instances and persists over restarts if cleanOnRoleRecycle is false (although not if the instance is moved to a new machine)

Note that in the Development Fabric UI local storage can be accessed by right clicking on the instance.

UPDATE 9/30/3009
Added maximum size for sizeInMb configuration parameter.

UPDATE 12/20/2009
Updated to be consistent with the most recent Azure API.

UPDATE 12/21/2009
Added table with maximum sizes of local storage for the various production Azure instance sizes.

UPDATE 3/25/2010
Added comment about the possibility of defining more than one named local resource for each role.

UPDATE 2/1/2011
Changed ILocalResource to LocalResource

Technorati Tags: ,

About Neil Mackenzie

Cloud Solutions Architect. Microsoft
This entry was posted in Uncategorized. Bookmark the permalink.

2 Responses to Local Storage on Windows Azure

  1. Pingback: Azure FAQ: Can I write to the file system on Windows Azure? « Coding Out Loud

  2. Pingback: Writing to Azure Local Storage from a Windows Service « Coding Out Loud

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s