Description
Common SharePoint tasks, such as assigning a user to a task in a SharePoint tasks list, require the use of the SharePoint People Web service. The SharePoint People Web service may be used to validate a user account exists, and to return metadata about a user. Developers must understand how to use the SharePoint People Web service to perform these SharePoint tasks in Windows Phone 7 applications.
Overview
Common SharePoint tasks, such as assigning a user to a task in a SharePoint tasks list, require the use of the SharePoint People Web service. The SharePoint People Web service may be used to validate a user account exists, and to return metadata about a user. Developers must understand how to use the SharePoint People Web service to perform these SharePoint tasks in Windows Phone 7 applications.
Objectives
In this hands-on lab, you will learn how to create a Windows Phone 7 application that integrates with the SharePoint People Web service, and the SharePoint Lists Web service. The Windows Phone 7 application will create SharePoint tasks and assign them to a user.
- Learn how to use the SharePoint People Web service to validate a user account exists.
- Learn how to use the SharePoint People Web service to return metadata for a user.
- Learn how to use the SharePoint Lists Web service to create a new task assigned to a SharePoint user.
Prerequisites
The following is required to complete this hands-on lab:
See Setting Up A SharePoint and Windows Phone 7 Development Environment Module for instructions that describe how to set up the SharePoint and Windows Phone 7 developer machine.
- Windows 7 x64 installed with all Windows Updates installed, in one of the following scenarios.
- Installed on a physical machine
- Installed on a bootable VHD
- SharePoint 2010 installed on the Windows 7 x64 developer machine configured with a site collection that uses Forms Based Authentication (FBA).
- Windows Phone 7 Developer Tools
- Windows Phone 7 Developer Tools - January 2011 Update
Windows Phone Developer Tools Fix
In this exercise, you will deploy a list template to SharePoint and make a list based upon the template. The list template defines a list used to tasks. The Windows Phone 7 application will read the tasks from the SharePoint list and create new tasks in the list that are assigned to a SharePoint user.
Task 1 – Deploying the List Template to a SharePoint Site
In this task, you will deploy the sample tasks list template to a SharePoint site. The list template contains sample data used in the lab.
Open Internet Explorer and navigate to the SharePoint Team Site configured for Forms Based Authentication.
example: https://fbawp7
- Log into the site using site collection administrator credentials.
- Click Site Actions, and select Site Settings.
- In the Galleries section, click List templates.
- In the Ribbon, click the Documents tab.
- Click Upload Document.
- Click Browse…
- Browse to the Sample Tasks.stp file located at %TrainingKitPath%\Labs\IntegratingPeopleData\Source\Before and select it.
- Click Open.
- Click OK.
- Click Save.
- Verify the Sample Tasks list template appears in the List Templates Gallery.
Task 2 – Creating the Sample Tasks List
In this task, you will use the sample tasks list template to create the sample tasks list.
Open Internet Explorer and navigate to the SharePoint Team Site configured for Forms Based Authentication.
example: https://fbawp7
- Log into the site using site collection administrator credentials.
- Click Site Actions and select More Options.
- In the Filter By section, select List.
Select the Sample Tasks list.
Figure 1
Create list dialog
- In the Name textbox enter Sample Tasks.
- Click Create.
Verify the Sample Tasks list contains the following sample data.
Figure 2
Sample Task list with data
In this exercise, you will create a Windows Phone 7 application to query the sample tasks SharePoint list. You will also implement the code necessary to lock and unlock the application.
Task 1 – Beginning the Exercise
In this task, you will open the lab solution in Visual Studio 2010.
- Make sure that you have downloaded and installed the items listed in System Requirements above prior to beginning this exercise.
- Launch Visual Studio 2010 as administrator and open the lab project by selecting File » Open » Project.
- Browse to the WP7.SharePoint.People.sln file located at %TrainingKitPath%\Labs\IntegratingPeopleData\Source\Before and select it.
- Click Open to open the solution.
Task 2 – Configuring Constants in the Windows Phone 7 Application
In this task, you will configure the constants used in the Windows Phone 7 application to work with your development environment.
- In the WP7.SharePoint.People project, in the Utilities folder, open the Constants.cs file.
- Change the value for the USER_NAME and USER_PASSWORD constants to represent a Forms Based Authentication user specific to your development environment. For this lab, the user requires read and write permissions.
- Change the value for the AUTHENTICATION_SERVICE_URL constant to the URL specific to your development environment.
The following code example demonstrates the value for a SharePoint server named fbawp7.
public const string AUTHENTICATION_SERVICE_URL = "https://fbawp7/_vti_bin/authentication.asmx";
Task 3 – Configuring the Reference to the SharePoint Lists.asmx Web Service
In this task, you will configure the reference to the SharePoint lists.asmx Web service. The service reference to this Web service has already been added to the project.
- In the Solution Explorer, double click the ServiceReferences.ClientConfig file to open it.
In the Endpoint element, change the address attribute to the URL for the lists.asmx SharePoint Web service in the site where you created the Sample Tasks list.
Example: https://fbawp7/_vti_bin/lists.asmx
Figure 3
Edit the Lists service endpoint address
Task 4 – Configuring the Reference to the SharePoint People.asmx Web Service
In this task, you will configure the reference to the SharePoint people.asmx Web service. The service reference to this Web service has already been added to the project.
- In the Solution Explorer, double click the ServiceReferences.ClientConfig file to open it.
In the Endpoint element, change the address attribute to the URL for the people.asmx SharePoint Web service in the site where you created the Sample Tasks list.
Example: https://fbawp7/_vti_bin/people.asmx
Figure 4
Edit People service endpoint address
In this task, you will use the SharePoint People Web service to verify a user account exists and request metadata about the user.
- In the WP7.SharePoint.People project, expand the ViewModels folder, and double click the MainViewModel.cs file.
Add the following code under the //TODO: 10.2.1 comment to define the CheckUser method:
public void CheckUser(string userName, bool addTask) { WP7.SharePoint.People.SPPeopleService.PeopleSoapClient peopleService = new SPPeopleService.PeopleSoapClient(); //App.CookieJar used for SharePoint FBA Authentication. //See the Security With SharePoint And Windows Phone 7 Applications //module for more information. peopleService.CookieContainer = App.CookieJar; peopleService.ResolvePrincipalsCompleted += new EventHandler<SPPeopleService.ResolvePrincipalsCompletedEventArgs> (peopleService_ResolvePrincipalsCompleted); SPPeopleService.ArrayOfString userNameArray = new SPPeopleService.ArrayOfString(); userNameArray.Add(userName); //Set the local variable to indicate a task will be added if //the username is resolved. addingTask = addTask; peopleService.ResolvePrincipalsAsync( userNameArray, SPPeopleService.SPPrincipalType.User, true); }
The CheckUser method is called when a user clicks the Check User button or the Create Task button in the Windows Phone 7 application. The buttons are highlighted in the screenshot below.
Figure 5
The check user button
The userName argument contains the username to validate. The addTask argument specifies if a new task should be created in the SharePoint task list if the user exists. The check user button passes in a value of false for the addTask argument because the button is only used to validate a user. The Create Task button passes in a value of true for the addTask argument because the button is only used to create a new task, however the user must be validated before the task may be created and assigned to a user.
You may also use a more complex MVVM pattern with System.Actions and callback delegate methods to implement the functionality the addTask parameter facilitates. The pattern implemented in the WP7.SharePoint.People is implemented in the lab for simplicity’s sake to make it easier to focus on the interaction with the SharePoint Web services.
First, the CheckUser method creates an instance of the proxy class Visual Studio generated for the SharePoint People Web service. Then, the CookieContainer is populated to authenticate the Web service request.
See the Security With SharePoint And Windows Phone 7 Applications module for more information about security and the App.CookieJar property.
Next, the ResolvePrincipalsCompleted event handler is registered. This event handler fires when the request to the SharePoint People Web service is complete.
Next, a string array is created to hold the usernames to validate. The username parameter is added to the array. Finally, The ResolvePrincipalsAsync method is called to validate the username and request the metadata for the user. The third argument in the ResolvePrincipals method specifies that a record should be created in the UserInformation list for the user being validated if a record does not already exist. This is set to true to ensure the record exists since it is required to assign a user to a task.
The ResolvePrincipals checks the authentication store for the SharePoint web site where it is called from to validate a user exists. It is possible for usernames to validate successfully in the ResolvePrincipals method without the user’s information being in the UserInformationList.
In this task, you will use the SharePoint People Web service to parse the result from the ResolvePrincipals web method and return the metadata about the user.
- In the WP7.SharePoint.People project, expand the ViewModels folder, and double click the MainViewModel.cs file.
Add the following code under the //TODO: 10.2.2 comment to define the peopleService_ResolvePrincipalsCompleted event handler:
void peopleService_ResolvePrincipalsCompleted(object sender, SPPeopleService.ResolvePrincipalsCompletedEventArgs e) { SPPeopleService.PrincipalInfo principalInfo = e.Result[0]; if (principalInfo.UserInfoID < 0) { MessageBox.Show("The user does not exist."); } this.UserInfoID = principalInfo.UserInfoID.ToString(); this.DisplayName = principalInfo.DisplayName; this.IsUserResolved = principalInfo.IsResolved; this.AccountName = principalInfo.AccountName; if (addingTask && IsUserResolved) { AddTask(TaskTitle, UserInfoID); } }
The peopleService_ResolvePrincipalsCompleted event handler fires when the ResolvePrincipals method in the SharePoint People web service is complete.
First, a PrincipalInfo class is created to store the results from the ResolvePrincipals method and make them easily accessible. The UserInfoID property is checked to see if the user exists. If the user does not exist then a MessageBox is displayed to indicate the user does not exist. Then, several properties are set to store the metadata about the user account. These properties are databound to the controls in the Windows Phone 7 application that display the metadata. When the properties are updated, the controls in the Windows Phone 7 application display the updated values automatically.
Finally, in the case when the addingTask local variable is true (because the Create Task button was clicked) and the ResolvePrincipals web method validated the user account (IsResolved property is equal to true), the AddTask method is called to create a SharePoint task and assign it to the validated user account.
Task 7 – Implementing Code to Create a SharePoint Task and Assign it to a User
In this task, you will use the SharePoint Lists Web service to create a task in a SharePoint tasks list and assign it to a user.
- In the WP7.SharePoint.People project, expand the ViewModels folder, and double click the MainViewModel.cs file.
Add the following code under the //TODO: 10.2.3 comment to define the AddTask method:
public void AddTask(string title, string userInfoID) { XElement updateQuery = new XElement("Batch", new XAttribute("OnError", "Continue"), new XAttribute("ListVersion", "1"), new XElement("Method", new XAttribute("ID", "1"), new XAttribute("Cmd", "New"), new XElement("Field", new XAttribute("Name", "Title"), title), new XElement("Field", new XAttribute("Name", "AssignedTo"), userInfoID))); WP7.SharePoint.People.SPListsService.ListsSoapClient lists = new WP7.SharePoint.People.SPListsService.ListsSoapClient(); //App.CookieJar used for SharePoint FBA Authentication. //See the Security module for more information. lists.CookieContainer = App.CookieJar; lists.UpdateListItemsCompleted += new EventHandler<SPListsService.UpdateListItemsCompletedEventArgs> (lists_UpdateListItemsCompleted); lists.UpdateListItemsAsync(Utilities.Constants.SHAREPOINT_LIST_NAME, updateQuery); }
The title argument contains the title value for the task to create in SharePoint. The userInfoID argument is the ID of the user account in the UserInformation list on the SharePoint site. The ResolvePrincipals web method returned this value; it is part of the user’s metadata.
The AddTask method creates a XElement object to define the update query. The title and userInfoID parameters set the Title and AssignedTo column values for the new SharePoint task.
Then, the AddTask method creates an instance of the proxy class Visual Studio generated for the SharePoint Lists Web service. The CookieContainer is populated to authenticate the Web service request.
See the Security With SharePoint And Windows Phone 7 Applications module for more information about security and the App.CookieJar property.
Next, the UpdateListItemsCompleted event handler is registered. This event handler fires when the request to the SharePoint Lists Web service is complete.
Finally, The UpdateListItemsAsync method is called to create the task in the SharePoint tasks list. The first argument in the UpdateListItemsAsync method is the name of the SharePoint list to update; it is retrieved from the Constants class. The second argument is the XElement object defining the update query.
Task 8 – Testing the Application
In this task, you will test the Windows Phone 7 application.
- In the WP7.SharePoint.People solution, select Windows Phone 7 Emulator in the deployment location dropdown list.
Press F5. The Windows Phone 7 application starts in the emulator. The application uses the SharePoint Lists Web service to query the Sample Tasks list and displays the tasks at the bottom of the application.
Figure 6
The Task application running in the emulator
- To create a new task in the Sample Tasks list and assign it to a user follow these steps.
- Click in the Title textbox and enter Schedule vacation.
Click in the Assigned To textbox and enter the name of a user that does not exist in the authentication store for your SharePoint web site.
For example: USERABC123
The ResolvePrincipals method uses a wildcard search to look for usernames to match. If you enter a username that partially matches an existing username it will resolve the partially matching user account. For example, if you enter ‘aut’, the All Authenticated Users group will resolve.
Click the Check User button.
Figure 7
User validation error
- The Windows Phone 7 application displays an error message that the user does not exist.
- Click OK.
The Windows Phone 7 application displays the metadata for the invalid user.
Figure 8
User validation failed
Click in the Assigned To textbox and enter the name of a user that does exist in the authentication store for your SharePoint web site.
Figure 9
Enter valid user
In this example, an account named testaccount is used. It is pictured below in the Computer Management console on the SharePoint server.
Figure 10
Confirm the test user account
- Click the Check User button.
The Windows Phone 7 application displays the metadata for the SharePoint user.
Figure 11
Test user passes validation
The record in the User Information list is created for the user.
The User Information list is a hidden list in SharePoint. To access the User Information list, browse to the following URL on your SharePoint server.
https://<SERVER NAME>/_catalogs/users/simple.aspx
Figure 12
The hidden user information list in SharePoint
- Click the Create Task button.
The task is created in the Sample Tasks SharePoint list; it is assigned to the specified user.
Figure 13
New task created in list
The Windows Phone 7 application refreshes the list of tasks and displays the new task in the Sample Task SharePoint list.
Figure 14
New task in the application
In this hands-on lab, you saw how to create a Windows Phone 7 application that integrates with the SharePoint People Web service and the SharePoint Lists Web serviceto query, and create SharePoint tasks. You also learned how to validate a user account exists, return the metadata for a user, and assign a task to a user.