Windows Azure Storage Extensions

Windows Azure Storage Extensions is a .NET library aimed at managing and querying entities from Azure Storage Tables.

It's built on top of the Azure .NET SDK, provides async interfaces (Task-based Asynchronous Pattern) and LINQ to Azure Table queries via TableSet context by using POCO entities.

Table Of Contents

• Features
• Download
• Dependencies
• Code Samples
• Sponsors

Features

Attribute Mapping

POCO properties and fields should be marked by one or both of PartitionKey and RowKey attributes for defining composite table key. Also can be used Timestamp, ETag, Property and Ignore attributes.

Fluent Mapping

Fluent mapping is the namesake mapping style that we use as an alternative to the AttributeMapping. It's a fluent interface that allows you to map your entities completely in code, with all the compile-time safety and refactorability that brings.

EntityTypeMap class

EntityTypeMap class is the basis of all your mappings, you derive from this to map anything.

public class AddressMap : EntityTypeMap<Address>
{
  public AddressMap()
  {
      this.PartitionKey(p => p.CountryCode)
          .RowKey(p => p.Id)
          .Ignore(p => c.Country);
  }
}

You map your entities properties inside the constructor.

Syntax note: Every mapping inside a EntityTypeMap is built using lambda expressions, which allow us to reference the properties on your entities without sacrificing compile-time safety. The lambdas typically take the form of x => x.Property. The x on the left is the parameter declaration, which will implicitly be of the same type as the entity being mapped, while the x.Property is accessing a property on your entity (coincidentally called "Property" in this case).

Once you've declared your EntityTypeMap you're going to need to map the properties on your entity. There are several methods available that map your properties in different ways, and each one of those is a chainable method that you can use to customise the individual mapping.

PartitionKey and RowKey

Every mapping requires an PartitionKey and RowKey of some kind.

The PartitionKey is mapped using the PartitionKey method, which takes a lambda expression that accesses the property on your entity that will be used for the PartitionKey.

PartitionKey(x => x.MyPartitionKeyProperty);

The PartitionKey is mapped using the RowKey method, which takes a lambda expression that accesses the property on your entity that will be used for the PartitionKey.

RowKey(x => x.MyRowKeyProperty);

Ignore

If you need to ignore a property by using the Ignore method, which takes a lambda expression that accesses the property on your entity that will ignored by the serializer.

Ignore(x => x.MyPropertyToIgnore);

ETag and Timestamp

The ETag property is mapped using the methods ETag, which takes a lambda expression that accesses the property on your entity that will be mapped.

ETag(x => x.MyETagProperty);

The Timestamp property is mapped using the methods Timestamp, which takes a lambda expression that accesses the property on your entity that will be mapped.

Timestamp(x => x.MyTimestampProperty);

Register custom mapping assembly

The TableEntityConverter class will try to find the mapping classes for your entities on the same assembly of the entitie, if you are using a different assembly for mappings classes you'll need to register this assembly by using the RegisterAssembly method from class EntityTypeMap. ATTENTION: this method just need to be called once and before instantiating the TableSet class. Below there is a sample of how we call the

EntityTypeMap.RegisterAssembly(typeof(MyEntity).Assembly)

Entities Management

Generic TableSet context provides a synchronous & asynchronous (TAP) methods for managing entities:

• Synchronous: Add, AddOrUpdate, Update and Remove.
• Asynchronous: AddAsync, AddOrUpdateAsync, UpdateAsync and RemoveAsync.

To avoid restrictions of group operations in Azure Storage all entities sorted by partition keys and merged into groups by 100 entities. Execution of requests with such batch operations can be configured via TableSet's ExecutionMode property. Allowed values:

• Sequential
• Parallel

Default ExecutionMode is Sequential.

LINQ Queries

TableSet context implements IQueryable interface for using LINQ Expressions. Provider supports next synchronous LINQ methods:

• First
• FirstOrDefault
• Single
• SingleOrDefault
• Take
• Where

To utilize filtering capabilities of string properties it supports:

• Compare
• CompareTo
• CompareOrdinal

