How to: Use the Client Application Connection Sample

  • Article

The Microsoft Office Live Client Application Connection code sample shows how you can use Office Live Small Business Web services to connect your client-side application to Office Live Small Business data.

This code takes advantage of the Office Live Small Business Discovery Web service, Windows Live ID for client applications, and the authentication services provided in the Microsoft System.Net namespace. You can provide access to an Office Live Small Business subscription from your application without requesting additional credential information by using a combination of these services.

As an example of accessing Office Live Small Business data after authentication, the Client Application Connection sample includes code that connects to an Office Live Small Business server with the user's Windows Live ID credentials to list all documents in one of the user's Office Live Small Business document libraries.

Download the sample

Client Application Connection is provided as sample code. You can copy snippets of this code or duplicate them in your application to help you provide authenticated connections.

To download the Client Application Connection code sample:

  1. Go to the Microsoft Download Center.
  2. Click the .exe file to install the Client Application Connection files to the following location: C:\Microsoft Office Live Developer Resources\Client Application Connection Sample.

Authenticate your client application connection

Microsoft Windows Live ID for client applications enables your application to access Windows Live ID sites and services, including Office Live Small Business, using a customized authentication ticket.

The following steps demonstrate how you can authenticate a user who is logged in to an Office Live Small Business subscription from your client application to allow access to Office Live Small Business data.

Step 1. Authenticate the user's Windows Live ID account.

This sample uses the IdentityManager class of Windows Live ID to create an Identity object for the current user and then uses the Authenticate method of this class to authenticate the user’s Windows Live ID account.

  IdentityManager identityManager;
identityManager = IdentityManager.CreateInstance(applicationId, 
                  applicationName);
Identity identity = identityManager.CreateIdentity();
if (!identity.Authenticate())
{
     throw new ApplicationException("Unable to authenticate the 
                         user’s Windows Live ID account.");
}
Step 2. Get the Office Live Small Business settings to generate a Windows Live ID authentication ticket.

The Client Application Connection code takes advantage of the Office Live Small Business Discovery Web service to discover the appropriate Windows Live ID settings. First, it accesses the Discovery Web service.

  Discovery discoSvc = new Discovery();
discoSvc.Url = "https://apis.officelive.com/discoverywebsvc/discovery.asmx";

Next, it gets the Windows Live ID settings for the Office Live Small Business service.

  LiveIDSettings settings = discoSvc.GetLiveIDSettings();
Step 3. Request the user's current Windows Live ID authentication ticket for the Office Live Small Business service.

You can use Windows Live ID’s GetTicket method to get the user’s authentication ticket information for the Office Live Small Business service.

  string ticket = identity.GetTicket(settings.SiteName, settings.Policy, false);
Step 4. Authenticate the user for Office Live Small Business Web requests.

The class WindowsLiveAuthenticationModule, included in this sample code, handles Windows Live ID authentication for Office Live Small Business Web requests. This module implements an IAuthenticationModule interface from the Microsoft System.Net namespace.

This sample code then creates and registers a new authentication module using the Register method of the AuthenticationManager class in the Microsoft System.Net namespace, passing the ticket obtained in step 3.

  WindowsLiveAuthenticationModule authModule;
authModule = new WindowsLiveAuthenticationModule(ticket);
		AuthenticationManager.Register(authModule);

Authenticate is the core method for the Client Application Connection sample custom authentication. The following are details of the actual process that triggers the Authenticate method:

  1. When an Internet resource requests authentication, the System.Net WebRequest.GetResponse method calls the AuthenticationManager.Authenticate method.
  2. The AuthenticationManager.Authenticate method calls each registered authentication module to find the first module that can respond to the authentication request.
  3. When a module responds, an Authorization object is returned to the Web request.

This Authorization is the key you need to unlock the user's Microsoft Office Live data.

Access Office Live Small Business data

The example in this code is designed to print the names of the documents in the user’s Office Live Small Business document library if the user is authenticated.

You can use methods of the Discovery class in the Discovery Web service to determine the subscriptions associated with the authenticated user and find a document library included in those subscriptions. The GetSubscriptions method allows the sample to find an Office Live Small Business subscription that the user owns. The GetResources method returns a list of resources, including document libraries, in the subscription. The code in this sample selects the first document library it finds.

The calls to the methods of the Discovery class invoke the WindowsLiveAuthenticationModule to authenticate this Office Live Small Business Web request:

  discoSvc.UserAgent = discoSvc.UserAgent + ";" + WindowsLiveAuthenticationModule.WindowsLiveClientHeader;
discoSvc.Credentials = new NetworkCredential();

To access Windows Live ID sites and services such as Office Live Small Business, you must find the URL of the Web Service Description Language (WSDL) file that describes the service. The service being used in this example is the SharePoint Lists Web service. In addition to adding this service as a Web reference, this example constructs a URL for it.

  string listServiceUrl = userDocumentLibraryUrl + 
                        SharepointServicesPrefix  + "Lists.asmx";

It then connects to the Lists Web service for the user’s document library.

  Lists listsWebService = new Lists();
listsWebService.Url = listServiceUrl;

Next, it invokes a WindowsLiveAuthenticationModule to authenticate this Office Live Small Business Web request.

  listsWebService.UserAgent = listsWebService.UserAgent + ";" + 
          WindowsLiveAuthenticationModule.WindowsLiveClientHeader;
listsWebService.Credentials = new NetworkCredential();

The example then uses the Lists Web service to access and print the titles of all documents contained in the user’s document library.