Intro

In the previous post I described how to create and delete Azure Storage tables. In this post I am going to show how to insert/replace/update/retrieve new entity into azure table.

Prerequisites

Refer to previous posts to get started with Azure Storage Table Service.

Code

First of all, you need to create an entity that can be used with Azure Table. It has to be inherited from TableEntity class.

In most of following examples I will use the following entity:

public class Profile : TableEntity
{
    public Profile()
    {
    }

    public Profile(string location, string id, string title, string description)
    {
        PartitionKey = location;
        RowKey = id;
        Title = title;
        Description = description;
    }

    public string Location
    {
        get { return PartitionKey; }
        set { PartitionKey = value; }
    }

    public string Id
    {
        get { return RowKey; }
        set { RowKey = value; }
    }

    public string Title { get; set; }

    public string Description { get; set; }

    public override string ToString()
    {
        return $"{Location}:{Id}: {Title}, {Description}";
    }
}

The most important properties are PartitionKey and RowKey. They are used by Azure to properly scale Azure Table storage, more information can be found at What PartitionKey and RowKey are for in Windows Azure Table Storage. An another important property is ETag, it will be described below.

The TableOperation class encapsulates a single operation to be performed against a table. Static factory methods are provided to create a TableOperation that will perform an Insert, Delete, Merge, Replace, Retrieve, InsertOrReplace, and InsertOrMerge operation on the given entity.

Consider the following code:

var entity = new Profile("AU", "EMP0001", "John Doe", "The first employee of the company");
table.Execute(TableOperation.Insert(entity)); 

This code will insert an entity with given PartitionKey and RowKey, if entity already exists the following exception will be thrown:

Additional information: The remote server returned an error: (409) Conflict.

If you don't want to throw an exception if entity already exists, you can use one of the methods described below.

Consider the following example:

table.Execute(TableOperation.InsertOrReplace(entity));

This code will insert an entity with given PartitionKey and RowKey if it doesn't exists, otherwise it will replace the entity completely. Thats it, if existing entity has different schema - it will be replaced completely, so no 'old' properties will be stored.

Consider the following example:

table.Execute(TableOperation.InsertOrMerge(entity));

This code will insert an entity with given PartitionKey and RowKey if it doesn't exists, otherwise it will merge new and existing properties. So if you have an 'old' entity that has more properties than a new one, the operation won't affect those properties. It will overwrite properties with the same name and leave everything else untouched.

You can also explicitly replace/merge/delete an entity. Consider the following example:

var entity = new Profile("AU", "EMP0001", "John Doe", "The first employee of the company");
table.Execute(TableOperation.Insert(entity));

entity.Title = "Jane Doe";
table.Execute(TableOperation.Replace(entity));

entity.Description = "Updated";
table.Execute(TableOperation.Merge(entity));

var result1 = table.Execute(TableOperation.Retrieve<Profile>("AU", "EMP0001"));
var profile1 = result1.Result as Profile;
Console.WriteLine(profile1);

table.Execute(TableOperation.Delete(profile1));

The code outputs following lines:

AU:EMP0001: Jane Doe, Updated

We can split this code into several blocks corredponding to specific actions. So this code does the following:

  • Inserts the entity
  • Replaces the entity - similar to InsertOrReplace, but throws exception if an entity doesn't exist
  • Merges the old and the new entity - similar to InsertOrMerge, but throws exception if an entity doesn't exist
  • Queries the entity by PartitionKey and RowKey
  • Deletes the entity

If you try to Replace/Merge/Delete entity that doesn't exist, one of following exceptions will be thrown:

Replace requires an ETag (which may be the '*' wildcard).

This exception indicates that your entity has invalid ETag. The ETag is used for concurrency. If you load a table entity and want to update it, you pass to update the ETag from when you loaded the value and it will update the entity only if that ETag matches what is stored. In our case we can set ETag to * and get the next exception:

The remote server returned an error: (404) Not Found.

This exceptions says that entity doesn't exist. This is what most people expect to see in the first place.

Summary

In this post I described basic operations that can be performed with a single entity and Azure Table. I provided a couple of code samples and explained meaning of some common exceptions. In the next post I am going to show how to perform batch operations on Azure Table storage.


;