This Toolkit is now deprecated and is now

superseded by Windows Azure Mobile Services

The Windows Azure Toolkit for Windows Phone provided developers with the first iteration of support for building backend services for Windows Phone apps using Windows Azure.  The main areas of feedback we received from mobile developers was that they wanted a turn-key set of services for common functionality such as notifications, auth, and data.   Windows Azure Mobile Services directly reflects this feedback by enabling developers to simply provision, configure, and consume scalable backend services. The downloads for this toolkit will be removed on the week of Feb 1st 2013 and all future improvements will be channeled into Windows Azure Mobile Services rather than this toolkit. 

To get started with Mobile Services, sign up for a Windows Azure account and receive 10 free Mobile Services.

This section goes through the solution generated and the steps required to explore it and run it. To watch a screencast on how to get started with the toolkit, please visit Getting Started with the Windows Azure Toolkit for Windows Phone 7 on Channel 9.

After creating a new Windows Phone Cloud Application project, perform these steps to go through the sample application generated.

Note: If you face any problems while following these steps, please make sure to review the Troubleshooting section.

Starting the Application

1. Make sure that you do not have any Web sites running in ports 443 or 10080 on your local IIS
   Note: By default, the ASP.NET MVC 3 Web Role that is generated by the project template is configured to run over two different endpoints: one HTTPS in port 443 and another HTTP in port 10080.
2. Make sure that the target for Silverlight for Windows Phone projects is set to Windows Phone Emulator.
    
   In Solution Explorer, right-click the Windows Azure project, point to Debug and click Start new instance.
3. Wait for the Web Role to start and click the Continue to this website (not recommended) link to be able to browse the site despite of the certificate warning.
   
4. To log into the Web application use the following credentials.
   • User Name: admin
   • Password: (with a zero)
5. In Solution Explorer, right-click the Windows Phone project, point to Debug and click Start new instance. This will launch the Windows Phone Emulator and start the application.
6. The application will redirect you to the log in page. Depending on the authentication mechanism selected when the application was created (ASP.NET Membership or ACS), you will get a different log in page. This is because there are some differences between ASP.NET Membership and ACS regarding the authentication flow.
   
7. In the log in page, click the Install certificate link. This will open Internet Explorer in the Windows Phone Emulator at http://127.0.0.1:10080/127.0.0.1.cer.
   
   Note: In order to consume the REST services over HTTPS in a Windows Phone device or in the Windows Phone Emulator, you need to use a trusted SSL certificate. If you do not have one, you can use a self-signed certificate, but you need to install it in the phone before consuming the services. Since the Computer Emulator always uses the 127.0.0.1 self-signed certificate, we need to install it in the Windows Phone Emulator before continuing with the next steps.
8. Click the shield icon to install the Windows Azure Compute Emulator’s SSL certificate in the Windows Phone Emulator. Finally, click install to confirm that you want to install the certificate.
   
   Important: If you leave the Windows Phone Emulator open, you do not need to install the certificate every time that you run the application. However, if you close the Windows Phone Emulator, you will have to install it again.
9. Once the certificate is installed, click ok and navigate back to the running application using the left arrow ().
   

Authenticating the User (ASP.NET Membership Authentication)

The following steps describe how the user logs in to the application configured to use ASP.NET Membership.

Note: If you selected the ACS authentication mechanism when the application was created, you should skip these steps and follow the authentication flow described in the Authenticating the user (ACS Authentication) section.

1. From the log in page of the application, click register.
2. In the register page, enter a username, e-mail and password, and then click register. Wait for the registration to complete. If the registration was successful, you will see the Registration Successful message. Click ok and you will be redirected back to the log in page.
   
   Note: The Windows Phone Emulator supports mapping of the keyboard on your development computer to the hardware keyboard on a Windows Phone (by default is not enabled). To enable the keyboard in the Windows Phone Emulator press the PAGE UP or PAUSE/BREAK key. To disable it, press the PAGE DOWN or PAUSE/BREAK key. For more information, see the following article: http://msdn.microsoft.com/library/ff754352(VS.92).aspx.
