The browse screen

The details screen

The edit screen

Excluding weekends

Dealing with holidays

Scenario

Creating the app

Limitations

Extracting strings

Detecting the user language and fallback

Retrieving the strings for the user language

Wrapping up

Wrapping up

Tweaking the compression encoder sample

    public override string ContentType
    {
        get { return innerEncoder.ContentType; }
    }

    public override string MediaType
    {
        get { return innerEncoder.MediaType; }
    }

    public override bool IsContentTypeSupported(string contentType)
    {
        return innerEncoder.IsContentTypeSupported(contentType);
    }

    public override T GetProperty()
    {
        return innerEncoder.GetProperty();
    }

    public override MessageVersion MessageVersion
    {
        get { return innerEncoder.MessageVersion; }
    }

    public override Message ReadMessage(ArraySegment buffer, BufferManager bufferManager, string contentType)
    {
        //Decompress the buffer
        ArraySegment decompressedBuffer = DecompressBuffer(buffer, bufferManager);
        //Use the inner encoder to decode the decompressed buffer
        Message returnMessage = innerEncoder.ReadMessage(decompressedBuffer, bufferManager, contentType);
        returnMessage.Properties.Encoder = this;
        return returnMessage;
    }

    public override Message ReadMessage(ArraySegment buffer, BufferManager bufferManager, string contentType)
    {
        ArraySegment decompressedBuffer = buffer;

        if (buffer.Count >= 3 && buffer.Array[buffer.Offset] == 0x1F &&
            buffer.Array[buffer.Offset + 1] == 0x8B && buffer.Array[buffer.Offset + 2] == 0x08)
        {
            //Decompress the buffer
            decompressedBuffer = DecompressBuffer(buffer, bufferManager);
        }

        //Use the inner encoder to decode the decompressed buffer
        Message returnMessage = innerEncoder.ReadMessage(decompressedBuffer, bufferManager, contentType);
        returnMessage.Properties.Encoder = this;
        return returnMessage;
    }

Adding an inspector to implement auto format selection and selective output compression

    public class CompressionAndFormatSelectionMessageInspector : IDispatchMessageInspector
    {
        static readonly Regex jsonContentTypes = new Regex(@"[application|text]\/json");
        static readonly Regex xmlContentTypes = new Regex(@"[application|text]\/xml");

        public object AfterReceiveRequest(ref Message request, IClientChannel channel, InstanceContext instanceContext)
        {
            object propObj;
            if (request.Properties.TryGetValue(HttpRequestMessageProperty.Name, out propObj))
            {
                var prop = (HttpRequestMessageProperty)propObj;
                var accept = prop.Headers[HttpRequestHeader.Accept];
                if (accept != null)
                {
                    if (jsonContentTypes.IsMatch(accept))
                    {
                        WebOperationContext.Current.OutgoingResponse.Format = WebMessageFormat.Json;
                    }
                    else if (xmlContentTypes.IsMatch(accept))
                    {
                        WebOperationContext.Current.OutgoingResponse.Format = WebMessageFormat.Xml;
                    }
                }
            }

            return null;
        }

        public void BeforeSendReply(ref Message reply, object correlationState)
        {
        }
    }

    public object AfterReceiveRequest(ref Message request, IClientChannel channel, InstanceContext instanceContext)
    {
        bool shouldCompressResponse = false;

        object propObj;
        if (request.Properties.TryGetValue(HttpRequestMessageProperty.Name, out propObj))
        {
            var prop = (HttpRequestMessageProperty)propObj;
            var accept = prop.Headers[HttpRequestHeader.Accept];
            if (accept != null)
            {
                if (jsonContentTypes.IsMatch(accept))
                {
                    WebOperationContext.Current.OutgoingResponse.Format = WebMessageFormat.Json;
                }
                else if (xmlContentTypes.IsMatch(accept))
                {
                    WebOperationContext.Current.OutgoingResponse.Format = WebMessageFormat.Xml;
                }
            }

            var acceptEncoding = prop.Headers[HttpRequestHeader.AcceptEncoding];
            if (acceptEncoding != null && acceptEncoding.Contains("gzip"))
            {
                shouldCompressResponse = true;
            }
        }

        return shouldCompressResponse;
    }

    public void BeforeSendReply(ref Message reply, object correlationState)
    {
        var useGzip = (bool)correlationState;
        if (useGzip)
        {
            // Add property to be used by encoder
            HttpResponseMessageProperty resp;
            object respObj;
            if (!reply.Properties.TryGetValue(HttpResponseMessageProperty.Name, out respObj))
            {
                resp = new HttpResponseMessageProperty();
                reply.Properties.Add(HttpResponseMessageProperty.Name, resp);
            }
            else
            {
                resp = (HttpResponseMessageProperty)respObj;
            }

            resp.Headers[HttpResponseHeader.ContentEncoding] = "gzip";
        }
    }

    public override ArraySegment WriteMessage(Message message, int maxMessageSize, BufferManager bufferManager, int messageOffset)
    {
        //Use the inner encoder to encode a Message into a buffered byte array
        ArraySegment buffer = innerEncoder.WriteMessage(message, maxMessageSize, bufferManager, 0);

        object respObj;
        if (message.Properties.TryGetValue(HttpResponseMessageProperty.Name, out respObj))
        {
            var resp = (HttpResponseMessageProperty)respObj;
            if (resp.Headers[HttpResponseHeader.ContentEncoding] == "gzip")
            {
                // Need to compress the message
                buffer = CompressBuffer(buffer, bufferManager, messageOffset);
            }
        }

        return buffer;
    }

