Today I'm pleased to announce several new capabilities we are adding to App Service in support of building mobile applications. App Service Mobile is now more robust, feature rich, and easier to use, making it a great choice for you next mobile backend API.
This set of updates includes:
- No-code tables and APIs for mobile applications
- Turnkey authentication support
- File sync capabilities
- REST API updates (with some breaking changes)
These are captured in today's portal updates as well as the following SDK releases:
- Node.JS Server SDK – 2.0.0-alpha5
- .NET Server SDK – 0.3.36.0 (Release candidate)
- iOS client SDK – 3.0.0-beta4 (Release candidate)
- Windows and Xamarin client SDK – 2.0.0-beta3 (Release candidate)
Easy Tables – No-code APIs for Mobile Apps (Preview)
One of the great things about the original Mobile Services was that you were able to create tables and edit your scripts right in the browser. You didn't have to worry about deploying a server project or maintaining lots of code, and could update your app from anywhere. We’ve heard loud and clear that customers really liked the ease of use of this feature, and I'm pleased to announce that today we are bringing this experience back for Azure Mobile Apps.
You can now easily create mobile-friendly OData CRUD APIs backed by SQL Azure, called “Easy Tables”. These APIs have first class support in the Mobile Apps client SDKs on the iOS, Android, Windows, Xamarin & Cordova platforms, and they work immediately with our offline data sync feature. Once you have a table created, you can view the data stored in it, modify the schema, and add custom logic all within the portal.
We’ve also made Easy Tables really flexible. Behind the scenes we scaffold an Express.JS application with a SQL database, and at any time you can take over and customize the site and database however you wish. You can even swap the storage layer and use Azure Table Storage, Mongo DB, or any other data services. This is also one of several development approaches you can take for your Node applications. If you prefer, you can always deploy via git or one of the other deployment options App Service provides.
This feature is currently limited to sites with the Node SDK, specifically those created from within the portal. So if you'd like to try this out, navigate to the quickstart as discussed above and dive in. Once the quickstart is deployed, you can create and manage endpoints by using the Easy Tables and Easy APIs options from within Settings. Clicking Edit Script for any of these will open the Visual Studio Online editor.
No-code authentication / authorization
Earlier today, I published a post about the new App Service Authentication/Authorization features. With this new release, it's now easier than ever to integrate authentication with Azure Active Directory, Facebook, Google, Microsoft Account, Twitter, or a custom identity provider into any App Service instance. It comes with all of the capabilities you had in Mobile Services, but also with more robust support for scopes and greater ease of management, no code required by you.
One of the many pieces of feedback we received was you wanted more control over authentication at an application level. Mobile Apps now uses App Service Authentication/Authorization in place of the App Service Gateway that was used early on in the preview. The gateway is being deprecated, but it will continue to work until further notice. The Authentication/Authorization feature does not require any additional resources and is available to all App Service applications immediately.
To enable authentication for your application, instead of using the Mobile Authentication settings option, choose Authentication/Authorization. All of the same authentication functionality is there, and the experience for configuring AAD has been simplified to just a few clicks. As part of this change, the Mobile Authentication shortcut will be removed. If you still wish to use an existing gateway, you can always access it from your resource group.
As a result of this change, some of the login and identity endpoints are different. The client SDKs have been updated to reflect this. Please see the Authentication/Authorization post for more details. We're also addressing a long-standing request by releasing support for custom authentication in preview. For more on that, please check the .NET server SDK section below.
File sync support
App Service Mobile includes a data sync capability that allows developers to build apps that work offline and to synchronize with variety of backend data stores. In the past, this was limited to structured data, but today we're adding preview support for files. Now, any entity exposed by your tables can also include a reference to files saved in blob storage. On the client side, we keep track of the changes to the files referenced from the entity. This feature introduces the following APIs to the client SDK:
mobileClient.InitializeFileSync(new MyFileSyncHandler(this), syncStore); await myTable.PullFilesAsync(entity); await myTable.PushFileChangesAsync();
Where MyFileSyncHandler is an implementation of IFileSyncHandler. This tells the application where the files should be stored locally and allows you to override the default synchronization rules.
The server SDKs handle issuance of SAS keys for the client so that your application can securely sync directly to blob storage. They also help manage the synchronization metadata and how files are attached to table entities.
You can try out our file sync support by installing the client library for Xamarin and Windows, located here. A more detailed sample using this feature is available here.
REST API changes
API version checking
One challenge in mobile development is keeping the client and server versions in sync. This is particularly important when taking major version upgrades of project dependencies, and we wanted to make it easier for customers to consume updates to the Mobile Apps SDKs going forward. Today, we are introducing a versioning system that will prevent API contract mismatches between client and server. The Server SDKs now look for a version header that the client SDKs provide. If a supported client version is not present, the server will return an error explaining which versions it will accept.
This means an old version of the Mobile Service client SDK cannot communicate with the latest Mobile Apps Server SDK. While much of the API behavior has stayed the same, there are some differences, such as how push notification registration is handled. We wanted to make it as simple as possible for developers to avoid surprises resulting from these changes.
If your application includes components that don't use the provided Mobile Apps SDKs, you can specify the version in your REST call. Just add ZUMO-API-VERSION as a header or query string parameter, with the value being the targeted version. For additional information about specific versions and how they interact with one another, please see our new client and server versioning topic.
System properties renaming
In our September update, we changed the way system properties were returned. With this release, we are changing the names of the properties to remove the double underscore which prefixed them previously. The __createdAt, __updatedAt, __version, and __deleted properties are now createdAt, updatedAt, version, and deleted, respectively. This makes it much easier for you to write data type mappings with tools like AutoMapper and have better control of the data objects used throughout your app. Please note that this constitutes a breaking change in the API contract – the client and server SDKs released today honor this change, and you should update both of them together. Doing so will also make sure the API version is aligned.
Node.JS Server SDK 2.0.0-alpha5
Last month, we open-sourced our Node.JS SDK, letting users start seeing what we're planning and get involved in the process. We've already received several community contributions – keep them coming!
Please note that this SDK remains in alpha. We encourage users to play around with it, but please do not go to production with this version. We will be moving it to beta once we have gathered some additional feedback.
This version of the SDK is also available through a portal-based quickstart, which will also introduce our in-portal editing. To create a Node.JS Mobile App in the portal, first click New, Web + Mobile, Mobile App, and follow the creation steps. Once the app is created, navigate to it and open Settings, and then select Get Started from the mobile category. Pick a client platform and follow the instructions. Step 2 will provision a Node.JS site for you with the classic quickstart.
At this time, we do not have end-to-end tutorials available for Node.JS. However, we have written a general document for working with the Node SDK, and there is great documentation on the GitHub repository. When we move the Node SDK out of Alpha and into a more robust preview, we will provide a full suite of documentation on azure.com.
.NET Server SDK release candidate
Over the past few months we've made several updates to the .NET SDKs. Based on the feedback we're seeing, we think we're ready for a release candidate. The SDK is still in preview, but it should be pretty closely aligned to what we expect to put out as 1.0.
You can get started by installing the 0.3.36.0 NuGet packages into your project. The quickstart projects in the portal have also been updated to use this version. As with the other updates, there are some breaking changes to be aware of. Most of these are just method renames, particularly around authentication. Variables and methods that started with MobileApp* are now AppService*, as many of these capabilities apply to more than just mobile scenarios.
We are also introducing a new preview NuGet package which brings support for custom authentication: Microsoft.Azure.Mobile.Server.Login. This package supplies the MobileAppLoginHandler.CreateToken() method, which allows you to easily issue a token for a given user. For example, if you wanted to leverage my own username/password store, you could write an API such as the following:
public HttpResponseMessage Post([FromBody] JObject assertion) { if (isValidAssertion(assertion)) //checks against a database { JwtSecurityToken token = MobileAppLoginHandler.CreateToken(new Claim[] { new Claim(JwtRegisteredClaimNames.Sub, assertion["username"]) }, mySigningKey, myAppURL, myAppURL, TimeSpan.FromHours(24)); return this.Request.CreateResponse(HttpStatusCode.OK, new LoginResult() { AuthenticationToken = token.RawData, User = new LoginResultUser() { UserId = userName.ToString() } }); } else { return this.Request.CreateUnauthorizedResponse(); } }
Here, isValidAssertion is just a method to wrap the custom validation logic, and LoginResult/LoginResultUser are just simple objects to wrap the properties being set in the response. Custom authentication is really lightweight, so you can integrate with your own store or a third-party provider very easily.
We have also removed a few extraneous types, such as MobileAppUser (recently renamed to AppServiceUser). This class really only provided the GetIdentityAsync() method, and meant you had do an explicit cast. Now, we've moved GetIdentityAsync() to be an extension method on IPrincipal, so you can just write:
ProviderCredentials creds = await this.User.GetAppServiceIdentityAsync(this.Request);
Just make sure to include a “using System.Security.Principal;” statement so the extension method shows up appropriately.
We also recently announced the open-sourcing of the .NET server SDK. Our GitHub repo is a great place to file issues, see what we're doing, and contribute to the project. You can also see a full list of changes on our changelog.
Client SDK release candidates
The release candidate client SDKs have been updated to support provide the version header and to use the new endpoints for authentication. They also include the system properties changes required to use the latest Server SDK. Most developers will not need to worry about code changes when updating to the new client SDKs, with the exception of the constructor. The constructor now only takes the application URL, as well as any optional delegating handlers. The gateway URL parameter has been removed due to the authentication changes, and the application key parameter is gone, mirroring the server SDK changes from July.
iOS (Objective-C)
self.client = [MSClient clientWithApplicationURLString:@"https://contoso.azurewebsites.net"];
iOS (Swift)
let client = MSClient(applicationURLString:"https://contoso.azurewebsites.net")
Windows and Xamarin (C#)
MobileServiceClient client = new MobileServiceClient("https://contoso.azurewebsites.net");
You can try out the release candidates by installing the managed NuGet package or downloading the iOS framework. The quickstart projects in the portal have also been updated to include these.
Temporary removal of the HTML/JS quickstart
Several of the changes, including API version checking, system properties renaming, and the authentication transition, have not been implemented yet in the HTML/JS SDK. In order to reduce confusion in terms of SDK compatibility, we have opted to temporarily remove the SDK from the quickstart options in the portal.
Getting the HTML/JS SDK to parity is a major near-term goal, and we aim to be bring it back shortly. We appreciate your patience as we continue through our preview.
Coming soon to a cloud near you…
We have a lot more changes coming soon. Here's a quick preview of what's coming before the end of the year:
- Moving the release candidate SDKs out of preview
- Android SDK for Mobile Apps
- Beta release of the Node.JS SDK
- One-click migration for Mobile Services customers with zero code changes required
- More documentation to help you make the most of all of these features
Until then, please check out the above updates and let us know what you think! You can connect with the Mobile Apps team in the comments below, on Twitter, our MSDN forums, or the Azure feedback site.