Shelly Guo @ MS

Powering your Windows 8 apps and websites with Microsoft accounts

2012-12-26T23:45:41Z

With the release of Windows 8 and the new app distribution channel through the Windows Store, developers now are embracing a completely new and different programming model. One of the often under-looked features in this new ecosystem is the ability for applications and websites to leverage users’ Microsoft accounts to provide personalized content without ever prompting the user to sign in. For client only apps, using SSO along with other Windows services such as Profile allows app developers to easily access user’s information and provide customized experiences without requiring additional user gesture. Apps can also leverage the 7GB free cloud storage that every Windows user has to store information in SkyDrive that is accessible from any platform. For websites or apps that have a server component, implementing SSO becomes even more compelling because now you can deliver personalized content to your users without having your own identity system. Even if you already have an identity system on your website, you can still benefit from SSO because with the support from the OS, the sign in and sign up experiences become much more seamless.

The Live SDK is a set of client APIs that make integrating with MSA and Windows services simple and straightforward. The V5.3 version of the Live SDK was recently released which includes updated Windows 8 SDKs and brand new .Net SDKs for classic desktop apps and Asp.Net apps. In this post, I will talk about how to use these SDKs to implement Single-sign-on (SSO) using Microsoft accounts (MSA) for Windows Store apps and Asp.Net websites. (I choose to talk about Asp.Net websites purely because we have an existing SDK for it. The concept though applies to websites implemented using other technologies as well.) If you want to take an in-depth look at the benefits and the technology used in SSO on Windows, check out the //BUILD2012 talk on this topic. For those who just want to get start on code, it is my hope that content in this post would help you get right on track.

Pre-requisite

Windows 8 and Visual Studio 2012.
Live SDK V5.3

Implementing SSO for Windows Store apps

Implementing SSO for a Windows Store app is very straightforward. Follow the following steps and you’ll be done in 5 minutes.

1. Create a new Windows Store C# app called HelloWorldWin8 in Visual Studio 2012.

2. Bring up the Add Reference dialog, fine the Windows/Extensions tab and add Live SDK to the project.

3. Add an image control and a textbox control to the main page. The image control will be used to display the user’s profile picture and the textbblock will be used to show a greeting message. The complete XAML is shown below:

<Page
    x:Class="HelloWorldWin8.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:HelloWorldWin8"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d">

    <Grid Background="{StaticResource ApplicationPageBackgroundThemeBrush}">
        <Image x:Name="imgMe" HorizontalAlignment="Left" Height="150"  Width="150" 
Margin="230,330,0,0" VerticalAlignment="Top" />
        <TextBlock x:Name="tbGreeting" HorizontalAlignment="Left" Margin="450,350,0,0" 
VerticalAlignment="Top" Height="50" Width="823" FontSize="32"/>
        <TextBlock x:Name="tbError" HorizontalAlignment="Left" Margin="230,560,0,0" TextWrapping="Wrap" 
VerticalAlignment="Top" Height="175" Width="1043"/>
    </Grid>
</Page>

4. Add the following code to mainpage.xaml.cs.

    using System;

    using System.Collections.Generic;

    using Windows.UI.Xaml.Controls;

    using Windows.UI.Xaml.Media.Imaging;

    using Windows.UI.Xaml.Navigation;

    using Microsoft.Live;

    // The Blank Page item template is documented at http://go.microsoft.com/fwlink/?LinkId=234238

    namespace HelloWorldWin8

    {

        /// <summary>

        /// An empty page that can be used on its own or navigated to within a Frame.

        /// </summary>

        public sealed partial class MainPage : Page

        {

            private static string[] scopes = new string[] { "wl.signin wl.basic" };

            private LiveAuthClient authClient;

            public MainPage()

            {

                this.InitializeComponent();

                this.authClient = new LiveAuthClient();

            }

            /// <summary>

            /// Invoked when this page is about to be displayed in a Frame.

            /// </summary>

            /// <param name="e">Event data that describes how this page was reached.  The Parameter

            /// property is typically used to configure the page.</param>

            protected override void OnNavigatedTo(NavigationEventArgs e)

            {

                this.SignInUser();

            }

            private async void SignInUser()

            {

                try

                {

                    var loginResult = await this.authClient.InitializeAsync(new List<string>(scopes));

                    if (loginResult.Status == LiveConnectSessionStatus.Connected)

                    {

                        this.GetMe();

                    }

                    else

                    {

                        loginResult = await this.authClient.LoginAsync(new List<string>(scopes));

                        if (loginResult.Status == LiveConnectSessionStatus.Connected)

                        {

                            this.GetMe();

                        }

                    }

                }

                catch (LiveAuthException e)

                {

                    this.tbError.Text = e.ToString();

                }

            }

            private async void GetMe()

            {

                try

                {

                    var connectClient = new LiveConnectClient(this.authClient.Session);

                    this.imgMe.Source = new BitmapImage()

                    {

                        UriSource = new Uri("https://apis.live.net/v5.0/me/picture?access_token=" + this.authClient.Session.AccessToken)

                    };

                    var getResult = await connectClient.GetAsync("me");

                    dynamic jsonResult = getResult.Result;

                    this.tbGreeting.Text = "Hello " + jsonResult.first_name + " " + jsonResult.last_name;

                }

                catch (LiveConnectException e)

                {

                    this.tbError.Text = e.ToString();

                }

            }

        }

    }

5. Provision your app to use Live Connect services. Make sure you have a valid Windows Store developer license. Go to Store –> Create App Packages from the Visual Studio menu (in the Ultimate version, this menu item is under Project –> Store –> Create App Packages), sign in and follow the steps to create a new Windows Store app.

