he Windows Live Tools for Microsoft Visual Studio enable developers to incorporate a set of Windows Live services into their web sites using Visual Studio and ASP.NET via a set of ASP.NET Server Controls.

Microsoft released the second community technology preview (CTP) of the Windows Live Tools in December, 2007. By downloading the toolset, you can start integrating Windows Live Contacts, Windows Live ID Authentication, and Silverlight Streaming services into your web site.

Through this CTP, Microsoft is releasing four ASP.NET Server Controls: Contacts, SilverlightStreamingMediaPlayer, IDLoginStatus, and IDLoginView.

• The Contacts control lets users share their contacts between Windows Live and your web site.
• The SilverlightStreamingMediaPlayer control lets you show videos on your web site from your Silverlight Streaming account by simply dragging and dropping.
• The IDLoginStatus and IDLoginView controls provide Windows Live ID authentication at your web site for your users.

To help you develop Windows Live web sites, Microsoft has created a project template as well. This release only works with Visual Studio 2008 and Visual Web Developer 2008 Express Edition at this time.

Installing the Windows Live Tools is straightforward. After you complete the installation, Visual Studio will have a new “ASP.NET Windows Live Web Site” project template in the File ? New Web Site dialog box (see Figure 1). You can also find these controls listed as “Windows Live Tools” in the Toolbox.

	?
Figure 1. New Template: After installing the Windows Live Tools, you’ll find a new ASP.NET Windows Live Web Site template in the New Web Site dialog in Visual Studio.

Creating Your First Project with the Windows Live Tools
To begin a project that integrates Windows Live services, navigate to File ? New Web Site, and select the “ASP.NET Windows Live Web Site” template. Fill out the template details to finish creating the project, and then open the Default.aspx web page in designer mode by choosing “View Designer” from the context menu in the Solution Explorer.

This article will drill down into each of the newly introduced controls and what they offer for your web site.

The Contacts Control
Have you ever wondered why you have to enter a new shipping address for each web site whenever you buy a gift for a friend? What if you could share the shipping address across multiple web sites by using a central address book? The Contacts control is a solution that lets you safely transfer your contact information between Windows Live Contacts (a user’s single address book between Windows Live Messenger and Windows Live Hotmail) and a shopping web site. The Contacts control can also help a web site build viral communication channels where users can message one another in the context of the web site. For example, a shopping web site can specify a promotion message that users can send to one another from the web site.

The Contacts control offers three different views to best suit your needs: Tile, TileList, and List. In the Tile and TileList views, web site users can start an IM conversation or open an email with a pre-defined message or custom greeting from the web site, such as “Let’s discuss this topic.” The List view allows users to select and share their Windows Live Contacts across multiple web sites, and centralize address book management in one place. It’s an off-the-shelf address book pre-filled with data for any web site on the Internet.

Users maintain control of their data; they have the authority to choose to share or not share their data with your web site.

	?
Figure 2. The Contacts Control: After adding a Contacts control to a web page, and signing in, you’ll see the default view (the TileList view) of your contacts.

I’ll show you how easy it is to use Windows Live Contacts in your web site. Drag-and-drop the Contacts ASP.NET Server Control from the Toolbox onto the Default.aspx web page. The drag-and-drop operation adds the privacyPolicy.htm file to your project (you can replace this file with your own privacy policy statement). Run the web site by hitting Ctrl+F5. Visual Studio, after compiling the web site, launches the browser and displays the Default.aspx page. You will need to sign in using your Windows Live ID. After you are signed in, the Contacts control renders your contacts from messenger and Hotmail. Figure 2 shows the Contacts control with its default settings.

Sharing Contacts Data
The Contacts control maintains secure data isolation between Windows Live Contacts and your web site.

The control fetches a user’s contacts data from Windows Live servers via a secure HTTPS connection. Users can select the contacts they want to share with your web site, initiate data sharing, and review what data is being shared. Only when that process is complete does Windows Live release any data to your web site.