Wrapping up

On the node.js version of mobile services, logging was done mostly via the node’s console object. In any of the server scripts you could call console.[log|warn|error] and when that script was executed you could go to the “logs” tab in the portal to see them. In the .NET backend you still have the same capabilities, but there are some new features and quirks which one should be aware to get the best logging experience in that new backend. Let’s go over them here.

Logging when running locally

This is a very simple example of logging in the .NET backend. If we write this controller class, we can use the Log property in the Services member of the TableController<T> class to write to the Azure logs.

When we publish the application to Azure and insert an item, we can see the log in the “logs” tab in the azure portal.

However, when we’re running the backend locally, there is no portal where we can see the logs, so where can we find them. As one user in Stack Overflow had this question, I imagine that others may have the same problem. And there’s nothing really fancy here – the logging is implemented (by default, see more advanced topics later) using the standard System.Diagnostics tracing system, so we can add a new listener in the web.config and send the log output to some file where you can read:

If we send the same request to the local service, we can now find it out the traces.

iisexpress.exe Information: 0 : Message='[PostItem] Inserting new item: 01234567-89ab-cdef-0123-456789abcdef-1', Id=00000000-0000-0000-0000-000000000000, Category='PostItem'

Another alternative, if you’re running the local .NET backend under the debugger, you can look at the “Output” window, selecting “Show output from: Debug”, and the traces will be shown in the window. If that’s the case you don’t even need to add a trace listener, as when running under the debugger VS will add one listener by default that writes to its output/debug window. There will be some noise on other information which is traced to the debug window, but that may be an acceptable solution as well.

The traces does not have the same format as we find in the portal, but that’s a quick way to get the information you want.

Customizing traces

But what if you really want a better formatted traces? Not a problem. The .NET backend uses the same system as its underlying framework, ASP.NET Web API. All traces are written via the ITraceWriter interface, and you can supply your own implementation of that interface, like in the code below, which uses a format very similar to the one displayed in the portal. The “category” parameter by default has the name of the member (typically method or property) where the log method was called, but it can be customized for anything that makes sense for your application.

And to use it we can replace the trace writer service with our own implementation in the HttpConfiguration object returned by the ServiceConfig.Initialize method.

The document Tracing in ASP.NET Web API has a good introduction on the tracing system used by Web API (and the .NET backend of the mobile service). Now, everything works fine when we run locally, but if we publish the service to Azure and invoke the operations in the controller again, we won’t see the traces in the portal anymore. The problem is that while we’re tracing to the System.Diagnostic subsystem, that is not hooked up to the tracing in the service running in Azure. We can fix that by passing the original trace writer (which can trace within Azure) to our trace writer implementation:

