Skip to content


Subversion checkout URL

You can clone with
Download ZIP


vermorel edited this page · 5 revisions

Tutorial to get started with Lokad.Cloud

Hands-on tutorial for Lokad.Cloud

Is Lokad.Cloud for you?

Lokad.Cloud is an an O/C mapper (object to cloud) as well as a cloud execution framework. In short, it's a set of libraries and apps that aims to improve your productivity while developing on the cloud. The O/C abstracts most of the nitty-gritty details related to the cloud storage, while the execution framework facilitate intensive parallelization of background processes.

Pretty much any Azure app (web or worker role) that interacts with the Azure Storage can benefit from the O/C mapper part of Lokad.Cloud. You can think of it as a super syntactic sugar sitting on top of Microsoft.WindowsAzure.StorageClient.dll.

Then, the execution framework part of the Lokad.Cloud is much more intrusive: it requires to really architecture your worker role around the Lokad.Cloud framework. This framework is primarily intended for rather intensive parallel processing, emphasizing dynamic auto-scaling along the way.

Big picture

Lokad.Cloud comes in two very distinct flavors:

  • an O/C mapper (object to cloud), simply put, a handy library to facilitate all your operations on the Azure Storage. The O/C mapper has a very limited impact on your app, it can be used with any .NET app from within or outside Windows Azure. All it takes is to add a single DLL to your .NET project, and you are good to go.
  • an execution framework, that let you define a set of services to be run in the !WorkerRole providing a lot build-in feature for basic stuff such as task scheduling, queue processing and app administration from a build-in web console. Contrary to the O/C mapper, the execution framework has a significant impact on the design of your app. We believe that this framework bring many benefits - like say ASP.NET MVC but for !WorkerRole - yet, like MVC, your app need to be designed on top of the framework to really benefit from the framework.

The package Lokad.Cloud itself comes basically in several parts:

  • a stand-alone library named Lokad.Cloud.Storage.dll (O/C mapper).
  • a library named Lokad.Cloud.Framework.dll (execution framework).
  • an Azure package named Lokad.Cloud.DeployWorker.cspkg (execution framework).
  • an Azure package named Lokad.Cloud.DeployConsole.cspkg (execution framework).

The O/C mapper is a stand-alone DLL while the execution framework is dependent on the O/C mapper.


In order to work with Lokad.Cloud, you need:

  • .NET 4.0,
  • Azure SDK v1.4
  • ASP.NET MVC 3 (for the web console only)

The O/C mapper

The O/C mapper is really straightforward, basically we try to do for the cloud storage, what O/R mappers are doing for relational storage.

The two sections below provides stand-alone code samples:

All it takes to get started with the O/C mapper is to add Lokad.Cloud.Storage.dll as reference to your project (and System.Runtime.Serialization.dll from the .NET Framework itself too), and the following code sample should run.

using System;
using System.Runtime.Serialization;
using Lokad.Cloud;
using Lokad.Cloud.Storage;

class Book
    public string Title { get; set; }

    public string Author { get; set; }

