Quickstart: Creating a connected app with mobile services
[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]
By starting with the sample that this topic describes, you can create any turn-based game that users play over a network. The TicTacToe sample is a simple Windows Store app that multiple users can play on various devices that are running Windows 8.1. The app stores game state by using mobile services and communicates updates by using push notifications.
Prerequisites
Windows 8.1.
Microsoft Visual Studio 2013 with NuGet installed.
To determine whether NuGet is installed, open the shortcut menu for a project node in Solution Explorer. If Manage NuGet Packages appears, NuGet is installed.
Download it from NuGet Package Manager for Visual Studio 2013.
The Azure SDK, which you can get from the Microsoft Azure Download page.
An Azure account with a subscription.
If you don't have one, sign up for a free trial.
Windows PowerShell.
Azure Command-Line Environment (CLI). See How to: Install and Configure the Azure Cross-Platform Command-Line Interface.
The TicTacToe sample files, which you can get from MSDN Code Gallery.
Install the sample, and set up the mobile service
Extract the files from TicTacToe.zip, and then open the TicTacToe solution.
Download a subscription file for your Azure subscription.
If you have the Azure tools installed, you can download this file by following these steps.
- In Server Explorer, open the shortcut menu for the Microsoft Azure node, and then choose Manage Subscriptions.
- On the Certificates tab, choose the Import button, and then choose the Download subscription file link.
- If prompted, sign in with the credentials that you use to access your Azure subscription.
- Confirm the download, and note the file location.
- In Visual Studio, choose the Cancel button, and then choose the Close button.
If PowerShell scripts aren't enabled, follow these steps.
- In a Azure Command Prompt window with administrative permissions, enter powershell.
- In the PowerShell command prompt that appears, enter Set-ExecutionPolicy unrestricted.
Change directories to the TicTacToe\TicTacToeCSharp\Script subdirectory of the directory where you installed the sample, and then run one of the following commands. Specify a new value for the mobile service that you're creating.
Note You'll need a unique name for your copy of the TicTacToe mobile service, such as TicTacToeYourName. An error will appear if you choose a name that's already in use.
Use this command line if you want to create a database and use the first subscription in the file. Specify new values for the ID and password of the administrator for the database that you're creating:
powershell -File "tictactoesetup.ps1" --subscriptionFile "YourSubscriptionFile" --serviceName "YourMobileServiceName" --serverAdmin "DatabaseAdminUserId" --serverPassword "DatabaseAdminPassword"
The script might take some time to run, as it creates a mobile service and all the tables and server-side scripts that the sample needs.
Add one or both optional parameters if you want to use an existing SQL Database in Azure or if you have multiple subscriptions and you don't want to use the first one in the list. Specify the ID and password of the administrator for the existing database.
powershell -File "tictactoesetup.ps1" --subscriptionFile "YourSubscriptionFile" --subscriptionId "YourSubscriptionId" --serviceName "YourMobileServiceName" --serverName "YourSQLServerInAzure" --databaseName "YourSQLDatabaseName" --serverAdmin "YourDatabaseAdminUserId" --serverPassword "YourDatabaseAdminPassword"
If you've never created a mobile service with your Azure subscription before, the script may fail with an error that your subscription isn't registered to use mobile services. If this error appears, go to the Azure management portal, create a mobile service, and then re-run these steps. You can then create mobile services by using the Azure CLI.
In Internet Explorer, open the Azure management portal, and then choose your mobile service.
On the Data tab, verify that four tables were created: games, moves, userfriends, and users.
Set up permissions and authentication
In the management portal, choose your mobile service, and then choose the Manage Keys button.
Choose the Copy button to copy the application key for your mobile service to the Clipboard.
In the TicTacToeCSharp solution, open App.xaml.cs, and locate the first line of the App class.
In the call to the constructor for the MobileServiceClient, insert the name of your mobile service, and paste the application key where requested.
In the next step, you'll register your version of the TicTacToe app with the Windows Store.
In Solution Explorer, open the shortcut menu for the TicTacToeCSharp project, choose Store, and then choose Associate App with the Store.
Specify an app name that isn't already in use.
Visual Studio updates the Package.appxmanifest file and adds a Package.StoreAssociation.xml file and a store key file with the .pfx extension to your project.
In the next step, you'll register your app with Live Connect so that you can authenticate with Microsoft accounts.
In Internet Explorer, open the Live Connect Developer Center
In the list, choose the app that you just created, choose the Edit Settings link, and then choose the API Settings link.
In the Redirect domain text box, enter the URL of the mobile service, http://YourMobileServiceName.azure-mobile.net, and then choose the Save button.
Note the Client ID and Client Secret in the next step, when you register for authentication and configure the permissions.
In the Azure management portal, choose your mobile service, and then choose the Identity tab.
In the microsoft account settings section, enter the client ID and client secret, and then choose the Save button.
Follow these steps to configure push notifications with information about your app.
See How to authenticate with the Windows Push Notification Service (WNS).
- Sign in to the Windows Store apps page of the Windows Dev Center, and then choose to edit the app that you just created.
- Choose the Services link, and then choose the Live Services site link.
- Choose the Authenticating your Service link, and find the Package Security Identifier (SID) and Client secret.
- In the Azure management portal, open your mobile service.
- On the Push tab, copy the Package SID and client secret into the appropriate places under windows application credentials, and then choose the Save button.
Run and test the sample
In Visual Studio, build the sample (Keyboard: Ctrl+Shift+B).
This step also downloads and restores the packages on which the sample depends.
Choose the Start button (Keyboard: F5) to build the solution, and then sign in with a Microsoft account when requested.
If you aren't requested to sign in, repeat items 7 through 12 in the previous procedure, Set Up Permissions and Authentication.
If a dialog box about privacy appears, choose the Yes button.
The app starts.
In the top-right corner, enter a user name in the box to create a player, and then choose the Register button.
When you sign in to TicTacToe with the same Microsoft account, you'll be signed in automatically as this player.
Before you play a game, create another player by performing one of the following sets of steps:
Close the app [Keyboard: Alt+F4], restart the app, sign in using a different Microsoft account, and then repeat the previous step with a different user name.
Install the sample on another computer or virtual machine that's running Windows 8.1, and then sign in using a different Microsoft account.
If the computer or virtual machine isn't running Visual Studio 2013, you must sideload the app. See Sideload Windows Store Apps.
You might want to start by creating both players on the same computer and, later, install the app on a different computer to test simultaneous play.
Perform the following steps to create a list of friends and then start a game with one of them:
- In the Search for user text box, enter a user name that you created, and then choose the Search button.
- In the Search Results box, choose a player, and then choose the Add Friend button.
- (Optional) Repeat the previous two steps to add more players.
- In the Opponent text box, choose a player in the list that you just created, choose New Game, make a move, and then choose the Submit Move button.
Inside the Code: Creating the mobile service client
The code for the mobile service client is in the file TicTacToeMobileServiceClient.cs and uses the .NET client library. You can code the client in a couple of ways, but you write the cleanest code by creating classes that map directly onto the tables in the database, with public members that match the columns in the data table. In this way, you can get the output of your queries directly as objects, instead of having to deserialize the query results as you'd have to do if you used the non-generic versions of the same APIs.
Each data table has an associated C# class that contains fields that map directly onto the data table.
[DataTable("games")] public class Game { public int id; public int User1; public int User2; public string Board; public int GameResult; public int CurrentPlayerIndex; public string Winner; }You can use these classes with the generic versions of the client API for the mobile service, as the following code shows. It starts a game by inserting a record in the games table.
public async Task<int> CreateGame(int userKey1, int userKey2, ITurnGame game) { Game gameObj = new Game { User1 = userKey1, User2 = userKey2, Board = game.GameBoard, GameResult = (int)game.Result, CurrentPlayerIndex = game.CurrentPlayerIndex }; // Insert a new entry in the "games" table await client.GetTable<Game>().InsertAsync(gameObj); // Return the gameID return (int) gameObj.id; }The methods that result in mobile service calls are all asynchronous, so you usually write asynchronous client methods.
Summary
Now you understand how to use a mobile service to create a simple connected app such as a turn-based game. Admittedly, tic tac toe might not be the most exciting challenge. However, you can design and create your own apps by using the sample code. You could create another turn-based game that you can play on a grid, like chess, concentration, go, or checkers. The TicTacToe class contains most of the programming that's specific to the tic-tac-toe game. The TicTacToe class implements ITurnGame, so you would need to provide a different implementation of ITurnGame to create the game of your choice.