And when creating our trace writer we can pass the original writer if the service is running in Azure (which you can access via the extension method GetIsHosted – you’ll need to add a "using System.Web.Http" statement if you don’t have already to see that method).

Notice that for the case of a better local logging you could also only replace the trace writer if the service was running locally (i.e., if it was not hosted). But that organization will be useful in the next section.

Changing logs destination

Looking at the traces in the portal is fine during development, but as the service goes into production and if your mobile application is successful, you can expect thousands of traces being generated, and going through them via the portal isn’t the ideal way to analyze your logs. But since we can own completely the logging implementation, nothing prevents us from redirecting the logs to some external source – for example, table storage, where you can fetch and analyze them easier with several of the existing tools. Let’s change our trace listener implementation to send the logs to a table in Azure Storage if the service is running in the cloud.

You’ll need to add a reference to the “Windows Azure Storage” package if you haven’t done it yet to be able to use the classes shown in the code above. The TableTraceRecord class is defined as a subclass of TableEntity, which is required to insert items into the tables. In this example I’m using the timestamp as the row key to make it easier to sort based on the trace order (and adding a random set of characters to disambiguate in case multiple trace requests come at the exact same instant).

We now need to pass the connection string and mobile service name to the trace writer class. The recommended way to store the connection string is via the app settings, so I’ll add the connection string fro my account there:

And on the Register method we retrieve the values we need from the application settings.

Now when the trace is executed, it will write to the table storage.

More logging please!

So far we’re looking at how to look at the logs which our application writes out. But the .NET backend also exposes other kinds of logs which you can see as well. When we’re initializing the service configuration, we can pass a set of configuration options. One of them is the list of trace categories which are excluded from the traces. By default, internal traces are excluded, but we can remove those by clearing the ExcludedTraceCategories list in the config options passed to the initializer, as shown below.

Try it out – you’ll see more information about the inner workings of the backend. Definitely some information that the majority of the users won’t need, but a good way to get a better view of what’s happening behind the scenes.

Wrapping up

I hope this post will help you understand how to better use the logging subsystems in the .NET backend for mobile services. As usual, feel free to submit questions or comments to this post, the MSDN forums or contact us via Twitter @AzureMobile.

One of the advantages of the .NET backend for Azure Mobile Services is that it has out-of-the-box support for multiple data storages, not only SQL Azure. In the node.js runtime you could bypass the SQL operations and use some other storage option (as in this post by Chris Risner for Azure Table Storage), but it’s not a built-in functionality and you’d need to write a lot of code yourself. With the .NET runtime, a lot of the support is built-in, and there’s no need to create a “dummy” table just to have the requests to it redirected. In this post I’ll talk a little about the MongoDB support, and how we can create tables for which the CRUD operations are directed to a MongoDB collection.

Database setup

If you already have a MongoDB account with some collection created, feel free to skip this step (just make sure to take a note of your connection string, we’ll need it later). I’ll also use a collection named “orders” in this post – you don’t need to create one, the backend will create one if it doesn’t exist.

If you’re starting from scratch, for this post I’m using a Mongo Labs database, which we can get for free (for the sandboxed, developer edition) on the Azure portal. To create an account, you can go to the Azure portal, select “New” –> “Store”, and select the MongoLab add-on, where you can sign up for an account.

Once you have the account set up, click the “Connection info” button to copy the URI to connect to the database and save that value. The name you gave to the account is the name of the database, which we’ll also use later.

Now the Mongo database is set; we don’t need to create a collection, it will be created when we first try to access it via the backend.

Service setup

Since we don’t have a complete Visual Studio tooling story for non-Entity Framework backend types, let’s begin with an empty web project. We’ll start as I did on my previous post about creating a .NET backend from scratch, but instead of adding the Azure Mobile Services .NET Backend Entity Framework Extension NuGet package, we’ll add the Azure Mobile Services .NET Backend Mongo Extension package instead. Let’s also add the Microsoft.Owin.Host.SystemWeb package so that we’ll be able to run it locally for easier debugging.