3. Back in the log in page, enter the credentials of the user you have previously created and then click log in. If the log in is successful, you will be redirected to the main pivot page.
   Note: In case you want to log in with different credentials, you need to log out by clicking the log out button () in the phone application bar, which will redirect you to the log in page.

Authenticating the User (ACS Authentication)

The following steps describe how the user logs in to the application configured to use Windows Azure Access Control Service (ACS).

Note: These steps only apply if you selected the ACS authentication mechanism when the application was created.

1. In the log in page, a list with the configured identity providers is shown. Select the identity provider you want to authenticate with and log in providing your account information.
   
   Note: Windows Live ID, Google and Yahoo identity providers are automatically configured into your ACS namespace when the application is created from the Windows Phone Cloud Application project template.
    
2. If this is the first time you logged into the application, you will be redirected to the register page. Enter a name and an email address for the user, and then click register. Wait for the registration to complete. If the registration was successful, you will see the Registration Successful message. Click ok and you will be redirected back to the log in page.
   
   Note: The Windows Phone Emulator supports mapping of the keyboard on your development computer to the hardware keyboard on a Windows Phone (by default is not enabled). To enable the keyboard in the Windows Phone Emulator press the PAGE UP or PAUSE/BREAK key. To disable it, press the PAGE DOWN or PAUSE/BREAK key. For more information, see the following article: http://msdn.microsoft.com/library/ff754352(VS.92).aspx.
   Note: In case you want to log in with different credentials, you need to log out by clicking the log out button () in the phone application bar, which will redirect you to the log in page.

Sending Microsoft Push Notifications

If you configured the application to support Microsoft Push Notifications in the Creating a New Windows Phone Cloud Application section, you will be able to send notification messages to Windows Phone devices. Follow the steps below to learn how to send Microsoft Push Notifications.

1. After the user authenticates, the notification pivot item is shown in the application. You will notice that push notifications are not enabled and therefore the connection status is disconnected.
2. Check the Enable push notifications option and wait until you see a message saying that the notification updates were received.
   
   Note: When the user enables push notifications, the application is registered with Microsoft Push Notification Service (MPNS) and the sample notification service included in this toolkit. After doing that, the application then downloads the queued messages for that Windows Phone device if there is any available. For more information about MPNS, you can read the Understanding Microsoft Push Notifications for Windows Phones and Understanding How Microsoft Push Notification Works – Part 2 articles.
3. Switch to the Web browser showing the Mobile Cloud Application Services Web site. Click the Log On link in the top-right corner.
4. To log into the Web application use the following credentials:
   • User Name: admin
   • Password: (with a zero)
5. Once logged in, additional menu options will be shown to manage user permissions to tables, blobs and queues, and to send push notifications.
   Note: The menu items displayed in the Mobile Cloud Application Services Web site may differ depending on the option you selected in the template wizard steps. For example, if you selected SQL Azure Database as the only data provider, you will not see the Tables and Queue menu items.
   
6. Click the Microsoft Push Notifications menu option, type “raw message” in the textbox for the user you have just created and click Send Raw. You will see a success message.
   
7. Now, type “tile message” in the textbox and click Send Tile. You will see an error message saying that the notification was not received by the Windows Phone device.
   Note: In order to receive tile notifications you first need to pin the application to the Windows Phone Start menu.
   
8. Switch back to the Windows Phone Emulator. You will see the raw notification message displayed in the Messages list.
   
9. Click the windows button () in the Windows Phone Emulator to navigate to the Start menu. In the Start menu, click the right arrow () to see the entire applications’ list. In the applications’ list, click the WA Toolkit WP icon and hold it for a few seconds until you see a contextual menu. In the contextual menu, click pin to start. This will redirect you back to the Start menu and you will now see the WA Toolkit WP application icon.
   