Also you can use Contains method. In this case query statement for each collection's item will be joined by using OData or operator.

NOTE: For creating a custom queries you should take a look at next article: Mixing LINQ Providers and LINQ to Objects.

Asynchronous LINQ Queries

In addition TableSet can be used for asynchronous queries powered by LINQ extensions (TAP) in EF 6 Async style.

Available methods:

• FirstAsync
• FirstOrDefaultAsync
• SingleAsync
• SingleOrDefaultAsync
• TakeAsync
• ToListAsync

LINQ Projections

LINQ Projections supported with a limitation - projection class should be a reference type.

TAP-based Extensions

Library contains TAP-based extensions for following Azure Storage Library classes:

• CloudBlobClient
• CloudBlobContainer
• CloudTableClient
• CloudTable

To use it just add Async postfix to synchronous method name for instance:

blobs = cloudBlobContainer.ListBlobs();
blobs = await cloudBlobContainer.ListBlobsAsync();

Task Cancellation

All of TAP-based methods accepts optional CancellationToken parameter for Task Cancellation.

Download

Via NuGet

To install library by using Windows Azure Storage Extensions nuget package execute next command:

Install-Package WindowsAzure.StorageExtensions

Via Git

To get the source code of the library via git just type:

git clone git://github.com/dtretyakov/WindowsAzure.git
cd ./WindowsAzure

Dependencies

Storage Extensions requires .NET Framework 4.0 or higher and WindowsAzure.Storage nuget package.

Code Samples

• Declaring a new POCO class and using attribute mapping:

public sealed class Country
{
    [PartitionKey]
    public string Continent { get; set; }
    [RowKey]
    public string Name { get; set; }
    public long Population { get; set; }
    public double Area { get; set; }
    public DateTime Formed { get; set; }
}

• Declaring a new POCO class and using fluent mapping:

public sealed class Country
{
    public string Continent { get; set; }
    public string Name { get; set; }
    public long Population { get; set; }
    public double Area { get; set; }
    public DateTime Formed { get; set; }
}

public class CountryMapping : WindowsAzure.Table.EntityConverters.TypeData.EntityTypeMap<Country>
{
    public CountryMapping() {
        this.PartitionKey(p => p.Continent)
            .RowKey(p => p.Name);
    }
}

• Creating a new table context:

var storageAccount = CloudStorageAccount.DevelopmentStorageAccount;
var tableClient = storageAccount.CreateCloudTableClient();

var countryTable = new TableSet<Country>(tableClient);

• Adding a new entity:

var resultSync = countryTable.Add(country);
var resultAsync = await countryTable.AddAsync(country);

• Updating an entity:

resultSync.Area += 333333;
resultSync = countryTable.Update(resultSync);

resultAsync.Population *= 2;
resultAsync = await countryTable.UpdateAsync(resultAsync);

• Removing entities:

countryTable.Remove(resultSync);
await countryTable.RemoveAsync(resultAsync);

• Querying entities:

var query = countryTable.Where(
        p => p.Formed > new DateTime(1950, 1, 1) &&
             (p.PresidentsCount < 10 ||
              p.Population < 10000000 && p.PresidentsCount > 10 && p.IsExists));

resultsSync = query.ToList();
resultsAsync = await query.ToListAsync();

• Using LINQ projections:

var projection = from country in countryTable
                 where country.Area > 400000
                 select new { country.Continent, country.Name };

var result = projection.ToList();
result = await projection.ToListAsync();

• Using Contains in the LINQ query:

var countryNames = new List<string> { "Germany", "Finland" };
var countries = countryTable.Where(p => countryNames.Contains(p.Name)).ToList();

Contributors

Great thanks to all of projects contributors.

• Dmitry Tretyakov for project idea.
• Timothy Makarov for performance optimizations.
• Gabriel Marquez for Fluent API mapping.
• Sebastian Betzin for additional TableSet methods.
• Tom Dietrich for his contributions.
• And Community for a valuable feedback.

See complete list of project contributors.

We appreciate all kinds of feedback, so please feel free to send a PR or write an issue.