Quickstart: Managing app contact stores (XAML)
[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]
On Windows Phone, you can create a contact store for your app. When you save contacts to this store, they will appear on the phone’s People hub, integrated with the user’s other contacts. Your contact store can use the standard set of contact properties, such as name and address, but you can also store custom properties for each contact. Custom properties are not displayed on the contact card in the People hub, but can be accessed programmatically from your app. The contact store APIs also provide a mechanism for you to enumerate changes between your app contact store on the phone and a contact store you maintain in a cloud service in order to synchronize the two stores.
Here, we'll show you how to create a contact store for your app, and how to perform basic operations like adding, updating, and deleting contacts.
Prerequisites
- We recommend that you be familiar with Microsoft Visual Studio and its associated templates.
- We recommend that you be familiar with C# development.
Creating or opening an app contact store
Each Windows Phone app can have a single contact store. You open the store by calling CreateOrOpenAsync. The store will be created when you call this method, if it doesn’t already exist. The overloaded version of this method accepts a member of the ContactStoreSystemAccessMode enumeration and a member of the ContactStoreApplicationAccessMode enumeration, which specify how much access the system and other apps have to your contact store. The ContactStoreSystemAccessMode.ReadOnly value indicates that only your app can modify your contacts. ContactStoreSystemAccessMode.ReadWrite means that the phone can modify your contacts through its built-in contacts experience. ContactStoreApplicationAccessMode.LimitedReadOnly means that other apps can read only the display name and the profile picture of your contacts. ContactStoreApplicationAccessMode.ReadOnly means that other apps can read all of the properties of your contacts. The default settings are ContactStoreSystemAccessMode.ReadOnly and ContactStoreApplicationAccessMode.LimitedReadOnly
ContactStore store = await ContactStore.CreateOrOpenAsync();
ContactStore store = await ContactStore.CreateOrOpenAsync(
ContactStoreSystemAccessMode.ReadWrite,
ContactStoreApplicationAccessMode.ReadOnly);
Adding a contact
After you have opened your contact store, you create a new contact by calling the StoredContact constructor, passing in a reference to your store. The StoredContact object has built-in properties for several common pieces of contact data, such as given name and family name. Each contact also has a field that contains a local ID, which is dynamically assigned by the operating system, and a field for storing a remote ID that can be set by your app. You can use the remote and local IDs to associate contacts in your app’s contact store on the phone with a remote contact store in the cloud.
Warning
If your app uses the ContactStore APIs and uses the StoredContact.RemoteId property to link contacts stored on the phone with contacts stored remotely, it is essential that the value for the RemoteId property is both stable and unique. This means that the remote ID should consistently identify a single user account and should contain a unique tag to guarantee that it does not conflict with the remote IDs of other contacts on the phone, including contacts that are owned by other apps. If you attempt to save a StoredContact that does not have a unique value for the RemoteId property, the save operation may fail.
If the remote IDs used by your app are not guaranteed to be stable and unique, you can use the RemoteIdHelper class shown later in this topic in order to add a unique tag to all of your remote IDs before you add them to the system. Or you can choose to not use the RemoteId property at all and instead you create a custom extended property in which to store remote IDs for your contacts.
In addition to the fields that are provided by the StoredContact object, you can add more properties by calling GetExtendedPropertiesAsync. This returns a dictionary of key value pairs that you can populate with contact data. You can use the fields of the KnownContactProperties class for key values if you want the fields to be consistent with the phone’s internal contact property names. Or you can specify any arbitrary string as a key. After you have set the properties on your contact, save it to the store by calling SaveAsync.
The following code shows a simple implementation of adding a contact.
async public void AddContact(string remoteId, string givenName, string familyName, string email, string codeName)
{
ContactStore store = await ContactStore.CreateOrOpenAsync();
StoredContact contact = new StoredContact(store);
RemoteIdHelper remoteIDHelper = new RemoteIdHelper();
contact.RemoteId = await remoteIDHelper.GetTaggedRemoteId(store, remoteId);
contact.GivenName = givenName;
contact.FamilyName = familyName;
IDictionary<string, object> props = await contact.GetPropertiesAsync();
props.Add(KnownContactProperties.Email, email);
IDictionary<string, object> extprops = await contact.GetExtendedPropertiesAsync();
extprops.Add("Codename", codeName);
await contact.SaveAsync();
}
Updating a contact
You can update a contact by retrieving it from the store, modifying its properties, and then saving it again. The following code example uses FindContactByRemoteIdAsync to retrieve a contact using its remote ID. You can also call FindContactByIdAsync to retrieve a contact by local ID. Then, the properties of the contact are modified and SaveAsync is called to save the contact back to the store.
async private void UpdateContact(string remoteId, string givenName, string familyName, string email, string codeName)
{
ContactStore store = await ContactStore.CreateOrOpenAsync();
RemoteIdHelper remoteIDHelper = new RemoteIdHelper();
string taggedRemoteId = await remoteIDHelper.GetTaggedRemoteId(store, remoteId);
StoredContact contact = await store.FindContactByRemoteIdAsync(taggedRemoteId);
if (contact != null)
{
contact.GivenName = givenName;
contact.FamilyName = familyName;
IDictionary<string, object> props = await contact.GetPropertiesAsync();
props[KnownContactProperties.Email] = email;
IDictionary<string, object> extprops = await contact.GetExtendedPropertiesAsync();
extprops["Codename"] = codeName;
await contact.SaveAsync();
}
}
Deleting a contact
Delete a contact by calling DeleteContactAsync and passing in the local ID of the contact to be deleted. If you want to delete a contact based on the remote ID, call FindContactByRemoteIdAsync then use the value of the Id property to call DeleteContactAsync.
async private void DeleteContact(string id)
{
ContactStore store = await ContactStore.CreateOrOpenAsync();
await store.DeleteContactAsync(id);
}
Querying for Contacts
You can query for all contacts in the store by calling CreateContactQuery. The no-argument version of the method returns the default set of fields for each contact, and uses the default ordering. Call GetContactsAsync on the returned ContactQueryResult object to retrieve the list of returned contacts.
async private void DefaultQuery()
{
ContactStore store = await ContactStore.CreateOrOpenAsync();
ContactQueryResult result = store.CreateContactQuery();
IReadOnlyList<StoredContact> contacts = await result.GetContactsAsync();
ContactListBox.ItemsSource = contacts;
}
If there is a subset of the KnownContactProperties that you know you will need to access, you can create a new ContactQueryOptions and then add property names to the DesiredFields vector to specify that they should be fetched when the query is made. You still must call GetPropertiesAsync to access the field values, but because it does away with extra queries to the database, specifying the desired fields can optimize performance.
You can also set OrderBy to change the field used to order the results, but it is recommended that you use the default ordering because that will provide a consistent user experience across apps.
async private void QueryWithDesiredFields()
{
ContactStore store = await ContactStore.CreateOrOpenAsync();
ContactQueryOptions options = new ContactQueryOptions();
options.DesiredFields.Add(KnownContactProperties.Email);
ContactQueryResult result = store.CreateContactQuery(options);
IReadOnlyList<StoredContact> contacts = await result.GetContactsAsync();
ContactListBox.ItemsSource = contacts;
}
Implementing a RemoteIdHelper class
As stated above, in order to use the RemoteId field of a custom contact, you must ensure that the ID value is unique across all apps on the phone. If your cloud-based contact store does not use IDs that are guaranteed to be unique, you can add the following class to your project that will help you add a unique tag to your IDs before you save a contact to the store. It will also help you remove the unique tag from the ID after you have retrieved it from the store so that you can get your original remote ID back. The following shows the definition of the RemoteIdHelper class.
class RemoteIdHelper
{
private const string ContactStoreLocalInstanceIdKey = "LocalInstanceId";
public async Task SetRemoteIdGuid(ContactStore store)
{
IDictionary<string, object> properties;
properties = await store.LoadExtendedPropertiesAsync().AsTask<IDictionary<string, object>>();
if (!properties.ContainsKey(ContactStoreLocalInstanceIdKey))
{
// the given store does not have a local instance id so set one against store extended properties
Guid guid = Guid.NewGuid();
properties.Add(ContactStoreLocalInstanceIdKey, guid.ToString());
System.Collections.ObjectModel.ReadOnlyDictionary<string, object> readonlyProperties = new System.Collections.ObjectModel.ReadOnlyDictionary<string, object>(properties);
await store.SaveExtendedPropertiesAsync(readonlyProperties).AsTask();
}
}
public async Task<string> GetTaggedRemoteId(ContactStore store, string remoteId)
{
string taggedRemoteId = string.Empty;
System.Collections.Generic.IDictionary<string, object> properties;
properties = await store.LoadExtendedPropertiesAsync().AsTask<System.Collections.Generic.IDictionary<string, object>>();
if (properties.ContainsKey(ContactStoreLocalInstanceIdKey))
{
taggedRemoteId = string.Format("{0}_{1}", properties[ContactStoreLocalInstanceIdKey], remoteId);
}
else
{
// handle error condition
}
return taggedRemoteId;
}
public async Task<string> GetUntaggedRemoteId(ContactStore store, string taggedRemoteId)
{
string remoteId = string.Empty;
System.Collections.Generic.IDictionary<string, object> properties;
properties = await store.LoadExtendedPropertiesAsync().AsTask<System.Collections.Generic.IDictionary<string, object>>();
if (properties.ContainsKey(ContactStoreLocalInstanceIdKey))
{
string localInstanceId = properties[ContactStoreLocalInstanceIdKey] as string;
if (taggedRemoteId.Length > localInstanceId.Length + 1)
{
remoteId = taggedRemoteId.Substring(localInstanceId.Length + 1);
}
}
else
{
// handle error condition
}
return remoteId;
}
}
Before saving any contacts to the store, create a new RemoteIdHelper and call SetRemoteIdGuid. This creates a GUID for your app and stores it in the extended properties of your contact store. It’s ok if you call this method more than once. If a GUID already exists, it will not be overridden.
ContactStore store = await ContactStore.CreateOrOpenAsync();
RemoteIdHelper remoteIdHelper = new RemoteIdHelper();
await remoteIdHelper.SetRemoteIdGuid(store);
Whenever you need to perform an operation with a remote ID, first pass it into GetTaggedRemoteId to retrieve a copy of the ID that has your app’s GUID appended to it.
string taggedRemoteId = await remoteIdHelper.GetTaggedRemoteId(store, remoteId);
StoredContact contact = await store.FindContactByRemoteIdAsync(taggedRemoteId);
If you need to obtain your original remote ID from the remote ID saved in the contact store, call GetUntaggedRemoteId which removes the unique tag and returns the original ID.
string untaggedRemoteId = await remoteIdHelper.GetUntaggedRemoteId(store, taggedRemoteId);
UpdateRemoteContact(untaggedRemoteId, contact);
Saving a contact from a vCard
vCard is a standard file format used for electronic business cards. The ContactInformation class exposes the ParseVcardAsync method, which asynchronously parses the vCard at the specified URI, and then returns a populated ContactInformation object. Pass this and a reference to your contact store to the StoredContact constructor, and then call SaveAsync to save the contact.
The following sample code shows how to save a contact to your custom contact store from a vCard.
public async Task<StoredContact> SaveFromVcard(ContactStore store, IInputStream vCardStream)
{
// Invoke the parser on the passed-in URI.
var contactInfo = await ContactInformation.ParseVcardAsync(vCardStream);
var contact = new StoredContact(store, contactInfo);
await contact.SaveAsync();
return contact;
}
Summary and next steps
Now you have a basic understanding of how to create and manage an app contact store.