10. Switch to the Web browser and click Send Tile to send the 'tile message' notification again. You will now see a success message.
    
11. Now, type “toast message” in the textbox and click Send Toast. You will see another success message.
    
12. Switch back to the Windows Phone Emulator. You will see that the WAT Windows Phone icon now displays a number (in this case 1) and there is a toast notification available too. Click on the toast notification or the icon to open the WAT Windows Phone application. In the notifications page, you will see that both messages ('tile message' and 'toast message') are displayed in the Messages list.
    
    Note: You were not redirected to the log in page because the authentication token that you had received the first time you logged in, is stored by default in the Isolated Storage.

Sending Apple Push Notifications

If you configured the application to support Apple Push Notifications in the Creating a New Windows Phone Cloud Application section, you will be able to send notification messages to an iOS application running in an iPhone, iPad, and iPod touch devices. Follow the steps below to learn how to send Apple Push Notifications.

1. Switch to the Web browser showing the Mobile Cloud Application Services Web site.
2. If not already logged in, click the Log On link in the top-right corner. Enter the administrator credentials provisioned by default and click Log On. Once logged in, additional menu options will be shown to manage user permissions to tables, blobs and queues, and to send push notifications.
3. Click the Apple Push Notifications menu option and specify in the Device ID the id of the iOS device to send the notification to, and in the Message field, the notification message text. Finally, press Send to send the push notification.
   Note: The menu items displayed in the Mobile Cloud Application Services Web site may differ depending on the option you selected in the template wizard steps. For example, if you selected SQL Azure Database as the only data provider, you will not see the Tables and Queue menu items.
   
   Note: The push notifications can only be sent to the iPhone, iPad, and iPod touch devices running the iOS application associated to the APNS certificate that was configured when creating the Windows Phone Cloud Application.

Working with Tables, Blobs and Queues

If you configured the application to support Windows Azure Storage in the Creating a New Windows Phone Cloud Application section, you will be able to access tables, blobs and queues stored on Windows Azure. Follow the steps below to learn how to use these features.

1. Flick or pan to the left to navigate to the tables pivot item. You will see the list of available tables in your Windows Azure storage. You can click the plus button () in the application bar to add a new one and click the delete button () next to the table’s name to delete one.
   
   Note: The PushUserEndpoints, secMembership, UserPrivileges and secRole tables are internally used by the toolkit services. Therefore, if you try to delete one of them you will get an error message saying that you do not have permissions.
2. Flick or pan to the left to navigate to the sample data pivot item. You will see the rows available in the SampleData table. If this table does not exist in your Windows Azure Tables storage, it is first created.
3. In the sample data pivot item click the plus button () in the application bar to add a new row. You can also click over each of the existing rows to edit or delete them.
   
4. Flick or pan to the left to navigate to the list blobs pivot item and click the camera button () in the application bar. The phone’s camera will be open. Click the button in the top-right corner of the screen to take a photo and then click accept. This will redirect you to the upload picture page.
   
5. In the upload picture page, type the name of the container where you want to upload your picture. Notice that the autocomplete list of available containers is filtered while you type. If you type a container name that does not exist in the storage, it will be created. Additionally, if you check the Make container public option, the Container ACL will be changed to full public read access.
   
6. Type a name for the blob. Additionally, check the Include location data and Include author data options if want to include the GPS location and the user ID values as blob metadata. Finally, click upload. If everything worked as expected, you will see a message box saying that the image was successfully uploaded. Click ok to navigate back to the main pivot page.
   
7. Back in the list blobs pivot item, chose the container where have just upload the picture in the previous step, and then click list blobs (notice that you can also filter the blob name by choosing a prefix).
   
8. Wait until the blob list finishes loading. You should see a thumbnail of the picture you have previously uploaded along with a link to the blob. If you click the link, it will open Internet Explorer in the phone displaying the picture. Additionally, you can click the delete button () next to the blob’s name to delete one.
   
