At the time of writing, Mobile Services is still in preview, so I believe that you have to “request” access to it. But as soon as you have, you get a new icon in your menu in the Azure management portal, which is all cool. But what is Windows Azure Mobile Services (Mobile Services from now on)?
Well, Mobile Services is basically a “layer” on top of Microsofts cloud offering. Initially, it is a great abstraction for SQL Databases, but the idea, as I have understood it at least, is that it will grow as the amount of Azure services expand, giving the users a simple API to work against. And in doing so, will make us as developers much more productive. But as I said, today, it is basically a very nifty layer on top of SQL Databases. However, that layer is really cool, simple to work with, and supports very rapid development.
I would say that Mobile Services is a simple backend as a service, that works VERY well if you are building an “app”. And that is probably not too far off from what Microsoft sees it as either, at least if you consider the platforms they support at the moment, which is Windows Phone 8, Windows 8 Store Apps and iOS.
But that’s enough talk. Let’s have a look at how it works…
The first thing you need to do after signing up for the preview, is to create a new mobile service, which is done through the Azure Management Portal.
The first thing you need to do is to find a unique name for your service. This is pretty easy at the moment as it is still in preview… Next, you decide whether you want to use an existing SQL Database, or if you want to use a new one.
The cool thing here, is that Mobile Services will prefix all its tables, so you can just add it to an existing db if you want to. And if you go for a new one, you can still connect to it from any other environment and query the tables, or even add new ones. However, adding new ones, will NOT make them available to your Mobile Services client…
At the moment Mobile Services is only available in West and East US, but that will obviously change when the service goes live…
Next, you get to either select database and logins and stuff, or select the name of the database if you decide to create a new. In my case, I decided to create a new and go tthe below screen.
Once you have configured the database, and clicked the little “V”, it will take a couple of seconds, and then the portal will tell you that your service is ready. That’s it! A brand new backend up and running…
Ok, so where do you go from here? Well, it actually keeps being this simple… If you click the newly created Mobile Service, you will be met by a screen that tells you that your service was created. It also asks you what platform you want to work with. In my case, I will choose Windows Store. Beneath that, you get 2 choices, “Create a Windows Store app” or “Connect an existing Windows Store app”.
If you choose any of the other platforms, the options will be the same…but for that platform of course…
If you choose to create a new application, the portal will help you to create a table, and give you a VS2012 solution with a fully working application, and if you choose to connect an existing app, if will give you a code snippet to get Mobile Services working in your application (this is what I will be doing).
In either case, it also gives you links to download VS2012 Express as well as the Mobile Services SDK. In my case, I will use my regular VS2012, but I still need to download the SDK. But since I have already installed it, I can just go ahead and build myself an application, so let’s do that.
I start off by creating a blank Store App project. I then add 2 references, one to Json.Net, which is a big part in the SDK, and one to the MobileServices assembly.
According to a bunch of sites on-line, the Mobile Services assembly should be available as an “Extension” under “Assemblies” in the “Add Reference” dialog in VS2012. However, that is missing in my case, and I have also heard other people having the same issue. Luckily, you can manually add the reference by browsing to “C:\Program Files (x86)\Microsoft SDKs\Windows\v8.0\ExtensionSDKs\MobileServicesManagedClient\0.2.0.0\References\CommonConfiguration\neutral\Microsoft.WindowsAzure.MobileServices.Managed.dll”.
If you are doing WP8, the location is “C:\Program Files (x86)\Microsoft SDKs\Windows Phone\v8.0\ExtensionSDKs\MobileServicesManagedClient\0.2.0.0\References\CommonConfiguration\neutral\Microsoft.Azure.Zumo.WindowsPhone8.Managed.dll”, and I love the fact that the WP8 assembly includes the word “Zumo”, I guess that must be a codename or something…
I also want to mention that there are minor differences in the APIs for the platforms, but they are mostly identical…
Now that we have the 2 references, I can go back to the Azure Portal and copy the code-snippet that it gives me, and paste it into my App.xaml.cs file.
sealed partial class App : Application
{
public static MobileServiceClient MobileService = new MobileServiceClient(
"https://darksidecookie.azure-mobile.net/",
"XXXXXXXXXXX"
);
...
}
For this simple example, I will go ahead and declare the Mobile Services proxy like this, but for anything more “real world like” I would definitely suggest NOT to add static variables like this to the App.xaml.cs just to make it available to the entire application. It stinks like hell! But this is a demo, so I will go ahead and do it anyway…
Ok, now the application is prepared to use Mobile Services, so let’s go ahead and do just that.
First off, I add some XAML for input in my MainPage.xaml
<Grid Background="{StaticResource ApplicationPageBackgroundThemeBrush}">
<StackPanel HorizontalAlignment="Center" VerticalAlignment="Center">
<TextBox x:Name="txtMessage" Width="200" />
<Button Content="Save Message" Click="SaveMessage" />
</StackPanel>
</Grid>
As you can see, it is just a simple StackPanel with a TextBox and a Button. Next up is to handle the button’s Click event. But before I can save the message, I need to do 2 things. First of all, I need to create a table to store it in. So I go back to the Azure Management Portal and click the “DATA” link at the top of the “darksidecookie” service page.
This gives me a view of all the tables in the service. At the moment, there are none, so I click the “Create” link and enter the name of the table, which is “messages” in this case.
2 things to note. The first being my choice to name the table “messages”. I go for a lower-case name as all the communication back and forth to the Mobile Service endpoint is going to be Json, and since JavaScript is camel-cased, I just think it looks good to have the table name camel-cased. But you can obviously name the table however you want…
The second thing to note is the permissions settings. All tables have the ability to set the permissions for all CRUD updates. The settings a fairly coarse though, “Everyone”, “Anybody with the application key”, “Only Authenticated Users” and “Only Scripts and Admins”.
“Everyone” is pretty obvious, it lets anyone do the action. And since we are talking about a public REST endpoint, it REALLY means everyone.
“Anybody with the application key”means that anyone that has the application key can do it, which basically means anyone that has your application. This is a very weak form of security, but it is better than “Everyone”, and is also the default.
“Only Authenticated Users” means that only authenticated users can do it…doh! I will do another post on authentication, which is REALLY simple, but for now I can say that you can VERY easily authenticate your users of the Mobile Service using Microsoft ID, Facebook, Twitter and Google.
And the final one, “Only Scripts and Admins”, means that only scripts (I will talk more about them soon) and special admin applications can use the table in the defined manner…
Ok, enough about that. I will just leave them all to be the default “Anybody with the application key”. After clicking ok, it takes a couple of seconds, but then the table has been created, and it is time to go back to the application.
The second thing to do before implementing the Button’s click handler is to create an entity to send to the service. In my case, I will create a really simple class that looks like this
public class Message
{
public int Id { get; set; }
public string Msg { get; set; }
}
However, Mobile Service defaults to inserting entities into tables based on their class names, and the property values into columns named the same thing as the property. In my case, this doesn’t work as my table is named “tables”. Not to mention that I want my column to be named using camel-casing. Luckily, this is easy to change by using a couple of attributes
[DataTable(Name = "messages")]
public class Message
{
[DataMember(Name = "id")]
public int Id { get; set; }
[DataMember(Name = "message")]
public string Msg { get; set; }
}
The DataTableAttribute class is in the Microsoft.WindowsAzure.MobileServices namespace, and the DataMemberAttribute in System.Runtime.Serialization.
A final note on the DTO class is the Id property. All entities being inserted into a Mobile Service table needs to have an Id. I guess that is pretty obvious, but I thought I would mention it…
Ok, now that we have an entity that we can send across the wire, it is time to go about doing it, which is really simple.
private async void SaveMessage(object sender, RoutedEventArgs e)
{
var msg = new Message
{
Msg = txtMessage.Text
};
await App.MobileService.GetTable<Message>().InsertAsync(msg);
new MessageDialog("Done inserting object. Id: " + msg.Id).ShowAsync();
}
It is just a matter of creating an instance of the entity to send to the service, and then use GetTable<T>() to get hold of the “table” and finally call InsertAsync() to insert the entity. And just for the fun of it, I await the insertion before showing a MessageDialog confirming the insertion as well as showing the Id, which has been “magically” set…
After running the application and pushing the buttons once, I can go to the Management Portal once again. But this time, I click the “DATA” link, and then the “messages” table. This will bring up a page where I can browse the data in the table, as well as do some other things…
In my case, the page looks like this after inserting a single message
But wait…how did that work? I never told the table that there was a column named “message”. Well…by default, Mobile Services will automatically create a table schema that can incorporate the data from your entity. This can be turned off, but it is pretty cool during development.
But what if I change my entity? Well, it just works. Let’s say I add a “subject” property as well, and a TextBox for populating it of course
[DataTable(Name = "messages")]
public class Message
{
[DataMember(Name = "id")]
public int Id { get; set; }
[DataMember(Name = "message")]
public string Msg { get; set; }
[DataMember(Name = "subject")]
public string Subject { get; set; }
}
Well, inserting one of those and then refreshing the Manage Portal’s “Browse” view gives me this
You have to admit that that is pretty cool!
But having to augment my entity like that everytime is really annoying form a coding point of view (not really, but let’s say it is…). Not to mention that we will probably end up with a whole heap of these DTOs. Isn’t there another “easier” way? Well, there is… We can go for straight up Json using the power of Json.Net. So instead of having a class like that, we could just do this
var msg2 = new JsonObject();
msg2.Add("message", JsonValue.CreateStringValue(txtMessage.Text));
msg2.Add("subject", JsonValue.CreateStringValue(txtSubject.Text));
await App.MobileService.GetTable<Message>().InsertAsync(msg2);
And THAT is VERY flexible! And if you have ReSharper installed, it “squiggly-lines” it, and tells you to convert it to
var msg2 = new JsonObject
{
{"message", JsonValue.CreateStringValue(txtMessage.Text)},
{"subject", JsonValue.CreateStringValue(txtSubject.Text)}
};
await App.MobileService.GetTable<Message>().InsertAsync(msg2);
which is actually both much more readable and a few keypresses less…
Ok, one final thing I want to show. This post is getting quite long as ususal, but a Mobile Services just wouldn’t be complete without talking about the power of scripts…
All tables have scripts that run on each of the CRUD operations. You can find them in the portal by clicking the table you want, and the clicking “SCRIPT”. By default they look like this
function insert(item, user, request) {
request.execute();
}
And yes, they are JavaScript. Mobile Services run Node.js, so you will have to do JavaScript, but other than that, scripts are REALLY cool. They are VERY flexible, just as JavaScript, and you get a bunch of power through Node.js.
I will write more about scripts in a future blog post, but for now, I want to give a quick intro.
The objects passed into the method are as follows.
The “item” is the entity that was send from the client. It is a Json object representing your entity. You can add and remove properties as you like.
The “user” object is an object representing the user that sent it. As we haven’t authenticated the user in this demo, it will just be an un-authenticated user.
And finally, the “request” object is the allmighty object that does the actual execution. By calling request.execute(), the script is telling the service that I want to do my "insert/update/read/delete based on the values in the “item” at the current time. You can however also call request.respond() and send an HTTP code to the client if you want to. That way you can make your Mobile Service behave like a proper RESTlike endpoint.
Ok…so what con you do with the scripts? Well….just about anything you can think of, just as with any other code… Let’s do something simple just to demonstrate scripting.
I change my insert script to the following for my “messages” table
function insert(item, user, request) {
item.created = new Date();
request.execute();
}
Oh…you do get VERY rudimentary IntelliSense in the script editor as well. It gives you little squiggly lines and so on….but it is VERY rudimentary…
After saving the script like that, and inserting a new entity, my table looks like this
So by just adding new properties using the flexibility of JavaScript, it is possible to augment items before they enter the database…cool…
Ok. that’s if for this time! I will be back with more Mobile Services goodness very soon!
Code available here: DarksideCookie.MobileServices.Intro.zip (24.41 kb)
However, remember that the code sample requires VS2012 with the Mobile Services SDK installed as well as an Azure account with Mobile Services activated and set up. And you need to update the App.xaml.cs with the correct endpoint configuration…