With the two packages (and all of its dependencies) installed, let’s add the bootstrapper class by adding a WebApiConfig static class with a default Register method:

And also add a Global Application Class to invoke the bootstrapper when running locally:

Next let’s define our object model which we’ll store in the database collection. For this example, let’s define the order which contains a series of items.

Notice that, like on EF-backed data the models to be used in tables need to implement the ITableData interface. For the EF scenario we provide the EntityData base class which can be used, and similarly for the MongoDB case we provide the DocumentData class which implements that interface, leaving the model class to define the domain-specific properties only.

Defining the table

Tables for MongoDB-backed data are really similar to the EF-based ones. The operations can be implemented exactly like in that scenario, except that we need a new domain manager implementation, for which we can use the MongoDomainManager class which comes with the Azure Mobile Services .NET Backend Mongo Extension NuGet package. Notice that you can always use the types from the MongoDB driver (or any other Mongo client) directly to implement the operations, but for common scenarios, the base class TableController<T> provides the implementation necessary.

The first parameter in the MongoDomainManager constructor is the name of an element in the <connectionStrings> section in the configuration which contains the actual connection string for the database (we may add an option to pass the actual connection string to the constructor later). If we add the appropriate section to the web.config file (use the connection string you got from the Azure portal):

We should be able to run the project now. If we press CTRL+F5 the service should start running.

Testing the service

To test the service, let’s fire up Fiddler to send some requests to the service. First, let’s see what we GET from it:

GET http://localhost:54524/tables/order HTTP/1.1 
User-Agent: Fiddler 
Host: localhost:54524 

=-=-=-=-=-=-=-=-=-

HTTP/1.1 200 OK 
Cache-Control: no-cache 
Pragma: no-cache 
Content-Length: 2 
Content-Type: application/json; charset=utf-8 
Expires: 0 
Server: Microsoft-IIS/8.0 
X-Powered-By: ASP.NET 
Date: Mon, 14 Apr 2014 15:43:31 GMT 

[]

Nothing unexpected here (unless you already had an “orders” collection in your database). Let’s add some orders to our collection:

POST http://localhost:54524/tables/order HTTP/1.1
User-Agent: Fiddler
Host: localhost:54524
Content-Length: 211
Content-Type: application/json

{
    "client":"John Doe",
    "orderDate":"2014-04-13T00:00:00Z",
    "items":[
        { "name": "bread", "quantity": 1, "price": 1.99 },
        { "name": "milk", "quantity": 2, "price": 2.99 }
    ]
}

=-=-=-=-=-=-=-=-=-

HTTP/1.1 200 OK
Content-Length: 383
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/8.0
X-Powered-By: ASP.NET
Date: Mon, 14 Apr 2014 15:53:13 GMT

{
  "orderDate": "2014-04-13T00:00:00Z",
  "client": "John Doe",
  "items": [
    {
      "name": "bread",
      "quantity": 1.0,
      "price": 1.99
    },
    {
      "name": "milk",
      "quantity": 2.0,
      "price": 2.99
    }
  ],
  "id": "534c0469f76e1e10c4703c2b",
  "__createdAt": "2014-04-14T15:53:12.982Z",
  "__updatedAt": "2014-04-14T15:53:12.982Z"
}

And one more

POST http://localhost:54524/tables/order HTTP/1.1
User-Agent: Fiddler
Host: localhost:54524
Content-Length: 216
Content-Type: application/json

{
    "client":"Jane Roe",
    "orderDate":"2014-02-22T00:00:00Z",
    "items":[
        { "name": "nails", "quantity": 100, "price": 3.50 },
        { "name": "hammer", "quantity": 1, "price": 12.34 }
    ]
}

=-=-=-=-=-=-=-=-=-

HTTP/1.1 200 OK
Content-Length: 387
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/8.0
X-Powered-By: ASP.NET
Date: Mon, 14 Apr 2014 15:53:21 GMT