9. Navigate back to the running application using the left arrow ().
10. Flick or pan to the left to navigate to the queues pivot item and click list queues to see the list of available queues in your Windows Azure storage. Notice that you can also filter the queues using a prefix.
    
11. In the queues pivot item, click the plus button () in the application bar to add a new queue (notice that you can click the delete button () next to the queue’s name to delete it).
    
12. Click the name of the queue you have just created in the previous step to navigate to the queue details page.
13. In the queue details page, type 'message 1' in the textbox and click queue. Then type 'message 2' in the textbox and click queue again. Finally, click dequeue two times to get the previous messages from the queue in the right order.
    
14. Click the windows button () in the Windows Phone Emulator to navigate to the Start menu.
15. Switch to the Web browser and click the User menu option. Notice that new users (like the one you have created) have by default granted permissions to access Tables, Blobs, Queues and SQL Azure.
    
    Note: The Web Site’s administrator user (admin) is displayed in the list only if the application is configured to use ASP.NET Membership authentication, in which case the admin user is also a valid application user.
    Note: The column SQL is displayed only if the application is configured to use a SQL database.
16. Uncheck the Tables, Blobs and Queues checkboxes for the user you have created.
    
17. Click the Tables menu option. In this page, you can grant permission to each user for each of the tables available in the Windows Azure Table storage.
    
18. Click the Queues menu option. In this page, you can grant permission to each user for each of the queues available in the Windows Azure Queue storage.
    
19. Click the Blob Containers menu option. In this page, you can grant permission to each user for each of the blob containers available in the Windows Azure Blob storage.
    
20. Switch back to the Windows Phone Emulator and click the WAT Windows Phone icon to open the application again.
21. Flick or pan back to left to navigate to the tables list pivot item and then to the sample data pivot item. You will see error messages in both pages saying that you have no permissions to use tables.
    
22. Flick or pan to left to navigate to the list blobs pivot item and then click list blobs. You will also see an error message saying that you have no permissions to use blobs.
    
23. Flick or pan to left to navigate to the queues pivot item and then click list queues. You will see an error message saying that you have no permissions to use queues.
    

Working with SQL Azure Database

If you configured the application to support SQL Azure Database in the Creating a New Windows Phone Cloud Application section, you will be able access an OData service on top of a SQL Azure database. Follow the steps below to learn how to use these features.

Note: The application uses Entity Framework 4.1 Code First, in order to create the needed database tables. By default, a database will be created in the SQL Azure server with the same name as the base project name used during the template wizard creation. In order to allow Entity Framework Code First to re-create the needed database tables when the model changes, it is necessary to add Persist Security Info=True to the connection string. This setting may not be suitable for production environments and you should consider removing it from your deployed applications.

1. Flick or pan to the left to navigate to the sql azure data pivot item. You will see the rows available in the SqlSampleData table.
   
   Note: The PushUserEndpoints, secMembership, UserPrivileges and secRole tables are internally used by the toolkit services. Therefore, if you try to delete one of them you will get an error message saying that you do not have permissions.
2. Click the windows button () in the Windows Phone Emulator to navigate to the Start menu.
3. Switch to the Web browser and click the User menu option. Notice that new users (like the one you have created) have by default granted permissions to access Tables, Blobs, Queues and SQL Azure.
   
   Note: The Web Site’s administrator user (admin) is displayed in the list only if the application is configured to use ASP.NET Membership authentication, in which case the admin user is also a valid application user.
   Note: The columns Tables, Blobs and Queues are displayed only if the application is configured to use Windows Azure Storage.
4. Uncheck the SQL checkbox for the user you have created.
   
5. Switch back to the Windows Phone Emulator and click the WAT Windows Phone icon to open the application again.
6. Flick or pan back to left to navigate to the sql azure data pivot item. You will see an error message in the page saying that you have no permissions to use SQL Azure.
   

Next step: BabelCam