# Getting Started with Windows Azure Mobile Services #
---
<aname="Overview"/>
## Overview ##
This demo script demonstrates how you can leverage Visual Studio 2012 and Windows Azure Mobile Services to add structured storage, push notifications, integrated authentication and scheduled jobs to your Windows Phone application.
> **Note:** This is a demo script that can be used as a guide for demos when presenting on Windows Azure Mobile Services and Windows Phone. Given this is a demo script and not a HOL screenshots have been excluded to keep printed format short. The corresponding PowerPoint presentation can be found here - [Presentation: Developing Windows Phone apps with Windows Azure Mobile Services](https://github.com/WindowsAzure-TrainingKit/Presentation-WindowsPhoneAndWindowsAzureMobileServices)
<aname="technologies"/>
### Key Technologies ###
- Windows Azure subscription - you can sign up for free trial [here][1]
- Windows Azure Mobile Services Preview enabled on your subscription
In order to execute this demo you need to set up your environment.
1. Download and Install Windows 8
1. Download and Install Visual Studio 2012
1. Download and Install the Windows Phone 8 SDK
1. Download and Install the Windows Azure Mobile Services SDK
1. **Code Snippets** have been provided that you can add for use in Visual Studio 2012. You can find them in /Source/Assets/ClientSnippets
<aname="Demo 1: Structured Storage - Creating your first Mobile Service"/>
## Demo 1: Structured Storage - Creating your first Mobile Service ##
The goal of this demo is to use the quick start within the portal to quickly demonstrate the structured storage capability of Windows Azure Mobile services. The Push Notifications demo will demonstrate how you can add code to both the server and client to demonstrate the APIs used by the quick start.
<aname="create-a-new-mobile-service"/>
### Create a new mobile service ###
Follow these steps to create a new mobile service.
1. Log into the [Windows Azure Management Portal](https://manage.windowsazure.com) and navigate to Mobile Services in the
1. Click the **+New** button then click **Mobile Service**, **Create**
1. On the **Create a Mobile Service** dialog provide a unique subdomain in the **URL** field. Once verification that the subdomain is unique proceed with the next steps.
1. Select either to use an existing database or new database and region. **Speaking Point:** If you select an existing database Windows Azure Mobile Services will separate multiple Mobile Service tenants by schema.
1. Complete the remainder of the database settings in the Create Mobile Service wizard
You have now created a new mobile service that can be used by your mobile apps.
<aname="create-a-new-app"/>
### Create a new app ###
Once you have created your mobile service, you can follow an easy quick start in the Management Portal to either create a new Windows Phone app or modify an existing app to connect to your mobile service.
1. After the status updates to **Ready** for your mobile service in the **Mobile Services** tab of the Management portal. Click on your mobile service name to navigate into the service.
1. Click on  to see the Mobile Services quick start page.
1. Select **Create a new Windows Phone 8 application** and perform the three steps provided
- For the **Get the tools** step Install the Mobile Services SDK if you have not done so already. The Mobile Services SDK provides a client side API that can be used within your Visual C++, XAML/C#/VB and HTML/JS Windows Phone apps.
- Click **Create Todoitem table**. This will create a table for the starter project.
- In the Download and run your app step select your desired app language, in this case **C#**, and click **Download**.
This downloads the project for the sample _To do list_ application that is connected to your mobile service. Save the compressed project file to your local computer, and make a note of where you save it.
> **Speaking Point:** You can add additional tables manually by clicking the "Data" tab and using the Create button within. We will revisit adding tables through the Data tab further on in the Push Notification demo.
<aname="run-your-app"/>
### Run your app ###
The final stage of this tutorial is to run and explore your new Windows Phone app.
1. Browse to the location where you saved the compressed project files, expand the files on your computer, and open the solution file in Visual Studio 2012.
1. Press the **F5** key to rebuild the project and start the app.
1. In the app, type meaningful text, such as _Complete the demo_, in the **Insert a TodoItem** textbox, and then click **Save**.
**Speaking Point:** Explain this sends a POST request to the new mobile service hosted in Windows Azure. Data from the request is inserted into the TodoItem table. Items stored in the table are returned and are subsequently populated in the list within the app. Pressing referesh causes a query against the mobile service filtering back incomplete items. Checking the checkbox causes an update against the Mobile Service
1. Back in the Management Portal, click the **Data** tab and then click the **TodoItems** table and observe that the data as been successfully stored
> **Note:** an effective way to do this portion of the demo is to have the WP emulator docked to the left side of the screen and the TodoItem Data tab docked in the right side of the screen. Insert the item then hit the refresh button in the toolbar at the bottom of the portal to see the new+updated data.
<aname="Explore-your-app-code"/>
### Explore your app code ###
In this step we explore _To do list_ application code and see how simple the Windows Azure Mobile Services Client SDK makes it to interact with Windows Azure Mobile Services.
1. Return to the downloaded To do list application Visual Studio 2012
1. In solution explorer **expand the references folder** and show the Windows Azure Mobile Services Client SDK reference. **Note:** While the dowloaded app already includes the reference you should show where to find the Windows Azure Mobile Services Client SDK referece if they already have an existing Windows Phone app under development.
1. Open App.xaml.cs and show the MobileServiceClient class. This is the key class provided by the client SDK that provides a way for your application to interact with Windows Azure Mobile Services. The first parameter in the constructor is the Mobile Service endpoint and the second parameter is the Application Key for your Mobile Service.
````C#
public static MobileServiceClient MobileService
= new MobileServiceClient(
"https://cloudnick.azure-mobile.net/"
,"vIWepmcOXGPsYCJQDDcFBKsnOVxzLG52" );
````
1. Open **MainPage.xaml.cs** to see how the mobile service client is then used for Inserts, Updates, Reads and **show** the following:
- Show the TodoItem entity and explain how the DataMember attribute can be used to provide different names to be used within the mobile service and for persisting the data to the underlying Windows Azure SQL Database. Note that you can also manipulate the Table that the entity is serialized to using DataTable attribute. This is useful for some environments where the DBAs may require a specific table naming convention e.g tblTodoItem etc.
- Note existence of todoTable.DeleteAsync(...) method
<aname="Demo 2: Server Scripts"/>
## Demo 2: Server Scripts and Structured Storage ##
> **Speaking Note:** In this demo we will demonstrate how you can inject your own business logic within the Mobile Services CRUD operation pipeline using Server Scripts. This is useful for scenarios like validation on the server side and implementing custom server side workflows.
1. In the portal Select the Select the **TodoItem Table**
1. Select the Scripts tab
1. Show that there are dropdowns for Insert/Read/Update/Delete
1. Select the **Insert** Dropdown and explain the item, user and request params
1. Add the following code to the Insert operation to demonstrate how one would add some simple validation within a Server Script.
````JavaScript
function insert(item, user, request) {
if(item.text.length <5){
request.respond(statusCodes.BAD_REQUEST, 'text is too short');
} else {
request.execute();
}
}
````
> **Note:** The above code snippet is also available in /Source/Assets/ServerSnippets/InsertScript.TodoitemTable.ValidateDemo.txt
<aname="Demo 3: Adding Push Notifications to your app"/>
## Demo 3: Adding Push Notifications to your app ##
In demo, you add push notifications, using the Microsoft Push Notification service (MPNS), to the quickstart project. When complete, an insert in the mobile service will generate a push notification back to your app. In this case we are choosing to use a Tile Notification as we can receive this while the app is running to generate the notification. Later we will look at Toast Notifications with scheduled scripts.
<aname="Add-push-notifications-to-the-app"/>
### Add push notifications to the app ###
1. In Visual Studio open the **Properties/WMAppManifest.xml** file, select the Capabilities tab and Check ID_CAP_PUSH_NOTIFICATION.
1. In the package.appxmanifest now select the **Application UI** tab and ensure **toast capable** is set to yes. **Speaking Point:** If you wish to send Wide Tiles then you must provide a default wide tile in the Wide Logo field.
1. Open the file **App.xaml.cs**
1. Replace the _Application_Launching_ and _Application_Activated methods with the following code snippet.
> **Note:** This is a rather large code snippet. Please ensure you walk though the code with the attendees. The key points to note are that you Request a Channel with the HttpChannelNotification Class and then Register it with Mobile Services
> **Note:** You can install and use the code snippet _wpchannelrequest_ located in /Source/Assets/ClientSnippets to perform this task. Note you may also remove the events for HttpNotificationReceived and ShellToastNotificationReceived if you do not want to handler Raw and Toast notifications respectively when the application is in the foreground
Now that we have the client wired up to request a channel and write it to our Mobile Service we now need to add a Channel table to our Mobile Service and add a server side script to send push notifications.
1. Now pin the tile of the application to the start screen on your Phone such that we can see when a notification is delivered.
<aname="Insert-data-to-receive-notifications"/>
### Insert data to receive notifications ###
In this section we add a Channel table and server side scripts to send push notifications everytime someone inserts into our TodoItem table. **Note:** from a demo perspective and in ensuring it keeps the duration of the presentation within an 1 I would suggest for the demo you keep the server scripts somewhere that you can copy and paste them in, then walk through what they are doing as opposed to typing them out.
1. Log on to the [Windows Azure Management Portal](https://manage.windowsazure.com/), click **Mobile Services**, and then click your app.
1. Select the **Data** tab
1. Click **+ Create** in the bottom toolbar
1. In **Table name** type _Channel_, then click the check button.
1. Click the new **Channel** table and verify that there are no data rows.
1. Click the **Columns** tab and verify that there is only a single **id** column, which is automatically created for you.
This is the minimum requirement for a table in Mobile Services.
**Speaking Point:** When dynamic schema is enabled on your mobile service, new columns are created automatically when JSON objects are sent to the mobile service by an insert or update operation.
1. Select the **TodoItem** table
1. Click the **Script** tab and select the **Insert** Operation and replace the existing script with the following and walk through the following code
````JavaScript
function insert(item, user, request) {
request.execute({
success: function(){
request.respond();
sendNotifications(item);
}
});
}
function sendNotifications(item){
var channelTable = tables.getTable('Channel');
channelTable.read({
success: function(channels){
channels.forEach(function(channel){
push.mpns.sendFlipTile(channel.Uri,{
title: item.text
});
});
}
});
}
````
**Note:** This script is located in the file _/Source/Assets/ServerSnippets/InsertScript.TodoitemTable.PushDemo.txt_ folder
**Speaking Point:** This script executes as a each time a the insert operation is performed on the Todoitem table. The sendNotifications method we select all channels from the Channels table and iterate through them sending a push notification to each channel uri. While we have only demonstrated a basic example of the sendFlipTile method in the push.mpns.* there are a number of other overloads and parameters you can use to send tile, toast and raw notifications. You can find all supported push.mpns.* functions and parameters [here ](http://msdn.microsoft.com/en-us/library/windowsazure/jj871025.aspx)
Next we will move on to look at how you can secure your Mobile Service endpoints using Twitter
<aname="Demo 4: Adding Auth to Your App and Services"/>
## Demo 4: Adding Auth to Your App and Services ##
This demo shows you how to authenticate users in Windows Azure Mobile Services from a Windows Phone 8 app. In this demo, you add authentication to the quickstart project using Twitter and lock down the service such that only authenticated clients can Insert/Update/Delete/Read from your TodoItem table. When successfully logged in using Twitter the authenticated users will be able to consume your Mobile Service.
<aname="Register-your-app"/>
### Register your app ###
To be able to authenticate users using Twitter, you must register your Mobile Service within the Twitter developer portal. Following this you must then register the twitter secrets with your Mobile Service.
1. Navigate to the [Twitter developer portal](https://dev.twitter.com/) and log on with your Twitter Account if needed, and then follow the instructions to register your app.
> **Note:** In this example we will use Twitter. If you wish to demonstrate another then choose supported identity provider from the list below and follow the steps to register your app with that provider:
1. Once logged in to the [Twitter developer portal](https://dev.twitter.com/) **click your username** in the top right and select **My Applications**
1. Press **Create a new Application**
1. Provide an arbitrary Name, Description and Website
1. For the Callback Url field enter the domain of your mobile service, in the format **https://****service-name****.azure-mobile.net/**, where _service-name_ is the name of your mobile service, then click **Save**.
1. Press **Create your Twitter Application**. On success this will provide you with a Consumer Key and Consumer Secret.
> **Note:** I generally dock the Twitter browser Left and dock the Windows Azure Portal Right for the next two steps
1. Select the **Identity Tab** in the Windows Azure Portal for your Mobile Service
1. Copy the Twitter Consumer Key and Consumer Secret to the correspond Mobile Service Portal Twitter settings fields and click **save**
<aname="Restrict-permissions"/>
### Restrict Table permissions ###
1. In the Management Portal, click the **Data** tab, and then click the **TodoItem** table.
1. Click the **Permissions** tab, set all permissions to **Only authenticated users**, and then click **Save**. This will ensure that all operations against the **TodoItem** table require an authenticated user.
1. Return to Visual Studio 2012 and press the **F5** key to run the app again; verify that now an exception with a status code of 401 (Unauthorized) is raised.
This happens because the app is accessing Mobile Services as an unauthenticated user, but the _TodoItem_ table now requires authentication.
Next, you will update the app to authenticate users with a Microsoft Account before requesting resources from the mobile service.
<aname="Add-authentication"/>
### Add authentication to your app###
1. Now that your Authentication provider is now configured lets wire up the application. Return to Visual Studio and select **MainPage.xaml.cs**
1. In the constructor for MainPage.xaml.cs add an event handler for the Page Loaded event
<!-- mark:4 -->
````C#
public MainPage()
{
InitializeComponent();
this.Loaded += MainPage_Loaded;
}
````
1. Remove **OnNavigatedTo** and replace the MainPage_Loaded handler with the following:
> **Note:** You can install and use the code snippet _wpauthenticate_ located in /Source/Assets/ClientSnippets to perform this task.
1. Press the F5 key to run the app and sign into the app with your chosen identity provider. **Note:** that you should probably move the emulator out of view for the password entry.
> **Note:** When you are successfully logged-in, the app will run without errors, and you will be able to query Mobile Services and make updates to data now that the user is authenticated.
<aname="Exercise5"/>
## Exercise 5: Adding a Scheduled Job to your Mobile Service ##
In this demo you learn how to execute script on a scheduled basis using **Windows Azure Mobile Services**. In this scenario we will configure the scheduler to poll Twitter every 15 minutes and then send a Toast notification with the latest tweet directed at a given alias.
### Task 1 - Close the Windows Phone app ###
1. Close the Windows Phone application so that you can see the toast arrive
### Task 2 - Configure the Mobile Services scheduler ###
1. Create the scheduler job that will send push notifications to registered clients every 15 minutes with the latest Twitter updates for a particular twitter handle.
1. Specify a name for the job and make sure the schedule frequency is set to **every 15 minutes**. Click the check mark to create the job.
1. Select the created job from the job list.
1. Select the **Script** tab and paste the code snippet below that both polls Twitter and then composes a push notification to update your start screens tile using push.mpns.*
**Note:** This script is located in the file _/Source/Assets/ServerSnippets/Scheduler.CheckTweets.txt_ folder
1. Once you paste the script into the editor, click the **Save** button to store the changes to the script
> **Note:** Note for next few steps of the demo I like to have both the Emulator (docked left) and Portal (docked right) visible
1. In the **Scheduler** tab of your mobile service click **Enable** in the command bar to allow the job to run every 15 minutes
1. To test your script immediately rather than wait 15 minutes for its first scheduled run, click the **Run Once** button in the command bar.
1. In the emulator you should see a toast delivered.
**Note:** an interesting alternative to this demo would be to send a push.mpns.sendFlipTile with the users twitter profile which is also returned in the tweet object.
<Description>This demo script demonstrates how you can leverage Visual Studio 2012 and Windows Azure Mobile Services to add structured storage, push notifications, integrated authentication and Scheduled Scripts to your Windows Phone application.</Description>
<DocumentConversionType="Html">Demo.md</Document>
<Title>Getting Started with Windows Azure Mobile Services and Windows Phone</Title>
# Getting Started with Windows Azure Mobile Services #
## Demo ##
### Introduction ###
Demos are sets of step-by-step guides that are designed to help you learn how to use key Windows Azure services and features. Each demo provides instructions to guide you through the process of developing a complete application.
In this demo you will see how how you can leverage Visual Studio 2012 and Windows Azure Mobile Services to add structured storage, push notifications and integrated authentication to your Windows Store application.
> **Note:** You can download the latest build of the Windows Azure Training Kit which includes a tested version of this Demo from here: http://bit.ly/WindowsAzureTK.
### Repository Structure ###
In the **root** folder of this repository you will find the script for this demo, **Demo.md**. Before beginning with the demo, make sure you have followed all the required steps indicated in the **Setup and Configuration** section of the document.
In the **Source** folder, you will find all the material necessary for this demo. The demo script will give you instructions on how to use this content. Typically, it will contain the following subfolders:
- **Setup:** This folder contains the dependency files and the setup scripts necessary to initialize specific configurations of the demo. Its execution is required for the majority of the demos.
- **Code:** This folder contains the source code required to perform the demo (usually there is a ***begin*** folder, which contains the starting code that you will complete by following the steps of the demo, and an ***end*** folder, which is the final result you should obtain once the demo is completed).
- **Assets:** This folder contains common content that is necessary to complete the demo.
### Get Started ###
In order to run the solutions provided by this demo you will first need to configure your environment and install any necessary prerequisites such as runtimes, components, or libraries. After cloning the Demo from the repository, follow the steps in the **Setup and Configuration** section of the Demo.md document.
### Contributing to the Repository ###
If you find any issues or opportunities for improving this demo, fix them! Feel free to contribute to this project by [forking](http://help.github.com/fork-a-repo/) this repository and make changes to the content. Once you've made your changes, share them back with the community by sending a pull request. Please see [How to send pull requests](http://help.github.com/send-pull-requests/) for more information about contributing to Github projects.
### Reporting Issues ###
If you find any issues with this demo that you can't fix, feel free to report them in the [issues](https://github.com/WindowsAzure-TrainingKit/Demo-Windows8AndMobileServices/issues) section of this repository.
Nick harris
