A local storage resource is a reserved directory in the file system of the virtual machine in which an instance of a role is running. Code running in the instance can access the local storage resource when it needs to write to or read from a file. For example, a local storage resource can be used to cache data that may need to be accessed again while the service is running in Windows Azure.
A local storage resource is declared in the service definition file. You can declare any number of local storage resources for a role. Each local storage resource is reserved for every instance of that role. The minimum amount of disk space that you can allocate for a local storage resource is 1 MB. The maximum amount that you can allocate for any given local resource depends on the size of the virtual machine that is specified for the role. Each virtual machine size has a corresponding total storage allocation, and the total space allocated for all local storage resources declared for a role cannot exceed the maximum size allotted for that virtual machine size. For more information about the maximum amount of local disk space that is allotted for each virtual machine size, see Configure Virtual Machine Sizes.
Be aware that it is the developer's responsibility to ensure that the amount of disk space that is requested for a local storage resource does not exceed the maximum amount allotted for a virtual machine. If you configure a local storage resource to be larger than the allowed maximum, an error will not occur until you attempt a write operation that exceeds the allowed maximum. In that case, the write operation will fail and an out of disk space error message will appear. The processing model for Windows Azure is try/fail. If you receive an out of disk space error you can handle the error and clear some disk space. You can then retry the write operation.
You can specify that a local storage resource be preserved when an instance is recycled. However, data that is saved to the local file system of the virtual machine is not guaranteed to be durable. If your role requires durable data, it is recommended that you use a Windows Azure drive to store file data. Windows Azure drives are backed by the Windows Azure Blob service, so they are guaranteed to be durable.
To declare a local storage resource within the service definition file, add the LocalResources element as a child of a WebRole element or the WorkerRole element. Then add a LocalStorage element to represent the resource. The LocalStorage element takes three attributes:
sizeInMB: Specifies the desired size for this local storage resource
cleanOnRoleRecycle: Specifies whether the local storage resource should be wiped clean when a role instance is recycled, or whether it should be persisted across the role life cycle. The default value is true.
The following service definition file shows two local storage resources that are declared for a web role:
<?xml version="1.0" encoding="utf-8"?>
<ServiceDefinition xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceDefinition" name="MyService">
<WebRole name="MyService_WebRole" vmsize="Medium">
<InputEndpoint name="HttpIn" port="80" protocol="http" />
<Setting name="SimpleConfigSetting" />
<LocalStorage name="localStoreOne" sizeInMB="10" />
<LocalStorage name="localStoreTwo" sizeInMB="10" cleanOnRoleRecycle="false" />
For more information about the service definition file, see Service Definition Schema.
The Windows Azure Managed Library provides classes for accessing the local storage resource from within code that is running in a role instance. The RoleEnvironment.GetLocalResource method returns a reference to a named LocalResource object.
Because the LocalResource object represents a directory, you can read from it and write to it by using the standard .NET file I/O classes. To determine the path to the local storage resource's directory, use the LocalResource.RootPath property. This property returns the full path to the local storage resource, including the named resource directory. For example, if your service is running in the development environment, the local storage resource is defined within your local file system, and the RootPath property would return a value similar to the following:
When your service is deployed to Windows Azure, the path to the local storage resource includes the deployment ID, and the RootPath property returns a value similar to the following:
Code running in a role instance can access a local storage resource that is defined for that role from the time the instance comes online to the time it is taken offline.