Mobile Services .NET Backend: Part 1—Creating the Service and Defining the REST API
Now that support for .NET backend (Web API) in Azure Mobile Services is well on its way, it’s time to start putting together some guidance on how to develop and deploy these .NET-specific flavor of mobile services. My plan is to eventually include this information into a new guidance topic on Azure.com.
I decided to chunk this guidance into a series of posts, so this is Part 1, where I will give a brief overview of how you create a .NET backend mobile service and define the REST API exposed by the service.
Introduction
A .NET backend mobile service is implemented as a specialized kind of Web API project in Visual Studio 2013. Unlike the original JavaScript (node.js) backend, where you have to manually create tables in the portal (or use the Git repo) and use dynamic schema to add columns automatically, the data model for a .NET backend project is defined strictly by using the Code First functionality of Entity Framework.
Data model changes are pushed to an existing database by using Code First Migrations (we’ll discuss this later posts—but here’s a hint). You can define the business logic components (controllers and scheduled jobs) manually, but Visual Studio 2013 Update 2 brings some nice new tooling to make things easier. One of the best things about using Entity Framework for data access is that you can extend data storage to any storage service that has an Entity Framework provider, and Mobile Services comes with several right out of the box.
Creating the .NET Backend Project
First, let’s discuss how to create a new .NET backend mobile service and get up and running with the project. There are two basic ways that you can do this….
From the Azure Management Portal
Now, when you create a new mobile service in the Azure Management Portal, the first thing that you choose is whether you want a .NET backend or a JavaScript (node.js) backend.
The rest of the process is the same for both backend types. As before, you can download a client-specific starter project that is already preconfigured to work with your new mobile service, but this time you also get the .NET backend Web API project with it.
For a great tutorial that walks you through this scenario, see Get started with Mobile Services
From Visual Studio 2013 Update 2
Visual Studio 2013 integrates with Mobile Services, including letting you create a new mobile service directly from the Visual Studio IDE. With Update 2 of Visual Studio 2013, you are also able to create a new .NET backend mobile service from the IDE, along with adding new controllers to an existing .NET backend project.
For complete instructions on how to use Visual Studio 2013 U2 to add a .NET mobile service backend to your solution, see Quickstart: Add a mobile service (.NET backend).
There is a release candidate (RC) version of Visual Studio 2013 U2 that you can download today (it has been working well enough for me).
Controllers and Scaffolding
When you visit the Azure Management Portal for a .NET backend mobile service, you will notice that the Data and API tabs are missing, and that there is no longer a way to define jobs in the portal (although you can still schedule and run them there). Creating a .NET backend mobile service is very much like creating any ASP.NET Web API service. The REST API exposed by the mobile service is implemented as ASP.NET Web API controllers.
The classes you use to implement the mobile service derive from these three new Mobile Services-specific scaffolds:
TableController<TData>
This new controller, which inherits from ApiController, exposes entity data for REST access as a /tables/table_name endpoint. This works when your controller class derives from TableController<TData>, where TData inherits from EntityData and is exposed as a a DbSet<TData> in a Code First data model . Visual Studio 2013 Update 2 contains new tooling that makes it easy to create a new TableController<TData>. To learn more, see How to use controllers to access data in mobile services.
Both the Mobile Services quickstart (in the Azure portal) and the Visual Studio tooling are currently tailored to storing data in tables in the SQL Database that is associated with your mobile service. However, there is also support (via NuGet packages) for using either MongoDB or Azure Table Storage services instead of SQL Database. To learn more, see Carlo’s post Creating MongoDB-backed tables in Azure Mobile Services with .NET backend and Simon J.K. Pedersens’s post Azure Mobile Service .NET backend using Azure Table Storage.
In a subsequent post, I’ll show more about the data model and accessing data from the backend .
ApiController
This is the same standard controller used by Web API, but the goodness starts when you add a Services property to this class. The ApiServices object returned by this property is used by Mobile Services to provide your controller with access, at runtime, to all the metadata loaded by your mobile service. Note that TableController<TData> also inherits from ApiController. Again, when you use the latest Visual Studio tools, you get a scaffold that creates a custom API controller with the Services property. To learn more, see How to create custom APIs and scheduled jobs in a mobile service.
ScheduledJob
In the strictest sense, a scheduled job is not a REST API or a controller, but rather it is a special class that can be scheduled and started asynchronously by the Mobile Services runtime. A scheduled job must inherit from the ScheduledJob class, where the code that defines the job to be executed goes in the ExecuteAsync method override. You can test the scheduled job locally by sending a POST request to the /jobs/JobName endpoint. (Note that when your class name ends in job, you can leave this off.) Once the job is published, you use the Scheduler tab in the portal to register your ScheduledJob class and to either run the job or to schedule its execution. We are finishing up a .NET backend equivalent to the topic Schedule backend jobs in Mobile Services, and I will update this link when it becomes available.
Creating a Mobile Service Project from Scratch
The project that you download from the Mobile Services quickstart tab in the Azure portal already has the basic scaffolding in place (TableController<TodoItem> and a SampleJob class), and there is tooling in Visual Studio 2013 U2 to create Mobile Services-specific controllers and classes. However, if you want to see how to leverage an existing mobile service from an empty ASP.NET Web API project or add it to an existing Web API project, see Carlo’s blog post Creating an Azure Mobile Services .NET backend from scratch (assuming that you have already created the mobile service in the portal).
That’s it for now….cheers!