Another key aspect that requires special mention is the privacy statement for your web site. The Contacts control requires that you provide a privacy statement URL. The Contacts control renders a privacy statement URL to the user while transferring contact information to your web site. In your privacy statement, you must clearly state how you’re planning to use the data being transferred. You may either discard this data after using it, or store it in your servers for future usage. If you choose to store the data, you should clearly state this in your privacy statement and provide a means for users to review or delete the stored data.

For example, to enable sharing contacts data for the shipping address scenario as mentioned earlier, you would need to:

• Set the PrivacyStatementURL to a web page/link that describes the privacy statement for your web site.
• Set the View property to List.
• Set the DataDesired property to specify which data elements to fetch from Windows Live Contacts.
• Provide client/server-side event handlers to receive the data and handle the shipping process for the purchased items.

Next, I’ll show you how to modify the project to allow users to share their contacts data on Default.aspx. You can get the complete reference to the data elements allowed for the DataDesired property, but for now, set the following values the DataDesired property to retrieve: firstname, lastname, personalstreet, personalcity, personalstate, personalcountry, and personalpostalcode.

After the Contacts control transfers the data, you can process the data in the OnClientData or OnServerData event handlers.

For example, the OnClientData event handler might look like this JavaScript:

	?
Figure 3. Contact Data Received: This alert message shows the contact details received in the OnClientData event.

The OnClientData event handler receives the transferred contacts as an array of objects. Each object represents one contact selected by the user for transfer. Each contact object has data elements corresponding to the DataDesired property. If a requested data element does not exist for a contact, it will not be returned.

When this code executes, you'll see an alert dialog that enumerates the data elements and their values (see Figure 3).

You can specify similar processing logic in the server-side code. The Contacts control offers a corresponding server-side event for processing data received from the transfer (see Listing 1).

The declaration for the Contacts control on the default.aspx web page would look like:

Writing Contacts Data
The Contacts control allows you to write into a user's address book. For example, a web page may allow users to transfer contacts data from their web site to Windows Live Contacts. Whenever a site attempts to modify a user's address book, Windows Live raises an alert to notifying the user. Users are required to review the modifications and approve them before they may proceed. Once approved, the modifications are transmitted to Windows Live servers via a secure HTTPS connection. Again, users maintain control of their own data.

