The sample illustrates the use of the ContactStore class and related APIs to create a contact store for your app. This feature is useful if your app uses an existing cloud-based contact store. The provided APIs allow you to create contacts on the phone that represent the contacts in your remote store. These contacts are displayed and can be modified in the phone’s People hub, just like contacts that are added through the built-in experience. You can use the APIs to update and delete contacts you have created on the phone and also to query for any changes the user has made to the contacts locally so that you can sync those changes to your remote store.

This sample has the following features:

  • Import Remote Contacts – This button creates the app’s contact store and creates new contacts based on the provided list. Typically, this list would come from a network request to a cloud-based contact store maintained by your app. In order to let this sample function as a standalone app, the network request is simulated by reading the remote contacts from a local XML file included with the project, “RemoteContactStore.xml”.

  • Update Remote Contacts – This button updates the contacts in the app’s contact store. Again, the updates would typically come from the cloud-based remote contact store, but in this case, the updates are read from another local XML file, “RemoteContactUpdates.xml”

  • Get Unsynced Local Changes – This button queries the app’s contact store to get a list of changes the user has made locally to the app’s contacts. These changes are compiled in an XML document that could be sent to your cloud-based remote contact store. Because this sample doesn’t use an actual remote store, the resulting XML is simply output to Visual Studio’s Output window.

  • List Contacts – This hyperlink takes you to the ListContacts.xaml page which creates a list of all of the app’s contacts and binds it to a ListBox control.

  • RemoteIdHelper class – The contact store APIs allow you to save a remote ID value with each contact. This allows you to maintain the association between the local contact ID and the ID used by your remote contact store. Your remote contact IDs must be unique among all applications on the phone or the save operation will fail. Since many apps use remote IDs that don’t meet this requirement, this sample provides a helper class, RemoteIdHelper, that helps you to prepend a GUID to each remote ID to make sure that it is unique. The class also allows you to get your original remote ID back, without the attached GUID, so that you can use it to communicate with your remote contact store.

For more info about this feature, see How to perform basic custom contact store operations for Windows Phone..

Build the sample

  1. Start Visual Studio Express 2012 for Windows Phone and select File > Open > Project/Solution.

  2. Go to the directory in which you unzipped the sample. Double-click the Visual Studio Express 2012 for Windows Phone solution (.sln) file.

  3. Use Build > Rebuild Solution to build the sample.

Run the sample

  1. To debug the app and then run it, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  2. Once the app has launched, press the Import Remote Contacts button. This will create the contact store for the app and then read the contacts from the RemoteContactStore.xml file and create new contacts for each listing in the file.

  3. To see that the contacts were created, press the List Contacts hyperlink button. This will take you to the ListContacts.xaml page which uses the contact store APIs to retrieve the all of the app’s contacts. Press the Start button to go to Start and then tap on the tile for the People hub. You will see that the app’s contacts appear there.

  4. Use the back button to return to the first page of the sample app, or just launch the app again, and then tap the Update Remote Contacts button. This will update the app’s contacts with the data in the RemoteContactUpdates.xml file. In this example, one contact is added, one is deleted, and one is updated with new data.

  5. Repeat step 3 to verify that the changes have been made to the app’s contacts.

  6. While in the People hub, use the built-in contact tools to modify some of the information for one or more of the app contacts, such as changing the contact’s family name or given name.

  7. Return to or relaunch the app and then tap the Get Unsynced Local Changes button. This will generate an XML document listing the changes that were made to the local contacts since they were last updated from the remote contact store (or in this example, the local XML file). Because this app doesn’t have a Web service to send the contacts to, the change list is simply printed to Visual Studio’s Output window.

See also