{
  "orderDate": "2014-02-22T00:00:00Z",
  "client": "Jane Roe",
  "items": [
    {
      "name": "nails",
      "quantity": 100.0,
      "price": 3.5
    },
    {
      "name": "hammer",
      "quantity": 1.0,
      "price": 12.34
    }
  ],
  "id": "534c0471f76e1e10c4703c2c",
  "__createdAt": "2014-04-14T15:53:21.557Z",
  "__updatedAt": "2014-04-14T15:53:21.557Z"
}

Now we can try to resend the GET request to see what we've got:

GET http://localhost:54524/tables/order HTTP/1.1 
User-Agent: Fiddler 
Host: localhost:54524 

=-=-=-=-=-=-=-=-=-

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 239
Content-Type: application/json; charset=utf-8
Expires: 0
Server: Microsoft-IIS/8.0
X-Powered-By: ASP.NET
Date: Mon, 14 Apr 2014 15:55:12 GMT

[
  {
    "id": "534c0469f76e1e10c4703c2b",
    "client": "John Doe",
    "orderDate": "2014-04-13T00:00:00Z"
  },
  {
    "id": "534c0471f76e1e10c4703c2c",
    "client": "Jane Roe",
    "orderDate": "2014-02-22T00:00:00Z"
  }
]

We got the items which we added, but we don’t get the complex property (items) in the object. The issue we have here is that the return type of the operation (IQueryable<Order>) only returns complex properties if the client explicitly asks for it (by passing the $expand=<propertyName> query string parameter). Having the method return a queryable object is useful because it also adds the additional filtering and ordering capabilities (via $filter and $orderby parameters, respectively), so we must make a decision on whether to continue using the queryable and pass the $expand to retrieve the items, or move to another return type. For the latter, the change is fairly small:

For the former, there are some alternatives. The easier (on the server) is to make the client send the $expand header, and nothing needs to be changed in the server. In this case, we can send the request and get the full document back:

GET http://localhost:54524/tables/order?$expand=items HTTP/1.1 
User-Agent: Fiddler 
Host: localhost:54524 

=-=-=-=-=-=-=-=-=-

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 663
Content-Type: application/json; charset=utf-8
Expires: 0
Server: Microsoft-IIS/8.0
X-Powered-By: ASP.NET
Date: Mon, 14 Apr 2014 17:52:26 GMT

[
  {
    "id": "534c0469f76e1e10c4703c2b",
    "client": "John Doe",
    "orderDate": "2014-04-13T00:00:00Z",
    "items": [
      {
        "name": "bread",
        "quantity": 1.0,
        "price": 1.99
      },
      {
        "name": "milk",
        "quantity": 2.0,
        "price": 2.99
      }
    ]
  },
  {
    "id": "534c0471f76e1e10c4703c2c",
    "client": "Jane Roe",
    "orderDate": "2014-02-22T00:00:00Z",
    "items": [
      {
        "name": "nails",
        "quantity": 100.0,
        "price": 3.5
      },
      {
        "name": "hammer",
        "quantity": 1.0,
        "price": 12.34
      }
    ]
  }
]

Another alternative is to use an action filter which will change the incoming requests to always add the expand query parameter. One possible implementation is given below:

And if we decorate our method with that attribute

We can send requests which use other queryable attributes while still having the expanded items in our order

GET http://localhost:54524/tables/order?$orderby=client HTTP/1.1 
User-Agent: Fiddler 
Host: localhost:54524 

=-=-=-=-=-=-=-=-=-
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 663
Content-Type: application/json; charset=utf-8
Expires: 0
Server: Microsoft-IIS/8.0
X-Powered-By: ASP.NET
Date: Mon, 14 Apr 2014 18:37:27 GMT

[
  {
    "id": "534c0471f76e1e10c4703c2c",
    "client": "Jane Roe",
    "orderDate": "2014-02-22T00:00:00Z",
    "items": [
      {
        "name": "nails",
        "quantity": 100.0,
        "price": 3.5
      },
      {
        "name": "hammer",
        "quantity": 1.0,
        "price": 12.34
      }
    ]
  },
  {
    "id": "534c0469f76e1e10c4703c2b",
    "client": "John Doe",
    "orderDate": "2014-04-13T00:00:00Z",
    "items": [
      {
        "name": "bread",
        "quantity": 1.0,
        "price": 1.99
      },
      {
        "name": "milk",
        "quantity": 2.0,
        "price": 2.99
      }
    ]
  }
]

