RSS Feed
Download our iPhone app
Browse DevX
Sign up for e-mail newsletters from DevX


Getting Started with the Windows Live Tools : Page 2

Windows Live Tools brings a set of Windows Live services right into your Visual Studio development environment.

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:

   <script type="text/javascript">
   function Contacts1_OnClientData(sender, args)
      var s = args.contacts.length+ " records\r\n";
      for (var i = 0; i < args.contacts.length; i++)
         for (var j in args.contacts[i]){
            s += j + ": " + args.contacts[i][j]+"\r\n";
         s += "\r\n";
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:

   <live:Contacts ID="Contacts1" runat="server"
     DataDesired="firstname, lastname,
     personalstreet, personalcity,
     personalstate, personalcountry,
     OnServerData="Contacts1_OnServerData" />
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<Contact> objContacts = new
      Contact objContact = new Contact();
      objContact.EmailPersonal = txtEmail.ToString().Trim();
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.

Close Icon
Thanks for your registration, follow us on our social networks to keep up-to-date