Using the Data Context

Current information about Live Connect is now available in the Windows Live Developer Center. The information in the following sections is provided for legacy purposes only.

The data context object manages all communication between your application and Windows Live. You use the data context to work with Windows Live data such as contacts, profiles, and categories. For example, to retrieve an authenticated user's Windows Live profile information or contacts, you send requests to Windows Live by using the data context.

This topic describes the typical programming pattern for working with Windows Live resources by using the data context.

The examples in this topic use the Windows Live Contact resource for the purpose of illustration. However, the programming patterns discussed here apply to all Windows Live resources.

In a typical scenario, you obtain the data context from inside the callback function that you specify to run when a user signs in. For example, the <wl:signin> control, which provides all the functionality necessary for user authentication, supports a callback function as shown in the following example.

<wl:signin  onsignin="{{signInComplete}}"></wlsignin>

When sign-in is complete, the control calls signInComplete. The callback function receives an object of type signInCompletedEventArgs as a parameter. You can use the functionality provided by this object to:

  • Verify that the sign-in succeeded, by calling signInCompletedEventArgs.get_resultCode.
  • Obtain a data context, by calling signInCompletedEventArgs.get_dataContext.

You use this data context to send requests to Windows Live. The following example shows a sample callback function. If the sign-in is successful, the callback function retrieves a data context and uses it to load the authenticated user's Windows Live contact data.

function signInComplete(signInCompletedEventArgs) {
    if (signInCompletedEventArgs.get_resultCode() != Microsoft.Live.AsyncResultCode.success) {
        //  Process on failure.
    // Get the data context and load contacts.
    dataContext = signInCompletedEventArgs.get_dataContext();
    dataContext.loadAll(Microsoft.Live.DataType.contacts, contactsLoaded);

The dataContext.loadAll() method retrieves all the user's contacts from Windows Live. It takes two parameters:

  • A string that is one of the fields of the Microsoft.Live.DataType class. It specifies the type of resource to load.
  • The name of a callback method that is called after loadAll has finished and after contacts are loaded.

Loading a Partial Collection

Instead of loading all contacts, you can load only a subset. To do this, use the load method of the data context and applying a server-side query filter as shown in the following example.

var options = { "$filter": "FirstName contains 'some_value'"};
dataContext.load(Microsoft.Live.DataType.contacts, options, contactLoaded);

After the loadAll (or load) operation completes, the specified callback function executes. The callback receives an object of type dataLoadCompletedEventArgs. As shown in the following example, the get_data method of that object returns a reference to the collection that was loaded.

function contactsLoaded(dataLoadCompletedEventArgs) {
    contactsCollection = dataLoadCompletedEventArgs.get_data();

The returned reference is to an in-memory collection. You can use this reference to update the contacts collection, add new contacts to it, or delete existing contacts from it. All the changes you make are to the in-memory collection. When you are ready to send the changes back to Windows Live, call the save method of the collection that you are working with.

Adding a Resource to the Collection

To add a new contact, create an instance of the Contact class, add it to the local collection, and send the updates back to Windows Live as shown in the following example.

function addContact() {
    if (contactsCollection) {
        // create newContact

Updating a Resource in the Collection

To update a resource, select it from the collection, update it, and then send the changes back to Windows Live. The following example updates the firstName and lastName properties of a contact resource.

function updateContact(contactSelected) {

Deleting a Resource from the Collection

To delete a resource, select and remove it from the collection and then send the updates back to Windows Live as shown in the following example.

function deleteContact(contactSelected) {

Enumerating Resources in the Collection

You can access the in-memory data collection as an array, and you can enumerate the objects in the array as demonstrated by the following example.

for (var i = 0; i < contactsCollection.get_length(); i++) {
    var contact = contactsCollection.get_items(i);
    // Process contact.

Saving the Local Collection Back to Windows Live

The save method of the collection object sends the updates back to Windows Live. The following statement sends the local updates for the contacts collection (contactsCollection) back to Windows Live.;

The save method takes a callback function as its only parameter. The callback function is called when the save operation is complete.

Verifying the Save Operation

In a typical scenario, a site performs several updates on an in-memory collection before sending the updates back to Windows Live. The save method sends one request to Windows Live for each update it finds in the collection.

As previously mentioned, the save method takes a callback function as a parameter (operationCompleted in the preceding example). The callback function takes a dataSaveCompletedEventArgs object as a parameter. This object provides the get_results() method that returns an array of results, one result for each update that was sent back to Windows Live.

We recommend that you verify that all of the result codes that are returned in this array indicate success. The following example shows a callback function that verifies results.

function operationCompleted(dataSaveCompletedEventArgs) {
    for (var i = 0; i < dataSaveCompletedEventArgs.get_results().length; i++) {
        var dataSaveResult = dataSaveCompletedEventArgs.get_results()[i];
        if (dataSaveResult.get_resultCode() !== Microsoft.Live.AsyncResultCode.success) {
             alert("Error saving data");