Deployment

Now that the service runs locally correctly, we’re ready to publish to Azure. After downloading the publishing profile from the portal, right-click the project in VS and select “publish”, the service will be live. And if we fire up Fiddler again, we should be able to retrieve our two orders straight from Azure:

GET http://blog20140413.azure-mobile.net/tables/order HTTP/1.1
User-Agent: Fiddler
Host: blog20140413.azure-mobile.net

=-=-=-=-=-=-=-=-=-
HTTP/1.1 500 Internal Server Error
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 43
Content-Type: application/json; charset=utf-8
Expires: 0
Server: Microsoft-IIS/8.0
X-Powered-By: ASP.NET
Date: Mon, 14 Apr 2014 18:50:22 GMT

{
  "message": "An error has occurred."
}

Something is wrong. By default the runtime doesn’t return any error details (for security purposes), so we can go to the portal, in the logs tab, to see what is going on, and the error is listed there:

Exception=System.ArgumentException: No connection string named 'mongodb' could be found in the service configuration.
   at Microsoft.WindowsAzure.Mobile.Service.MongoDomainManager`1.GetMongoContext(String connectionStringName)
   at System.Collections.Concurrent.ConcurrentDictionary`2.GetOrAdd(TKey key, Func`2 valueFactory)
   at Microsoft.WindowsAzure.Mobile.Service.MongoDomainManager`1..ctor(String connectionStringName, String databaseName, String collectionName, HttpRequestMessage request, ApiServices services)
   at MongoDbOnNetBackend.OrderController.Initialize(HttpControllerContext controllerContext)
   at System.Web.Http.ApiController.ExecuteAsync(HttpControllerContext controllerContext, CancellationToken cancellationToken)
   at System.Web.Http.Dispatcher.HttpControllerDispatcher.SendAsyncCore(HttpRequestMessage request, CancellationToken cancellationToken)
   at System.Web.Http.Dispatcher.HttpControllerDispatcher.d__0.MoveNext(), Id=6133b3eb-9851-41d1-9e17-38f196e41f6b, Category='App.Request'

The problem is that the local web.config file which we were using when running the service locally is not used when the service is running in the cloud. We need to define the connection string some other way. Unfortunately due to a current bug we have there’s no easy way to define the connection string (it should be easily done in the portal, but this is not there yet), so we have to work around it for now.

To do that, first go to the “configure” tab of the mobile service in the portal, and add a new app setting whose value is the connection string which we had defined in the web.config file before:

And when initializing the table controller, we change the connection strings in the service settings based on that value which we can read from the app settings.

And now when we publish it again we should be able to consume the table from Azure.

GET http://blog20140413.azure-mobile.net/tables/order HTTP/1.1
User-Agent: Fiddler
Host: blog20140413.azure-mobile.net
x-zumo-application: cOFQkbaAmffuVRBJRpYDKHbNHbtDYG97

=-=-=-=-=-=-=-=-=-
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 663
Content-Type: application/json; charset=utf-8
Expires: 0
Server: Microsoft-IIS/8.0
X-Powered-By: ASP.NET
Date: Mon, 14 Apr 2014 19:21:11 GMT

[
  {
    "id": "534c0469f76e1e10c4703c2b",
    "client": "John Doe",
    "orderDate": "2014-04-13T00:00:00Z",
    "items": [
      {
        "name": "bread",
        "quantity": 1.0,
        "price": 1.99
      },
      {
        "name": "milk",
        "quantity": 2.0,
        "price": 2.99
      }
    ]
  },
  {
    "id": "534c0471f76e1e10c4703c2c",
    "client": "Jane Roe",
    "orderDate": "2014-02-22T00:00:00Z",
    "items": [
      {
        "name": "nails",
        "quantity": 100.0,
        "price": 3.5
      },
      {
        "name": "hammer",
        "quantity": 1.0,
        "price": 12.34
      }
    ]
  }
]

Just a final note on this request – when the service is running locally, there’s no authentication by default so our request didn’t need to send any keys. To send the request to the server running on Azure, we need to specify the application key (the default authentication level) in the “x-zumo-application” header.

Wrapping up

The .NET backend for Azure Mobile Services offers a selection of storage providers for the “table” abstraction. Since most examples out there deal with the Entity Framework (SQL Server) based option, hopefully this post will give you some information on how to use our MongoDB provider for storing data. And as usual, we welcome comments and suggestions in this blog, in our MSDN forums or via twitter @AzureMobile.

When learning a new feature I often like to understand the minimum pieces necessary to get it running. In the case of the .NET backend of azure mobile services, that would mean the smallest number steps required to go from an empty project to a running mobile service – no additional tooling required. Currently the item and project templates required for the mobile services backend require the VS 2013 Update 2 Release Candidate, and many people (myself included) are wary of installing non-RTM versions of VS updates, so here’s a guide on how to create a .NET backend project without those.

Set up

The minimum project which we can create for a service backend is an empty ASP.NET application (on VS 2013, select the New Project –> Web –> ASP.NET Web Application, then select Empty). At that point we’ll won’t have anything at all (except for an empty web.config file).

Now it’s time to add the reference to the .NET backend binaries. Right-click the project, select “Manage NuGet Packages…”, and search for “MobileServices”. There will be (as of today) 5 packages related to the backend, with three of them (Entity Framework Extension, Azure Storage Extension, Mongo Extension) defining extensions for specific storage providers. Let’s choose the entity framework one (Windows Azure Mobile Services .NET Backend Entity Framework Extension), and click “Install”. After being prompted to accept licenses, NuGet will install the necessary packages (there is currently a bug that a “conflict file” dialog is shown; you can safely ignore that dialog). And now we still have an empty project, with the difference that the web.config has a few more entries which we can ignore.

Defining the model

Now let’s add a class to represent the model (entity) we’ll want to expose. For simplicity sake, I’ll use the old TodoItem class. To expose a class as a table in the .NET backend, it needs to implement the ITableData interface, but the entity framework extension NuGet package defines the EntityData class which we can use as a base type.

Now we need a context to hook up Entity Framework with our model types (or single type in this case). When you create a new mobile service, a new schema is defined in the associated database, and the service is granted access to that schema. In our implementation of the context we need to tell it that we use that schema (you can also use databases on different schemas, or even a completely different database, and that is a topic for another post). Normally we’d override the OnModelCreating method on the DbContext class:

But since this would be done many times, we provide one class derived from DbContext – EntityContext – which does that automatically, so we can implement our context fairly concisely:

The EntityContext class also “teaches” EF how to use the TableColumnAttribute attribute, which you can use to customize the type of the columns created in your tables. And now that the context is created, we can define the table controller. This code is pretty much boilerplate for exposing entities as tables, and if you have the latest tooling (currently with the VS 2013 Update 2 RC) you can do that by using the item template.

That’s it, the service is ready to be built and deployed. If you publish it to the mobile service (after downloading the publishing profile from the portal), you should be able to send requests to the table.

Configuring the service

The mobile service is now running, but we haven’t configured anything on how we want it to run – so the mobile service used a default bootstrapper, which initializes the service configuration with default options. If you want to change any configuration settings, define additional routes, access other extensibility points, define mapping between entity objects and DTOs, among other initialization tasks, you need to define a method to be called on startup. My colleague Henrik described the configuration in details on this blog post so I won’t cover it here, and let’s just define a WebApiConfig class to change something in our project, which calls the Initialize method on the ServiceConfig class, and changes a setting in the JSON.NET serializer.

If you now publish the project to the server again and send a request to the server, you’ll see that the JSON responses are now indented.

Running locally

One of the great features of the .NET backend for Azure Mobile Services is the ability to test the service locally prior to deploying. But at this point, while your service can be run in the cloud, if you try to run it locally it won’t do anything (it will show an error page). There are two things which we still need to do: hook up the .NET backend to the ASP.NET pipeline running in IIS Express, and call the bootstrapper code needs to be called.

For the first part can be done by installing another NuGet package, Microsoft.Owin.Host.SystemWeb, to the project. The .NET backend is implemented using the OWIN framework, and that NuGet adds a bridge between the OWIN adapter and System.Web, which is used in IIS. No code is needed in this step.

For the second part, we need to tell the application to invoke the WebApiConfig.Register method. To do that, add a new Global Application Class (global.asax). You can remove all methods except Application_Start from the generated class. In the app start, call that method, as shown below.

If you now press F5, the project will run (i.e., the “This mobile service is up and running” page will appear on your browser). But when you try to invoke any operation in the table controller, you’ll get an internal server error. Looking at the response body it will show the following error:

System.ArgumentNullException: Value cannot be null. Parameter name: schema
   at Microsoft.WindowsAzure.Mobile.Service.EntityContext..ctor(String schema)
   at WebApplication9.MyContext..ctor(String schema) in c:\…\WebApplication9\WebApplication9\MyContext.cs:line 17
   at WebApplication9.TodoItemController.Initialize(HttpControllerContext controllerContext) in c:\…\WebApplication9\WebApplication9\TodoItemController.cs:line 18
   at System.Web.Http.ApiController.ExecuteAsync(HttpControllerContext controllerContext, CancellationToken cancellationToken)
   at System.Web.Http.Dispatcher.HttpControllerDispatcher.SendAsyncCore(HttpRequestMessage request, CancellationToken cancellationToken)
   at System.Web.Http.Dispatcher.HttpControllerDispatcher.d__0.MoveNext()"  

The parameter which we passed to the context constructor (this.Services.Settings.Schema) is null, which is causing this error. What is missing are configuration settings which the service adds when the backend is running on the cloud, but for local running they need to be defined in web.config. The schema can be defined with the MS_TableSchema app setting, but if that value is not defined it will default to the mobile service name (defined by the MS_MobileServiceName app setting). Another thing which we need to define is the connection string for the database used by the Entity Framework context. The EntityContext class which we used to define our DB context uses the connection setting named MS_TableConnectionString by default, so we need to define it as well.

There are many other values which you can add to the app settings – you can check them out in the ServiceSettingsKeys class.

Wrapping up

I hope this post will give you not only a recipe for starting from scratch to create a mobile service backend (but if it does, great) but also explain a little more about how the .NET backend is hosted in the Azure Mobile Service. If you have any comments or questions, feel free to leave as comments in this post, ask a new question in our MSDN forums or contact us via twitter @AzureMobile.

New table types: IMobileServiceSyncTable and IMobileServiceSyncTable<T>

System.InvalidOperationException: SyncContext is not yet initialized.

The problem is that the SDK has no idea about where to store the local data. Before using any of the sync operations, we first need to initialize the synchronization context of the client so that those operations can start working.

The synchronization context

Defined table in the store
Initialized the sync context
Pending operations in the sync context queue: 0
Table: TodoItem
Inserted into local store: 9e61196d-55df-4869-8b30-4a4a6eb792f2
Pending operations in the sync context queue: 1
Inserted another item into the local store: c349b30d-d603-48db-8509-b2fd170f4499
Pending operations in the sync context queue: 2
Things to do Buy bread, Buy milk
Pending operations in the sync context queue: 2
Updated item: c349b30d-d603-48db-8509-b2fd170f4499
Pending operations in the sync context queue: 2

I talked about synchronization operations without introducing them. Let’s look at them now.

Push / pull / purge

Handling conflict errors

Advanced features

One more thing: the implementation of the local store uses the SQLite database, which is a x86/arm only binary. The project cannot be configured to “AnyCPU”, it needs to be configured to a specific architecture.

Wrapping up

In this release we introduced offline capabilities in the .NET SDK for Mobile Services. We released it as an alpha NuGet package so you can try and give us feedback on what works, what doesn’t and what we can improve. Please let us know in the comments, in our forum or via twitter @AzureMobile.