class Program
    static void Main(string[] args)
        // TODO: change your connection string here
        var providers = CloudStorage.ForAzureConnectionString(

        // 'books' is the name of the table
        var books = new CloudTable<Book>(providers.TableStorage, "books");

        var potterBook = new Book 
           { Author = "J. K. Rowling", Title = "Harry Potter" };

        var poemsBook = new Book 
           { Author = "John Keats", Title = "Complete Poems" };

        // inserting (or updating record in Table Storage)
                new CloudEntity<Book> {
                    PartitionKey = "UK", RowKey = "potter", Value = potterBook},
                new CloudEntity<Book> {
                    PartitionKey = "UK", RowKey = "poems", Value = poemsBook}

The O/C mapper is a stand-alone feature of Lokad.Cloud and can be used in any .NET app. In particular, the app does not have to be hosted in Windows Azure, as the Azure Storage can be remotely accessed from the internet.

The execution framework

Running a complex business logic in a WorkerRole ensuring a design both resilient and scalable is rather challenging. Lokad.Cloud is making this easier through an execution framework.

Lokad.Cloud introduces the notion of Cloud Service, pretty much as a cloud equivalent of the Windows Service that exists on a classical Windows OS. Those cloud services can be used to design scalable back-end architecture.

Once the Azure package is deployed, developing with Lokad.Cloud basically means adding three DLL references: Lokad.Cloud.Storage.dll, Lokad.Cloud.Framework.dll and Autofac.dll to your .NET project and then implementing a CloudService inheritor (base class found in the namespace Lokad.Cloud.Framework).

Lokad.Cloud Console Home

And that's pretty much it. The web administration console shipped with Lokad.Cloud as WebRole for Windows Azure let you import your newly created libraries (containing the CloudService implementations), as illustrated by the screenshot below.

Lokad.Cloud Console assemblies

Once the libraries are imported, Lokad.Cloud takes care of executing your cloud services, eventually logging exceptions thrown by your services.


Lokad.Cloud requires two Azure services:

  • an Azure Storage account.
  • an Azure Compute account.

Lokad.Cloud also requires a certificate for Azure management (see below).

You can open those accounts from the Windows Azure Developer Portal.

Certificate for Azure Self-Management

Lokad.Cloud leverages the Azure Management API for self-management in order to get more information about its current deployment and to adapt its topology on demand. The Azure Management API requires a X509 certificate for authentication but accepts self-signed certificates you can quickly generate yourself.

To generate a certificate you can use the following command (all on a single line). You can then use the certmgr tool to export a certificate with a private key in PKCS12 format e.g. to AzureManagementPrivate.pfx

makecert -r -pe -a sha1 -n "CN=Azure Management" -ss My -len 2048
-sp "Microsoft Enhanced RSA and AES Cryptographic Provider" -sy 24 AzureManagementPublic.cer

Note : makecert is included in Microsoft Windows SDK

In the Azure Portal when navigating to your hosted service you'll see a section Certificates at the bottom of the page where you can upload your private (pfx) certificate. Once uploaded, the page will print the certificate's thumbprint which we will need below to enable the certificate for Lokad.Cloud.

If you'd like to enable Self-Management for Lokad.Cloud (recommended) then you'll also have to add your public (cer) certificate to your Azure account's API Certificates. You can do this in the Azure Portal on the Account tab on top of the page.

See also the very detailed post of Chris Auld about certificates on Windows Azure.

Deploying Lokad.Cloud

First, you need to download the latest version of Lokad.Cloud from download page.

The ZIP archive contains two Azure packages:

  • Lokad.Cloud.DeployWorker.cspkg, a worker role for the executing environment itself.
  • Lokad.Cloud.DeployConsole.cspkg, an web administration console, that will let you deploy your assemblies (among others).

At this point, you need extract the files from the ZIP archive and edit ServiceConfiguration.cscfg to fit your own settings (it's just a small XML file, Notepad is sufficient for that).

Those settings are basically the usual Azure Storage settings (including the account name and the storage endpoints). In addition, !WebRole settings include an OpenID entry where you can list OpenID logins. Those logins will be granted administrative rights to the Lokad.Cloud Web Administration Console. If you don't already an OpenID account, getting one is quick, easy and gratis, just go to

The settings also include a Certificates section for both roles, with a single entry named SelfManagement. Update the thumbprint attribute of this entry to the certificate thumbprint mentioned above. To enable Self-Management for Lokad.Cloud (optional) also set the value of the SelfManagementCertificateThumbprint setting in both roles to the same thumbprint, and set the value of SelfManagementSubscriptionId to your Azure account subscription Id as printed in the Azure Portal on the Account tab.

Once the configuration file has been set with your own settings, you are ready to deploy on Azure. It's done the usual way, no special requirements here.

Windows Azure Dev Portal

The Lokad.Cloud web console comes as an ExtraSmall VM on Windows Azure. It can also be used to administrate multiple Lokad.Cloud worker role services.

Building your first queue service

An application build on top of Lokad.Cloud gets typically divided in two parts:

  • the front-end, typically a webrole, actually feeding the back-end with workload. Ex: in the case of Lokad, companies are uploading loads of data to be forecasted to our front-end. The front-end interacts with Lokad.Cloud by populating queues through Lokad.Cloud.Storage.dll.
  • the back-end, typically a set of CloudService implementations, also relying on Lokad.Cloud.Storage.dll but also on Lokad.Cloud.Framework.dll, that takes care of the bulk of the resource intensive operations. Ex: in the case of Lokad, the back-end deals with the actual forecasting computation.

The Lokad.Cloud package with a minimalistic sample named PingPong which can be downloaded with the sources of Lokad.Cloud.

The PingPong sample comes in two parts:

  • a front-end, just a console application named PingPongClient.exe, that populates a queue named ping with a few items. Once the items have been pushed, the app just keeps pinging the queue named pong for items.
  • a back-end, a single library named PingPongService.dll, that contains a single service retrieving items from the ping queue and putting them to the pong queue.

As you can see below, the actual implementation of the cloud service PingPong is really straightforward.

using System.Collections.Generic;
using Lokad.Cloud.Framework;

namespace PingPong
  /// <summary>Retrieving messages from 'ping' and put them in 'pong'.</summary>
  [QueueServiceSettings(AutoStart = true, QueueName = "ping")]
  public class PingPongService : QueueService<double>
    protected override void Start(double x)
      var y = x * x; // square operation
      Put(y, "pong");

In order to run the PingPong sample, you need to

  • Deploy Lokad.Cloud as detailed in the previous section.
  • Build the PingPong sample.
  • Zip the library PingPongService.dll
  • Deploy the ZIP on Azure through the web admin console shipped with Lokad.Cloud.
  • Update the configuration file of PingPongClient.exe with your own settings.
  • Run PingPongClient.exe and observe the items being processed by the service.

At this point, you should be ready to build and run your own cloud services on top of Lokad.Cloud. Do not hesitate to drop us feedback.

Something went wrong with that request. Please try again.