Transition from Mobile Services to Mobile Apps Node.js Edition
Adrian Hall (MSFT)
We recently announced that Azure Mobile Services will be deprecated and all services will be migrated to Azure App Service. At this point, you will become responsible for the code running your app. You may want to upgrade your site to take advantage of the additional facilities that Azure App Service provides you, such as staging slots and picking the Node version that is run when you run your site. The Azure Mobile Apps compatibility package allows you to convert older Azure Mobile Services applications written for the Node platform so that they can utilize the latest Azure Mobile Apps Node SDK.
How Does it Work?
The package takes the raw source code from a Node-based Azure Mobile Service and generates the equivalent set of table and custom API definitions that will work with the Azure Mobile Apps Server SDK for Node. You will have a new project at the end that you can deploy as a new site to Azure App Service. Both platforms offer a similar set of functionality, but with different APIs. The compatibility package maps the Mobile Services API to the newer Mobile Apps API. The generated app is ready to deploy to an Azure App Service and should work for most applications. It's important to review the code afterwards as some common scenarios (such as authentication) will require specific configuration or code changes in addition to the conversion.Performing a Conversion
Because the conversion produces a new site, there is a natural process to the conversion. If you run into problems, please get live help - we listen in on Stack Overflow, the Azure Forums and have a Gitter channel for live assistance during normal (West US) working hours. Note that this process cannot be attempted until AFTER you have migrated the site from Azure Mobile Services to Azure App Service.Obtain your Azure Mobile Services Scripts
Open the Debug Console in your browser (it's at http://yourMobileService.scm.azure-mobile.net/DebugConsole). Navigate by clicking on the directory names to site/wwwroot/App_Data/config. Download the scripts directory in ZIP format by clicking on the download icon next to the folder name.Create the Azure Mobile App
First, install the compatibility package by executing the following with elevated privileges:npm i -g azure-mobile-apps-compatibilityThis installs a command line utility with the following usage:
scaffold-mobile-app <inputPath> <outputPath>For example,
scaffold-mobile-app scripts outThis reads the Azure Mobile Service definition from the scripts directory located in the current working directory and creates a directory called out with a scaffolded Mobile App. Once the app has been created, check the target folder to make sure it contains files for the tables and custom APIs you defined in your mobile service. Your app is almost ready to deploy!
Deploying and Testing
During deployment, you will need to update your database and create a new App Service, linking the updated SQL database to the new App Service.Create Database Compatibility Views
Mobile Services created a specific schema to hold the Mobile Services data and had system column names preceded by a double-underscore. Mobile Apps has changed these requirements. We can map one to the other using SQL Views. The scaffolded app includes a SQL script called createViews.sql. This script must be executed against the target database. The connection string for the target database can be obtained from your Mobile Service or migrated Mobile App from the Settings blade under the Connection Strings section. The connection string name is MS_TableConnectionString. This script creates read / write views in the dbo database schema that map older reserved column names to new column names. This script can also be obtained from our GitHub repository.Create the Target Mobile App
Create a new App Service Mobile App using the Azure portal and perform the following tasks:- Take note of the URL for your Mobile App. You will need it later.
- Configure a data connection that points to the Mobile Service database.
- Configure push settings to use the same configuration as the Mobile Service.
Deploy your new Mobile App
The simplest way to get your app onto Azure is using FTP. The URL, username and password can be obtained from the portal. Before copying the files, you must run npm install in a console window from the output folder created above. Copy the entire contents of the output folder to the site/wwwroot folder of the FTP host. Alternatively, if you are familiar with git, we recommend you follow publish from source control. You can also use WebDeploy or hook up continuous deployment. After you have deployed your app, open your browser and navigate to the URL of your Mobile App. You should see the home page for your app. Additionally, the Easy Tables and Easy API sections for your app in the portal should now be functional.Update Your Client
The client application must be updated to use the latest version of the Azure Mobile Apps SDK. In many cases, this may simply be a matter of updating the Azure Mobile Apps libraries to the latest version. Note that some libraries changed names:- The C#/.NET/Xamarin library is now Microsoft.Azure.Mobile.Client
- The JavaScript library is now azure-mobile-apps-client
- The Apache Cordova library is now cordova-plugin-ms-azure-mobile-apps
Troubleshooting
If you run into a problem, you should debug the issue just like you would any other development issue. Generally, this means you should enable diagnostic logs for your app. Explicitly, you should turn on Application Logs (Filesystem) to see most of the issues with the code. Here are some of the more common errors you may encounter with their solutions.Cannot find module 'xxx'
Dependencies on external modules such as async have not been included by default to reduce the size of the application. If you are using any external modules, you will need to install them by opening a browser to https://_yourMobileService_.scm.azurewebsites.net/DebugConsole , navigating to the site/wwwroot folder and executing:npm i <module name>You can also add an options @<version> - this is recommended to install the same package versions that were used in your original Mobile Service.
The table 'xxx' does not exist
The getTable function is now case-sensitive. Check to ensure the appropriate case is being used.Invalid column name '__createdAt'
The double underscore notation for createdAt, updatedAt, version and deleted columns have been removed. You will need to update any explicit column references manually within your code. The SQL script createViews.sql will take care of these columns in your database.Can't set headers after they are sent
Calling request.respond or response.send more than once per request will result in this error. Older versions of the web framework used by Mobile Services, express, allowed this behavior, but the current version does not. Use the generated stack trace to identify the offending module and change the code to ensure these functions are only called once.Error in sideband demultiplexer
This usually indicates a corrupt git repository. You can fix this by running:git remote set-head origin masterThis assumes your remote repository uses the default name origin and the branch you are pushing to is called master.