For example, adding a contact to a signed-in user's address book is very simple. The Contacts control provides the CreateContact method, which takes a list of contacts (List). The Microsoft.Live.ServerControls namespace contains the definition of the Contact class, which has member properties that represent a contact's data elements. (Here's complete list of the available data elements).

To see code for this example, refer to Listing 2, which shows Default.aspx, and Listing 3, which shows Default.aspx.cs. Default.aspx has a Contacts control, an update panel, a text box where users can input e-mail for the contact to be added, and three button controls, which add a contact, add a list of contacts, and delete contacts, respectively.

The btnAdd_Click event handler (defined in Listing 3) shows that it's easy to add contacts to a user's contacts. You start by creating a Contact object. Next, set the data elements that you are interested in, create a generic List of contacts, and pass that list to the CreateContacts method. The Contacts control can then either abort or commit the operation. The following C# code snippet shows how to set this only for email; however, you can extend the code to set whatever data elements your application desires:

   //add contact to signed-in users' contacts   protected void btnAdd_Click(object sender, EventArgs e)   {      List objContacts = new         List();      Contact objContact = new Contact();      objContact.EmailPersonal = txtEmail.ToString().Trim();      objContacts.Add(objContact);      Contacts1.CreateContacts(objContacts);      Contacts1.CommitContacts();   }

Listing 3 also includes the btnAddList_Click handler, which submits multiple contacts for addition. You can submit a maximum of 30 contacts in one operation.

	?
Figure 4. Error Handling: The figure illustrates client-side error reporting using the OnClientCommit event.

Finally, the btnDeleteList_Click performs batch contact deletions. The code attempts to delete four contacts?but the fourth contact was never added. Note that you must call the CommitContacts method after create or delete operations; otherwise, these operations won't be finalized. When the CommitContacts method executes (after DeleteContacts) and the user approves the operation, it posts a delete request to the Windows Live servers. In this case, because the fourth contact doesn't exist, that delete request will fail. The btnDeleteList_Click code shows how Windows Live reports errors back to your code from create/delete operations; after the request completes, the OnClientCommit event is raised followed by the OnServerCommit event. Figure 4 shows the event argument returned on the client side, args, which reports an error because of the attempt to delete the nonexistent contact.

The Contacts control also offers other events for sign-in/sign-out, error handling, and various properties for styling (such as text, color, height, and width). You'll find the Contacts control reference online.

The IDLoginStatus Control
The IDLoginStatus control provides Windows Live ID authentication, which can be used to identify visitors to your web site. IDLoginStatus provides a unique, site-specific identifier for each Windows Live user. This allows web sites to personalize the experience for the visiting user.

When a user clicks on the sign-in link, the IDLoginStatus control redirects to the sign-in web page on Windows Live servers (http://login.live.com) along with an application ID. After users enter their credentials, the sign-in page redirects them to the page with the IDLoginStatus control.

To obtain an application ID for your web site, you need to register your application with the Windows Live ID service. You can do so by visiting http://msm.live.com/app (see the sidebar "Registering Your Application with Windows Live ID").

IDLoginStatus provides an easy workflow for developers within the Visual Studio development environment. After you drag-and-drop the IDLoginStatus control onto your web page, you can get a new application ID by clicking "Create new Application ID" from the IDLoginStatus tasks (Figure 5). After you complete application registration and close the form, the IDLoginStatus control saves the application ID and your application secret into Web.Config and sets the ApplicationIDConfigKey and ApplicationSecretConfigKey properties on the IDLoginStatus control. The control adds wll_appid and wll_secret keys into the section of the Web.Config file. At run time, the control checks the ApplicationIDConfigKey and ApplicationSecretConfigKey property values, and reads the Web.Config keys.

	?
Figure 5. IDLoginStatus: You can get a new application ID from within Visual Studio by clicking "Create new Application ID."

The following snippet from Web.Config shows an example of the alterations:

The HTML declaration for the IDLoginStatus control looks like this:

IDLoginStatus offers both client side and server side events for sign-in/sign-out. IDLoginStatus also returns an AuthEventArgs instance, which contains:

• ApplicationUserID: The unique site-specific identifier for the signed-in user.
• TimeStamp: The time the user authenticated measured in seconds from Jan 1, 1970 GMT.
• ApplicationContext: A parameter that round-trips your application state through the redirections to and from the Windows Live servers).

If you are using ASP.NET membership, IDLoginStatus enables single-sign-on. You can set the AutomaticallyConvertAuthentication property to true. When true, the IDLoginStatus control verifies whether the current signed-in user has previously associated with an ASP.NET membership profile, and if so, automatically logs in to ASP.NET membership based on that association. You'll see more about this in the next section.

You can find the complete reference for the IDLoginStatus control online.

The IDLoginView Control
The IDLoginView control extends ASP.NET's LoginView control. Where the LoginView control provides template switching based on a user's logged-in state in ASP.NET membership, IDLoginView provides switching based on a user's logged-in state in both ASP.NET membership and Windows Live ID. The IDLoginView handles template switching and association of Windows Live ID and a user's ASP.NET membership profile.

IDLoginView adds three new templates in addition to the two provided in the LoginView control:

• AnonymousTemplate: Displayed to web site users who are not logged into the web site (inherited from LoginView).
• LoggedInTemplate: Displayed to web site users who are logged into ASP.NET membership at the web site (inherited from LoginView).
• LoggedInIDTemplate: Displayed to web site users who are logged in with Windows Live ID at the web site.
• LoggedInAllTemplate: Displayed to web site users who are logged into both ASP.NET membership and Windows Live ID.
• AssociatePromptTemplate: Displayed to web site users when they have logged in with both ASP.NET membership and Windows Live ID, but have not yet associated these two identities.

Not only does IDLoginView provide template switching based on a user's logged-in state, but it also allows users to associate their Windows Live ID and ASP.NET membership identities. Based on your choice, the control presents the AssociatePromptTemplate to users, asking whether they want to associate their Windows Live ID and ASP.NET membership to get a single-sign-on experience.

Refer to Listing 4 (IDLoginView.aspx) and Listing 5 (IDLoginView.aspx.cs) for the following discussion.

After you drag and drop the IDLoginView control onto your web page, start by setting these two properties: AutomaticallyAssociateAuthentication and PromptOnAssociation. Setting the AutomaticallyAssociateAuthentication property to true instructs the IDLoginView control to associate ASP.NET membership and Windows Live ID when a user is logged in with both identities. IDLoginView calls AssociationManager.AssociateAuthentication passing the ApplicationUserID (Windows Live ID's unique identifier for the signed-in user at your web site) and the ASP.NET membership identity. If you set the PromptOnAssociation property to true, the IDLoginView asks users whether to associate their Windows Live ID with their ASP.NET membership before establishing an association.

If you haven't already, you need to launch the ASP.NET Web Site Administration Tool from Website ? ASP.NET Configuration. Please make sure that you make the following changes:

• Set Authentication type to "From the Internet". By default, this is not the case. You can access this setting from the Security tab of ASP.NET Web Site Administration, and then clicking "Select the authentication type."
• Set up a few users by choosing "Create User". This will create users for your web site who will be saved in the ASPNETDB.MDF database in the App_Data folder.

Having set up some users for the web site, you can test the template switching and association features in IDLoginStatus and IDLoginView, as provided in Listing 4 and Listing 5.

You may be surprised to see that you all the template switching and association functionality is taken care of without you having to write a single line of code.

Here's how it works: When a web site visitor signs-in to your web page using the IDLoginStatus control, IDLoginStatus sets the webauth cookie, which contains the ApplicationUserID for the signed-in user. The IDLoginView detects the state change after the IDLoginStatus control sets this cookie. IDLoginView then switches the template to the LoggedInIDTemplate and renders the specified contents. You can provide content applicable to users having Windows Live ID in this template. If a user signs in to ASP.NET membership, IDLoginView switches to the LoggedInAllTemplate. At this time, if you had set the AutomaticallyAssociateAuthentication and PromptOnAssociation properties to true, IDLoginView renders the AssociatePromptTemplate to the user. If the user chooses to associate the two identities, IDLoginStatus creates an association between Windows Live ID and ASP.NET membership.

The btnRemove_Click event handler (see Listing 5) shows how you can remove this association, if a user chooses to do so.

AssociationManager
The AssociationManager allows a developer to directly query, set, or remove associations for the signed-in user. The Microsoft.Live.ServerControls namespace contains this class. Include a using statement for the Microsoft.Live.ServerControls namespace in your program.

The SilverlightStreamingMediaPlayer Control
The final Windows Live control is the SilverlightStreamingMediaPlayer, which lets you upload videos to your Silverlight Streaming account and play them on your web site by simply dragging-and-dropping them on the control.

At design time, you provide account credentials for your Silverlight Streaming account and then choose the video that your web page should play. After you drag-and-drop this control onto your web page, you can specify the video to be played through the "Select Media File" form. This form is accessible through the control's tasks window or property grid (see Figure 6). You don't need to write code to make a connection to Silverlight Streaming servers or choose videos. All this is encapsulated; all you you need to do is specify the credentials, and choose a video.

	?
Figure 6. The SilverlightStreamingMediaPlayer Control: This control lets you include and stream videos on your pages that you've stored in your Silverlight Streaming account.

After you choose the video you want to play, the control saves the video's URL in streaming:// format in the control's MediaSource property. It also saves AccountID and AccountKey values for your Silverlight Streaming account into the Web.Config file's section, as shown below (using example values for the AccountID and AccountKey keys:

The control's HTML declaration would look like this:

At run time, the control converts streaming:// URLs to HTTP URLs. If you don't want to hard-code the video, you can also set the video URL from client side JavaScript using code similar to the following (note that you need to hook this JavaScript function to an action, such as a button click):

You can find details about the underlying ASP.NET MediaPlayer here.

The examples and discussion in this article should prove helpful in getting you started with the Windows Live Tools. If you have feedback about Windows Live Tools or how you are going to use it, please leave suggestions to improve the feature set or bug reports here: http://dev.live.com/tools.