Using local storage in an instance

The Microsoft Azure Fabric Controller deploys an instance of a Microsoft Azure role onto a virtual machine (VM) as three Virtual Hard Disks (VHD). The guest OS image is deployed to the D drive, the role image is deployed to the E or F drive, while the C drive contains the service configuration and the local storage available to the instance. Only code running with elevated privileges can write anywhere other than the local storage.

Tip

As Azure could change the way it manages the underlying operating system of Cloud Services, the information provided about filesystem topology could change suddenly with no obligation from Microsoft to explain it.

Each instance has read-write access to a reserved space on the C drive. The amount of space available depends on the instance size and ranges from 20 GB for an Extra Small instance to 2,040 GB for an Extra Large instance. This storage space is reserved by being specified in the service definition file, ServiceDefinition.csdef, for the service. Note that RoleEnvironment.GetLocalResource() should be invoked to retrieve the actual path to local storage.

The LocalStorage element for a role in the service definition file requires a name (Name) and, optionally, the size in megabytes to be reserved (sizeInMb). It also requires an indication of whether the local storage should be preserved when the role is recycled (cleanOnRoleRecycle). This indication is only advisory, as the local storage is not copied if an instance is moved to a new VM.

Multiple local storage resources can be specified for a role as long as the total space allocated is less than the maximum amount available.

Tip

In fact, the purpose of the allocated space is just an upper-bound limit, as an exception is thrown only when a write operation actually exceeds the allowed maximum.

This allows different storage resources to be reserved for different purposes. Storage resources are identified by name.

The RoleEnvironment.GetLocalResource() method can be invoked to retrieve the root path for a local resource with a specific name. The role instance can invoke arbitrary file and directory-management methods under this path.

In this recipe, we'll learn how to configure and use local storage in an instance.

How to do it...

We are going to access the local storage on an instance and create a file on it. We will write to the file and then read the contents from the file. We will do this using the following steps:

1. Use Visual Studio to create an empty cloud project.
2. Add a worker role to the project (accept the default name of WorkerRole1).
3. Right-click on the WorkerRole1 item under the Roles folder of the cloud project. Then, go to the Properties page and click on the Local Storage tab.
4. Click on Add Local Storage and set Name as WorkerStorage, a size of 10 MB, and leave the Clean on role recycle box unchecked.
5. Add a new class named LocalStorageExample to the project:
6. Add the following using statements to the top of the class file:

   using Microsoft.WindowsAzure.ServiceRuntime;
   using System.IO;

7. Add the following private members to the class:

   static String storageName = "WorkerStorage";
   String fileName;
   LocalResource localResource = RoleEnvironment.GetLocalResource(storageName);

8. Add the following constructor to the class:

   public LocalStorageExample(String fileName)
   {
     this.fileName = fileName;
   }

9. Add the following method, which writes to the local storage, to the class:

   public void WriteToLocalStorage()
   {
     String path = Path.Combine(localResource.RootPath, fileName);
   
     FileStream writeFileStream = File.Create(path);
     using ( StreamWriter streamWriter =new StreamWriter( writeFileStream))
     {
       streamWriter.Write("think but this and all is mended");
     }
   }

10. Add the following method, which reads the file, to the class:

    public void ReadFromLocalStorage()
    {
      String fileContent = string.Empty;
      String path = Path.Combine(localResource.RootPath, fileName);
      FileStream readFileStream = File.Open(path, FileMode.Open);
      using (StreamReader streamReader =new StreamReader(readFileStream))
      {
        fileContent = streamReader.ReadToEnd();
      }
    }

11. Add the following method, using the methods added earlier, to the class:

    public static void UseLocalStorageExample()
    {
      String fileName = "WorkerRoleStorage.txt";
    
      LocalStorageExample example =new LocalStorageExample(fileName);
      example.WriteToLocalStorage();
      example.ReadFromLocalStorage();
    }

12. Add the following code at the start of the Run() method in WorkerRole.cs:

    LocalStorageExample.UseLocalStorageExample();

How it works...

In steps 1 and 2, we created a cloud project with a worker role.

In step 3, we used the GUI to locate the local storage section of the project properties. In step 4, we added the definition of the local storage to the service definition file for the Cloud Service. We provided a name by which it can be referenced and a size. We also specified that the content of local storage should be preserved through an instance recycle.

In steps 5 and 6, we set up the LocalStorageExample class. In step 7, we added some private members to store the filename and the local storage resource. We initialized the filename in the constructor that we added in step 8.

In step 9, we added a method that created a file and added some text to it. In step 10, we opened the file and read the text.

In step 11, we added a method that invoked the other methods in the class. In step 12, we invoked this method.

See also

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

• Additional details about local storage behavior and process model at http://msdn.microsoft.com/en-us/library/azure/ee758708.aspx