6. Run the application. Upon app start, you will be prompted to give the app permission to access your data. Click Yes. Your profile picture should then appear along with a message that greets you by your name.

7. Now you’re set up to use Microsoft accounts in your app, you can then add SkyDrive support by using our SkyDrive API. To learn more about how to work with SkyDrive, check out our //BUILD2012 talk “The developer’s guide to the SkyDrive API” by Deepesh Mohnani.

Integrate Microsoft account and Windows services in your website

You can also integrate with Microsoft account in your website to use MSA as your identity system or to interact with user data stored in SkyDrive and other Windows services. With the introduction of the new Asp.Net SDK, we’ve made this a much easier task than it used to be.

To show you how to user the Asp.Net SDK to authenticate the user using MSA, I’m going to use the project I created for the BUILD talk as my code sample here. It would be easier to walk through the code if you open the project in Visual Studio. So here’s how you would set it up:

First download the project files and open the solution file YummySample.sln. Notice that there are two projects in the solution, one YummyWin8App and YummyWebsite. These two projects are designed to work with each other to demonstrate the interactions between your app and your companion website.
Open the Win8 app project and follow the steps above to register this app with the Windows Store.
While you’re still in the Windows Store developer portal, select your application, click on “Advanced features” –> “Push notifications and Live Connect services info” –> “Representing your app to Live Connect users”. Enter “http://www.yummywebsite.com" as the redirect domain for your app. As an optional step, upload a logo.

Click the “Authenticating your service” link on the left nav and note down the two values on this page: Package Security Identifier (PSID) and Client secret.

Go back to Visual Studio, open YummyWebsite –> Controllers –> HomeController.cs file and copy the values of your app’s client id (the PSID) and client secret to the corresponding variables at the top of the file. Do the same for the AccountControll.cs file.
Next, you need to configure you website on your local IIS server. Go to IIS Manager, add a new website call “YummyWebsite” and configure it to point to where your copied the project files to on your local file system. Set the host name to be “http://www.yummywebsite.com”.

Add a host entry in your hosts file that points to your local IIS.

127.0.0.1 www.yummywebsite.com

Now you should be set up to run the sample. Make sure you’re logged in to the OS with either a Microsoft account or a MSA connected domain/local account. In IE10, browse to http://www.yummywebsite.com and see the web page loads with pictures of yummy food. Notice there is no personal information displayed on the page.
Click the Register link at the upper right corner. This takes you to a page where the website asks you to register for an account. For the simplicity of the sample, the registration logic is not implemented. The purpose of this page is to serve as a proof-of-concept that you can streamline sign-up with information about the user and make the process much less intimidating.
Once you click the Register button, it takes you back to the home page where you now will see your name and profile picture show up at the upper right corner. You have now signed in to the website using your MSA.

Now let’s take a look at the code for the home controller:

    public async Task<ActionResult> Index()

            {

                HomePageModel model = new HomePageModel();

                model.Pictures = this.GetPictures();

                model.Favorites = new List<string>();

                model.ProfileImageUrl = "Images/user.png";

                #region LiveSDK Impl

                HttpCookie stateCookie = this.Request.Cookies["state"];

                if (stateCookie == null || string.Compare(stateCookie.Value, "registered", true) != 0)

                {

                    return View(model);

                }

                LiveLoginResult loginResult = await this.authClient.InitializeWebSessionAsync(this.HttpContext);

                if (loginResult != null && loginResult.Status == LiveConnectSessionStatus.Connected)

                {

                    model.LoginUrl = "";

                    model.ProfileImageUrl = "https://apis.live.net/v5.0/me/picture?access_token=" + loginResult.Session.AccessToken;

                    var connectClient = new LiveConnectClient(loginResult.Session);

                    var getResult = await connectClient.GetAsync("me");

                    var jsonResult = getResult.Result as dynamic;

                    model.UserName = jsonResult.first_name + " " + jsonResult.last_name;

                    model.Favorites = this.GetFavorites(loginResult.Session.AuthenticationToken);

                }

                else if (loginResult != null &&

                    loginResult.Status == LiveConnectSessionStatus.Unknown || loginResult.Status == LiveConnectSessionStatus.Expired)

                {

                    Dictionary<string, string> options = new Dictionary<string, string>();

                    options.Add("display", "none");

                    string reAuthUrl = this.authClient.GetLoginUrl(new List<string>(scopes), options);

                    return new RedirectResult(reAuthUrl);

                }

                else

                {

                    model.LoginUrl = this.authClient.GetLoginUrl(new List<string>(scopes));

                    model.ProfileImageUrl = "Images/user.png";

                }

                #endregion

                return View(model);

            }

The line of code that I want to highlight is this:

LiveLoginResult loginResult = await this.authClient.InitializeWebSessionAsync(this.HttpContext);

The LiveAuthClient.InitializeWebSessionAsync function is the main function that handles the web authentication flow for OAuth 2.0. If the user has 1) signed in to MSA either through the OS for IE or through the web for any browsers that support cookies; 2) granted permission for the app to access his information, the user will be signed in to your website and you can go ahead with retrieving user information from Windows services.

If the user’s status is not Connected, it means either the user is not signed or the user has not given the app permission to access his data. In these cases, the app needs to call LiveAuthClient.GetLoginUrl to get the url for the sign-in/consent page and redirect the browser to that page so the user can finish the sign-in flow.

Notice that at the top of the HomeController.cs file, we specify the value for redirectUrl as

private static string redirectUrl = "http://www.yummywebsite.com/home/login";

How is this used? The OAuth web flow is a two step authentication process. When the user grants consent to the web app, the authentication server sends a authorization code to the application web server (http://www.yummywebsite.com) and the application web server needs to exchange this code for the access token that it needs for retrieving data from the resource provider (https://apis.live.net). The redirect url tells the authentication server where to send the authorization code to. You can use the default path to handle redirect, but we recommend that you use a separate path or a different controller for the sole purpose of handling OAuth redirect. It makes to code easier to read and maintain. In my example, I’m using the path /home/login to handle the redirect.

The AccountController class handles the /account/register path. The logic here is similar to that of the home controller. Notice the code below:

Dictionary<string, string> options = new Dictionary<string, string>();
options.Add("state", "register");
string reAuthUrl = authClient.GetLoginUrl(new List<string>(scopes), options);
return new RedirectResult(reAuthUrl);

Here we’re getting the login url by calling LiveAuthClient.GetLoginUrl. A ‘state’ parameter is added to the login url to track the current navigation state and the user is taking to the MSA login or consent page when the browser gets redirected to the login url.

Tracking user on your website and providing personalized content

So far, I have not talked about how to link the Win8 app and the website together and have SSO work across the two. I will devote this section for that purpose. First let’s talk about SSO across the app and the website. The promise here is if you are signed in to the app on a connected windows device, you’re also signed in to the website and vice versa. To see how it works, now run the YummyWin8 app again. You will notice that after the app initializes, your name and profile pictures shows up at the upper right corner. This is because you’ve already given the app permission to sign in when you went through the registration process on the website. The app now can automatically sign you in when it starts.

Now you have SSO between the app and the website, we can then talk about tracking users and providing personalized content. The key that provides the link between the app and the website in terms of user tracking is a ticket that’s known as the “Authentication Token”. So far, when we talk about authentication and authorization through OAuth, we talk about the “access token”. An access token is a ticket that the authentication server gives to the application for accessing data from a resource provider. In most cases, the resource provider is owned by the same entity that owns the authentication server. For example, the SkyDrive API service is a resource provider that accepts Microsoft account’s OAuth access token. The authentication token on the other hand, is a ticket that is understood by the application website, i.e. your website. This ticket contains a unique user id that your app can use to identify the user. The ticket is encrypted using the application secret that only your app knows about, therefore only understood by your app. Once you are able to uniquely identify your user, you have the foundation for providing personalized content. You can use this unique user id as key into your database, or any other way you choose to store user information.

The authentication token is exposed as the AuthenticationToken property on the LiveConnectSession object. Note that this property is only set if the application has a redirect domain registered. Apps that don’t have a server-side component have no use of this token.

To decrypt the authentication token, you need your app’s client secret. The authentication token is encrypted with your client secret using the standard JWT format. Because only your web server has access to the client secret, you must send the authentication token to your website for decryption. We ask that under no circumstances, client secret should be store on user machines. The Asp.Net SDK provides a utility method to decrypt the token and extract the user id. You can call LiveAuthClient.GetUserId and pass in the authentication token. The return value is the unique user id you can use to identify the current user.

The “Add to favorites” functionality in the sample app leverages the authentication token to store user favorites on the server. You can easily expand this to include any personalized content you want to build for your app. To see how the favorites functionality work in this sample, follow these steps:

Start the website by going to http://www.yummywebsite.com
Run the YummyWin8 app.
Click on a couple pictures and see them being selected.
Click the “Add to favorites” header.
Notices the favorites being added to the favorites column.
Go back to the website and refresh the page. Notice the favorites also show up on the website.

How does this work? It works with the Win8 app sending the authentication token along with the list of user favorites to the web server. The website then decrypts the token, gets the unique user id and stores the favorites list for this user. The website can also display the favorites by getting its own authentication token, decrypts it and then retrieve the favorites list for the current user.

That’s it. You have set up the foundation to power your app and your website with Microsoft accounts and Windows services. Now it’s up to you to create the most awesome app for the new Windows ecosystem and good luck!

Get Started on Live SDK for Windows Phone 7.x

2012-12-26T18:10:03Z

[Update on 12/27/2012] If you’re looking for the starter guide for Live SDK on Windows Phone 8, please refer to this post. If you’re looking for the starter guide for Live SDK on Windows 8 or Asp.Net, please refer to this post.

[Update on 4/17/2012] We now have an iOS SDK and an Android SDK as well. Check it out! The 5.1 release is now live on Live Connect Developer Center. This release fixes some known issues with the 5.0 release. It also include a version of the SDK for Windows 8 that’s compatible with the Windows 8 Consumer Preview.

Live Connect provides developers a set of controls and APIs that enable applications to integrate sign in with the user’s Microsoft account and enable users to access information from SkyDrive, Hotmail, and Messenger. In my previous posts, I talked about how to integrate Live Connect using the Live SDK in Metro style apps written in JavaScript and in Metro style apps written in C#. If you’re a Windows Phone developer, the same SDK also supports integrating Live Connect in a Windows Phone app. In this post, I will walk through the steps for creating a simple Live Connect powered Windows Phone application.

A few words on the behind the scene stuff before I start the step-by-step guide. When building Metro style apps on Windows 8 Consumer Preview, Single-Sign-On (SSO) is achieved with support from the OS. On Windows Phone, however, such support is not available for third party apps. To provide a good sign-in experience on mobile devices, Live Connect allows a mobile client to obtain a refresh token and use it to exchange for an access token. This provides a way for mobile clients to implement a Sign-In-Once experience and avoid the need to ask user for password every time the app is activated. To opt-in for this experience, your app needs to satisfy two criteria:

The app must be provisioned as a mobile app.
User must grant the app offline access permission.

We will discuss the details on how to meet these two criteria in the following step-by-step guide.

Pre-requisite:

Download and install the latest Windows Phone Developer Tools from App Hub.
Download and install Live SDK.

Let’s start by creating a new Windows Phone application.

1. Create a new HelloWorldPhone Windows Phone application in Microsoft Visual Studio 2010 or Microsoft Visual Studio 2010 Express for Windows Phone using the Visual C# -> Silverlight for Windows Phone -> Windows Phone Application project template.

2. Bring up the Add Reference dialog and go to the .Net tab. Scroll down to find the Microsoft.Live and Microsoft.Live.Controls assemblies. Add them to your project.

The SignInButton control should now show up in your toolbox.

4. Drag the SignInButton onto your designer surface. In your xaml file, change the generated xml for the SignInButton to the following:

<my:SignInButton Name="btnLogin" HorizontalAlignment="Left" Scopes="wl.signin wl.basic wl.offline_access"

SessionChanged="btnLogin_SessionChanged" />

5. Add a couple TextBlock elements to display the greeting and the error message (in case something goes wrong). Here’s the complete xaml for MainPage.xaml.

<phone:PhoneApplicationPage 
    x:Class="HelloWorldPhone.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:phone="clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone"
    xmlns:shell="clr-namespace:Microsoft.Phone.Shell;assembly=Microsoft.Phone"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d" d:DesignWidth="480" d:DesignHeight="768"
    FontFamily="{StaticResource PhoneFontFamilyNormal}"
    FontSize="{StaticResource PhoneFontSizeNormal}"
    Foreground="{StaticResource PhoneForegroundBrush}"
    SupportedOrientations="Portrait" Orientation="Portrait"
    shell:SystemTray.IsVisible="True" xmlns:my="clr-namespace:Microsoft.Live.Controls;assembly=Microsoft.Live.Controls">

    <!--LayoutRoot is the root grid where all page content is placed-->
    <Grid x:Name="LayoutRoot" Background="Transparent">
        <Grid.RowDefinitions>
            <RowDefinition Height="129"/>
            <RowDefinition Height="639*"/>
        </Grid.RowDefinitions>

        <!--TitlePanel contains the name of the application and page title-->
        <StackPanel x:Name="TitlePanel" Margin="12,17,0,0">
            <TextBlock x:Name="ApplicationTitle" Text="Hello World" Style="{StaticResource PhoneTextNormalStyle}"/>
            <my:SignInButton Name="btnLogin" Scopes="wl.signin wl.basic wl.offline_access" SessionChanged="btnLogin_SessionChanged" HorizontalAlignment="Left" />
        </StackPanel>

        <!--ContentPanel - place additional content here-->
        <Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
            <TextBlock Name="tbGreeting" FontSize="40" Height="80" HorizontalAlignment="Left" Margin="20,30,0,0" Text="Hello" VerticalAlignment="Top" Width="418" />
            <TextBlock Name="tbError" FontSize="24" Height="80" HorizontalAlignment="Left" Margin="20,130,0,0" Text="No Errors." VerticalAlignment="Top" Width="418" />
        </Grid>
    </Grid>

</phone:PhoneApplicationPage>

6. Add the following code in your MainPage.xaml.cs file.

using System;
using Microsoft.Phone.Controls;

using Microsoft.Live;
using Microsoft.Live.Controls;

namespace HelloWorldPhone
{
    public partial class MainPage : PhoneApplicationPage
    {
        private LiveConnectClient liveClient;
        
        public MainPage()
        {
            InitializeComponent();
        }

        private void btnLogin_SessionChanged(object sender, LiveConnectSessionChangedEventArgs e)
        {
            if (e != null && e.Status == LiveConnectSessionStatus.Connected)
            {
                this.liveClient = new LiveConnectClient(e.Session);

                this.GetMe();
            }
            else
            {
                this.liveClient = null;
                this.tbError.Text = e.Error != null ? e.Error.ToString() : string.Empty;
            }
        }

        private void GetMe()
        {
            this.liveClient.GetCompleted += OnGetMe;
            this.liveClient.GetAsync("me", null);
        }

        private void OnGetMe(object sender, LiveOperationCompletedEventArgs e)
        {
            this.liveClient.GetCompleted -= OnGetMe;
            if (e.Error == null)
            {
                string firstName = e.Result.ContainsKey("first_name") ? e.Result["first_name"] as string : string.Empty;
                string lastName = e.Result.ContainsKey("last_name") ? e.Result["last_name"] as string : string.Empty;

                this.tbGreeting.Text = "Welcome " + firstName + " " + lastName;
            }
            else
            {
                this.tbError.Text = e.Error.ToString();
            }
        }
    }
}

Before proceeding, let’s take a look at what the above code does.

The xaml definition of the SignInButton control specifies the scopes that the app needs to ask user permissions for. We’re including 3 scopes here: wl.sign, wl.basic and wl.offline_access. Together these 3 scopes give the app access to user’s basic profile information and allows the app to access data even when the user is not actively using the app. For more information on Live Connect scopes, read here. In addition, the documentation you can download from the Live SDK download site includes updated information on this release.
The xaml definition also adds an event handler for the SessionChanged event on the SignInButton. This event is fired when the sign-in process has finished.
If access is granted and the LiveConnectSession object indicates the LiveConnectSessionStatus as Connected, a new instance of the LiveConnectClient class is created with the current Session object.
In the function GetMe(), the code talks to the Live Connect REST API to retrieve user’s basic profile information by calling LiveConnectClient.GetAsync on “me”.
When the result comes back, the GetCompleted event on LiveConnectClient is fired, the app can then obtain user’s first and last names through the e.Result IDictionary object.

7. Before you can run the app, you need to provision it with Live Connect. Go to the application management site and click the Create Application link. Create an application called HelloWorldPhone.

8. After you click “I accept”, an application is created for you with a client id and a client secret (values removed for discretion).

9. Go to Application Settings Page and click on the API Settings tab. Check “Yes” for “Mobile client app” and save.

10. The app is now provisioned and ready to go. Go back to your MainPage.xaml, and add the ClientId property on the SignInButton.

<my:SignInButton Name="btnLogin" ClientId="[Your Client ID here]" HorizontalAlignment="Left" SessionChanged="btnLogin_SessionChanged" Scopes="wl.signin wl.basic wl.offline_access" />

11. You’re done. Hit F5 and run the app in the emulator. Click the “Sign In” button and type in a username and password to sign into Windows Live. Next you will see a screen asking user permission to access data.

13. Click Yes. Notice that the SignInButton has changed to “Sign Out” state and a greetings with your name is displayed.

14. At this point, the app can continue to access user data until user signs out or until the refresh token is expired. A refresh token is valid for one year and is reset every time a new access token is issued. The user will not be asked for credentials again as long as the app is activated at least once a year.

For more Live Connect code samples, visit our github site at https://github.com/liveservices/livesdk.

Get started on Live SDK for Windows Phone

2011-09-20T05:35:10Z

[Update on 12/26/2012] Live SDK 5.3 is now available on Live Connect Developer Center! Many new features in this release, most notably new .Net SDKs for both classic desktop and Asp.Net. It also include an updated Windows Phone SDK targeting the new Windows Phone 8. Even better, all our SDKs including the Windows and Windows Phone SDKs are now open source. Check out our LiveServices github depot, download the source code and party. This post is now updated to use code samples for Windows Phone 8. If you are looking for the starter guide for Windows Phone 7.x, please refer to the older post.

Live Connect provides developers a set of controls and APIs that enable applications to integrate sign-in with the user’s Microsoft account and access user information stored in Windows services such as SkyDrive and Hotmail. In this post, I will walk through the steps for creating a simple Live Connect powered Windows Phone application. Once you get you app started with the basic stuff, you can move on to learn more about our SkyDrive API and how to use it to cloud power your application.

A few words on the behind the scene stuff before I start the step-by-step guide. When building Windows Store apps on Windows 8, Single-Sign-On (SSO) is achieved with support from the OS. (To learn more about how to implement SSO for Windows Store apps, check out our //BUILD 2012 talk or my blog post for “Powering your apps and websites with Microsoft accounts”.) On Windows Phone, however, such support is not available for third party apps. To provide a good sign-in experience on mobile devices, Live Connect allows a mobile client to obtain a refresh token and use it to exchange for an access token. This provides a way for mobile clients to implement a Sign-In-Once experience and avoid the need to ask user for password every time the app is activated. To opt-in for this experience, your app needs to satisfy two criteria:

The app must be provisioned as a mobile app.
User must grant the app offline access permission.

We will discuss the details on how to meet these two criteria in the following step-by-step guide.

Pre-requisite:

Download and install the latest Windows Phone Developer Tools from Windows Phone developer center.
Download and install Live SDK.

Let’s start by creating a new Windows Phone application.

2. Bring up the Add Reference dialog and go to the Assemblies –> extensions tab. Find the Microsoft.Live and Microsoft.Live.Controls assemblies. Add them to your project.

3. Open MainPage.xaml in the designer. Bring the Toolbox in view and right-click to select Choose Items… Under Windows Phone Components tab, find the SignInButton control in the Microsoft.Live.Control namespace and add to your toolbox (You only need to do this once). You will see two entries here, choose the one that’s for Windows Phone 8 by examining the directory of the component dll. It should be something like C:\Program Files (x86)\Microsoft SDKs\Live\v5.0\Windows Phone 8.0\References.

The SignInButton control should now show up in your toolbox.

4. Drag the SignInButton onto your designer surface. In your xaml file, change the generated xml for the SignInButton to the following:

<Controls:SignInButton Name="btnLogin" Scopes="wl.signin wl.basic wl.offline_access"

SessionChanged="btnLogin_SessionChanged" HorizontalAlignment="Left" Margin="155,217,0,0" VerticalAlignment="Top"/>

5. Add a couple TextBlock elements to display the greeting and the error message (in case something goes wrong). Here’s the complete xaml for

    <phone:PhoneApplicationPage

        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"

        xmlns:phone="clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone"

        xmlns:shell="clr-namespace:Microsoft.Phone.Shell;assembly=Microsoft.Phone"

        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"

        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"

        xmlns:Controls="clr-namespace:Microsoft.Live.Controls;assembly=Microsoft.Live.Controls"

        x:Class="HelloWorldPhone.MainPage"

        mc:Ignorable="d"

        FontFamily="{StaticResource PhoneFontFamilyNormal}"

        FontSize="{StaticResource PhoneFontSizeNormal}"

        Foreground="{StaticResource PhoneForegroundBrush}"

        SupportedOrientations="Portrait" Orientation="Portrait"

        shell:SystemTray.IsVisible="True">

        <!--LayoutRoot is the root grid where all page content is placed-->

        <Grid x:Name="LayoutRoot" Background="Transparent">

            <Grid.RowDefinitions>

                <RowDefinition Height="Auto"/>

                <RowDefinition Height="*"/>

            </Grid.RowDefinitions>

            <!--TitlePanel contains the name of the application and page title-->

            <StackPanel x:Name="TitlePanel" Grid.Row="0" Margin="12,17,0,28">

                <TextBlock Text="Hello World" Margin="9,-7,0,0" Style="{StaticResource PhoneTextTitle1Style}"/>

            </StackPanel>

            <!--ContentPanel - place additional content here-->

            <Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">

                <Controls:SignInButton ClientId="[Enter your Client ID]" Scopes="wl.signin wl.basic wl.offline_access" HorizontalAlignment="Left" Margin="10,10,0,0" VerticalAlignment="Top" SessionChanged="btnLogin_SessionChanged"/>

                <TextBlock x:Name="tbGreeting" Text="Hello " HorizontalAlignment="Left" Margin="24,149,0,0" TextWrapping="Wrap" VerticalAlignment="Top" Height="82" Width="394" FontSize="36"/>

                <TextBlock x:Name="tbError" HorizontalAlignment="Left" Margin="24,397,0,0" TextWrapping="Wrap" VerticalAlignment="Top" Height="82" Width="394" FontSize="36"/>

            </Grid>

        </Grid>

    </phone:PhoneApplicationPage>

6. Add the following code in your MainPage.xaml.cs file.

    using System;

    using Microsoft.Phone.Controls;

    using Microsoft.Live;

    using Microsoft.Live.Controls;

    namespace HelloWorldPhone

    {

        public partial class MainPage : PhoneApplicationPage

        {

            private LiveConnectClient liveClient;

            public MainPage()

            {

                InitializeComponent();

            }

            private void btnLogin_SessionChanged(object sender, LiveConnectSessionChangedEventArgs e)        

            {            

                if (e != null && e.Status == LiveConnectSessionStatus.Connected)            

                {                

                    this.liveClient = new LiveConnectClient(e.Session);                

                    this.GetMe();            

                }            

                else            

                {                

                    this.liveClient = null;                

                    this.tbError.Text = e.Error != null ? e.Error.ToString() : string.Empty;            

                }        

            }        

            private async void GetMe()        

            {

                try

                {

                    LiveOperationResult operationResult = await this.liveClient.GetAsync("me");

                    var jsonResult = operationResult.Result as dynamic;

                    string firstName = jsonResult.first_name ?? string.Empty;

                    string lastName = jsonResult.last_name ?? string.Empty;

                    this.tbGreeting.Text = "Welcome " + firstName + " " + lastName;

                }

                catch (Exception e)

                {

                    this.tbError.Text = e.ToString();

                }

            }

        }

    }

Before proceeding, let’s take a look at what the above code does.

The xaml definition of the SignInButton control specifies the scopes that the app needs to ask user permissions for. We’re including 3 scopes here: wl.sign, wl.basic and wl.offline_access. Together these 3 scopes give the app access to user’s basic profile information and allows the app to access data even when the user is not actively using the app. For more information on Live Connect scopes, read here.
The xaml definition also adds an event handler for the SessionChanged event on the SignInButton. This event is fired when the sign-in process has finished.
If access is granted and the LiveConnectSession object indicates the LiveConnectSessionStatus as Connected, a new instance of the LiveConnectClient class is created with the current Session object.
In the function GetMe(), the code talks to the Live Connect REST API to retrieve user’s basic profile information by calling LiveConnectClient.GetAsync on “me”.LiveConnectClient.Async is implemented as an async operation using the Task async pattern. use the keyword “await” to call this API.
When the result comes back, the app can then obtain user’s first and last names through the operatonResult.Result IDictionary object. In this example, we cast operationResult.Result to a “dynamic” object so you can access the dictionary values through the .key syntax.

7. Before you can run the app, you need to provision it with Live Connect. Go to the application management site and click the Create Application link. Create an application called HelloWorldPhone.

8. After you click “I accept”, an application is created for you with a client id and a client secret (values removed for discretion).

9. Go to Application Settings Page and click on the API Settings tab. Check “Yes” for “Mobile client app” and save.

10. The app is now provisioned and ready to go. Go back to your MainPage.xaml, and add the ClientId property on the SignInButton.

<my:SignInButton Name="btnLogin" ClientId="[Your Client ID here]" HorizontalAlignment="Left" SessionChanged="btnLogin_SessionChanged" Scopes="wl.signin wl.basic wl.offline_access" />

13. Click Yes. Notice that the SignInButton has changed to “Sign Out” state and a greetings with your name is displayed.

For more Live Connect code samples, visit our github site at https://github.com/liveservices/livesdk.

A Step-by-step guide to creating your first Hello World Metro style app using Live Connect, in C#

2011-09-16T13:29:00Z

In my previous post, I showed how to create a Live Connect powered Windows Metro style app using JavaScript. In this post, I will go through the steps for creating the same app using C#.

If you’re a VB developer, follow the same steps in this post but change the code behind to use VB.

If you’re a Windows Phone developer, this post is for you.

If you haven’t downloaded and installed the Windows Developer Preview, you got to check it out. It’s a brand new Windows unlike anything before.

If you haven’t downloaded and installed the Live SDK, please do that before taking the following steps. Sign up for the Live Connect technical preview, download and install the LiveSDK.msi.

Sign into your new PC using a Live ID account. If you must use a domain account or a local account, you can connect your domain or local account to a Live ID account through Control Panel -> Users, click “Connect your Windows Live ID” and following the instructions.

Now you’re ready. Let’s write our first Metro style app in C# together.

The Managed application UI framework for Metro style apps carries forward the WPF programming paradigm that most .Net UI developers are familiar with. Application UI is defined in XAML and business logic is implemented in code behind using managed languages like C# and VB. If you’ve worked with WPF or Silverlight, this should be very intuitive to you. With that said, let see how we can add Live Connect to your app.

1. Start Visual Studio 11 Express and create a new project called HelloWorldCSharp. Choose the Visual C# -> Windows Metro style -> Application project template.

2. Bring up the “Add Reference” dialog and choose “Live SDK for Windows Metro style XAML applications” under the Windows -> Extension SDKs tab. Click “Add” and then “Close”. Notice that a reference to LiveSDKXAML SDK is added to you project.

3. Now open the MainPage.xaml file. Add the following attribute to the root UserControl tag

xmlns:live="using:Microsoft.Live.Controls"

This adds a namespace declaration for the sign-in control we will be using in this xaml file.

4. In the root <Grid> element, add a Canvas control that hosts the sign-in button and two TextBlock controls.

<Grid x:Name="LayoutRoot" Background="#FF0C0C0C">
  <Canvas HorizontalAlignment="Left" Height="217" Margin="100,100,0,0" VerticalAlignment="Top" Width="742">
    <live:SignInButton Name="btnSignin" Scopes="wl.signin wl.basic" Margin="100,20,0,0" Foreground="White" Background="Black" />
    <TextBlock Name="tbGreeting" Margin="100,100,0,0" Text="" Width="300" Height="50" FontSize="32"/>
    <TextBlock Name="tbError" Margin="100,150,0,0" Text="" Width="300" Height="50" FontSize="32"/>
  </Canvas>
</Grid>

You will notice that adding the SignInButton control causes the designer to invalidate the xaml and fail to load. Unfortunately this is an issue that cannot be resolved in the Windows Developer Preview build of Visual Studio. Design time support for custom control is still absent in VS. To work around that, I replace the SignInButton with a regular Button control, do my design work and then replace the SignInButton back when I’m ready to run the app.

You will also notice that I have added the Scopes attribute to the SignInButton. The value “wl.signin wl.basic” indicates that this app will ask the user for permission to access his basic profile information. For more information about different scopes supported by Live Services, visit here.

5. Once we have the markup, now let’s go to MainPage.xaml.cs and add some code. This is what I have:

       1: using System;

       2:  

       3: using Microsoft.Live;

       4: using Microsoft.Live.Controls;

       5:  

       6: namespace HelloWorldCSharp

       7: {

       8:     partial class MainPage

       9:     {

        private LiveConnectClient liveClient;

 

        public MainPage()

        {

            InitializeComponent();

            this.btnSignin.SessionChanged += OnSessionChanged;

        }

 

        private void OnSessionChanged(object sender, LiveConnectSessionChangedEventArgs e)

        {

            if (e.Session != null && e.Session.Status == LiveConnectSessionStatus.Connected)

            {

                this.liveClient = new LiveConnectClient(e.Session);

 

                this.GetMe();

            }

            else

            {

                this.liveClient = null;

            }

        }

 

        private void GetMe()

        {

            this.liveClient.GetCompleted += OnGetMe;

            this.liveClient.GetAsync("me", null);

        }

 

        private void OnGetMe(object sender, LiveOperationCompletedEventArgs e)

        {

            this.liveClient.GetCompleted -= OnGetMe;

            if (e.Error == null)

            {

                dynamic result = e.Result;

                this.tbGreeting.Text = "Hello " + result.first_name + " " + result.last_name;

            }

            else

            {

                this.tbError.Text = e.Error.ToString();

            }

        }

    }

}

Let’s go through what’s happening here.

First, I add a OnSessionChanged event handler to the SignInButton’s SessionChanged event, right after InitializeComponent. When the user clicks the sign in button and gives consent to the app, the SessionChanged event is fired indicating user has successfully signed in.
When the OnSessionChanged event handler is called, I create a new instance of LiveConnectClient class, passing in the Session object. The session object contains the access token that the app needs to request data from Live Services.
The LiveConnectClient class make it easy to call the Live Service REST API and retrieve user data from the Window Live cloud. Here I’m retrieving the user’s basic profile information by calling GET on “me”. “me” is a special token used to identify the current user. You can retrieve other types of user data by passing in the relative url to the resource. You can find out more about what data is available in the documentation file you download through the Live Connect website.
When the GET request complete, my event handler OnGetMe is called.

6. We’re almost done. Before you can run this app, you need to register it with Windows Live. You can register your app by going to the application management site and the following the instructions there.

7. After your app is registered you’re ready to go. Hit F5 in VS. You will see that a sign-in button shows up.

Wait, why is that busy cursor keeps whirling? I know, but we’re working on it… For now, just ignore the busy cursor.

Click the button, a dialog comes up asking user if they would allow the app to access their data.

8. Click yes. The dialog disappears and the sign-in button changes to “Sign Out” state. At the same time a greeting is displayed with the user’s name. Hey, your app has just successfully connected to Live and obtained the user’s profile information.

9. Just like the JavaScript app we created in this post, the Single-Sign-On feature is also available in C# and VB. Shut down the app, restart it and watch the sign in button change to “Sign Out” state automatically.

Hope this is helpful to get your first Live Connected app up and running.

For more Live SDK samples, visit our github site at https://github.com/liveservices/LiveSDK.

A Step-by-step guide to creating your first Hello World Metro style app using Live Connect

2011-09-16T06:11:00Z

On Tuesday September 13^rd, together with the unveiling of the Windows Developer Preview, our preview release of the Live SDK for Live Connect went public on the Microsoft Connect website. The SDK includes a set of libraries that enable third party applications to connect with Windows Live and gain access to user’s profile as well as data stored in the Live cloud, including SkyDrive documents, Hotmail Contacts and Calendars, Messenger status, etc. The libraries in the SDK support multiple platforms, including Windows Phone and Windows Metro style apps using JavaScript, C# and VB. This will be the first of a series of how-to blogs that I will write about using the Live SDK and Live Connect for your apps.

In this first blog, I will go through the steps for creating your very first Live Connect powered Hello World Metro style app using JavaScript.

If you’re a C# or VB developer, check out this post.

If you’re a Windows Phone developer, this post is for you.

Let’s get started.

1. Download and install Windows Developer Preview following the instructions on the website.

2. Once your machine is all set up and ready to go, sign into your PC using a Live ID account. If you must use a domain account or a local account, you can connect your domain or local account to a Live ID account through Control Panel -> Users, click “Connect your Windows Live ID” and following the instructions.

3. Sign up for the Live Connect technical preview. Live Connect provides developers a set of controls and APIs that enable applications to integrate Single Sign On (SSO) with Microsoft connected accounts and enable users to access information from SkyDrive, Hotmail, and Messenger.

4. Install the Live SDK by downloading and running LiveSDK.msi from the website.

5. Start Visual Studio 11 Express and create a new project called HelloWorldWWA. Choose the JavaScript -> Windows Metro style -> Blank Application project template.

Tip: you can search for any installed programs by typing the program name in the start screen.

6. Bring up the “Add Reference” dialog and choose “Live SDK for Windows Metro style HTML applications” under the Windows -> Extension SDKs tab. Click “Add” and then “Close”. Notice that a reference to LiveSDKHTML SDK is added to your project.

Expand the LiveSDKHTML reference node and you will see under the js node, a reference to wl.js file is added.

7. Now open the default.html file. Add the following script tag to the header:

This adds the reference to wl.js in the html file.

8. In the body of default.html, add the following HTML markup.

<body>
    <div class="signin_button" id="signin"></div>
    <div class="greeting" id="greeting"></div>
    <div class="error" id="info"></div>

    <script>
        WL.Event.subscribe("auth.login", onLoginComplete);
        WL.init();
        var scopes = ["wl.signin", "wl.basic"];
        WL.ui({
            name: "signin",
            element: "signin",
            scope: scopes
        });

        function onLoginComplete(session) {
            if (!session.error) {
                WL.api({
                    path: "me",
                    method: "GET",
                }, onAPICalled);
            }
            else {
                document.getElementById("info").innerText =
                    "Error signing in: " + session.error;
            }
        }

        function onAPICalled(result) {
            if (!result.error) {
                document.getElementById("greeting").innerText =
                    "Hello, " + result.first_name + " " + result.last_name + "!";
            }
            else {
                document.getElementById("info").innerText =
                    "Error getting info: " + result.error;
            }
        }
    </script>

</body>

The 3 div elements provide hosting surface to the sign-in button, the greeting and the error message (if anything goes wrong).

The code inside the script tag does the following things:

Subscribe to the auth.login event (WL.Event.subscribe()). The event is fired when user logs into Windows Live and grants consent to your application.
Initializes WL (WL.init()), the JS library for Live Connect.
Creates the sign-in button (WL.ui()) with a list of scopes that the app needs to request user consent for.
When login completes, the onLoginComplete is invoked. The app then makes a call to Live Services REST API via WL.api() to retrieve the user profile.
When the api() call completes, the app can obtain the user’s profile information through the JSON object passed in to the callback function, in this case, the result object passed to the onAPICalled callback.
The app greets the user by displaying their first and last names.

9. We’re almost there. Before you can run this app, you need to register it with Windows Live. You can register your app by going to the application management site and the following the instructions there.

10. The last optional step is to add some css style to your div elements. Here’s a basic example. In you default.css file, add the following:

.signin_button
{
    margin-left: 100px;
    margin-top: 100px;
}

.greeting
{
    margin-left: 100px;
    margin-top: 50px;    
    font-weight:bold;
    font-size: x-large;
}

.error
{
    margin-left: 100px;
    margin-top: 20px;
    font-size: large;    
}

Tip: Visual Studio does not support editing html through a visual designer, but you can view and edit the visuals through Microsoft Expression Blend 5 included in the Windows Developer Preview. Start Blend and open the sample project. You will see that the default.html file looks like the following in Blend’s designer view (the greeting and error strings are added only to show the visual effects in the designer).

11. Now let’s run it. Hit F5 in VS. You will see that a sign-in button shows up.

Click the button, a dialog comes up asking user if they would allow the app to access their data.

12. Click yes. The dialog disappears and the sign-in button changes to “Sign Out” state. At the same time a greeting is displayed with the user’s name. Voila, your app has just successfully connected to Live and obtained user profile information from Live Services.

13. Now here’s the best part. Shut down the app, without changing anything, restart it. You’ll notice that after loading, the sign-in button automatically switches to “Sign Out” state and the greeting is displayed. This is what we call the Single-Sign-On for third party apps feature. It enables the app to do instant personalization without user having to do anything, as long as he has consented to allow the app to access to his data. Now, that’s cool! Think about all the things you can do to personalize your app for the user with zero clicks. This cool new feature will make your app piping hot…

For more Live SDK samples, visit our github site at https://github.com/liveservices/LiveSDK.