1. Get contacts

Get contact with facets

Version:

You must specify which facets should be returned with a contact or batch of contacts by passing an array of facet keys into the ContactExpandOptions. The only facets that are always returned if they exist are ConsentInfo and MergeInfo.

In the following example, the default EmailAddressList and AddressList facets are requested as part of the contact expand options:

var contacts = await client.GetAsync<Contact>(references, new ContactExecutionOptions(new Sitecore.XConnect.ContactExpandOptions(EmailAddressList.DefaultFacetKey, AddressList.DefaultFacetKey)));

A facet is added to the contact’s Facets dictionary if the facet exists for that contact. If the facet you requested is not defined in the model xConnect will throw an exception when the request is executed. When the contact or contacts have been returned, use the .GetFacet<T>() method on the contact to retrieve the facet object:

EmailAddressList myFacetObject = contact.GetFacet<EmailAddressList>(EmailAddressList.DefaultFacetKey);

The method .GetFacet<T>() will return null if:

  • The facet was not requested as part of the ContactExpandOptions when the contact was initially retrieved

  • The facet has not set for a particular contact

  • The combination of type and key is incorrect

The following example demonstrates how to retrieve and work with the EmailAddressList facet:

using Sitecore.XConnect.Collection.Model;
using Sitecore.XConnect.Operations;
using System;
using System.Collections.Generic;
using System.Linq;
using Sitecore.XConnect;
using Sitecore.XConnect.Client;

namespace Documentation
{
    public class GetFacetsMultiple
    {
        // Asyc example
        public async void ExampleAsync()
        {
            using (XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    var references = new List<IEntityReference<Sitecore.XConnect.Contact>>()
                    {
                        // Contact ID
                        new ContactReference(new Guid("{A2814105-1F45-E611-52E6-34E6D7117DCB}")),
                        // Username
                        new IdentifiedContactReference("twitter", "myrtlesitecore"),
                        // Ad network ID
                        new IdentifiedContactReference("twitter", "AB973934540244")
                    };

                    // Get a reference to the facet by name
                    string emailsFacetKey = Sitecore.XConnect.Collection.Model.CollectionModel.FacetKeys.EmailAddressList;

                    // Pass the facet name into the ContactExpandOptions constructor
                    var contactsTask = client.GetAsync<Sitecore.XConnect.Contact>(references, new ContactExecutionOptions(
                    new ContactExpandOptions(emailsFacetKey)
                    {
                    }));

                    IReadOnlyCollection<IEntityLookupResult<Contact>> contacts = await contactsTask;

                    if (contacts != null && contacts.Any())
                    {
                        foreach (var c in contacts)
                        {
                            // For each contact, retrieve the facet - will return null if contact does not have this facet set
                            EmailAddressList emailsFacetData = c.Entity.GetFacet<EmailAddressList>(emailsFacetKey);

                            if (emailsFacetData != null)
                            {
                                // Do something with data - e.g. display in view
                                EmailAddress preferred = emailsFacetData.PreferredEmail;
                            }
                        }
                    }
                }
                catch (XdbExecutionException ex)
                {
                    // Handle exceptions
                }
            }
        }

        // Sync example
        public void Example()
        {
            using (XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    var references = new List<IEntityReference<Contact>>()
                    {
                        // Contact ID
                        new ContactReference(new Guid("{A2814105-1F45-E611-52E6-34E6D7117DCB}")),
                        // Username
                        new IdentifiedContactReference("twitter", "myrtlesitecore"),
                        // Ad network ID
                        new IdentifiedContactReference("twitter", "AB973934540244")
                    };

                    // Get a reference to the facet by name
                    string emailsFacetKey = CollectionModel.FacetKeys.EmailAddressList;

                    // Pass the facet name into the ContactExpandOptions constructor
                    IReadOnlyCollection<IEntityLookupResult<Contact>> contacts = client.Get<Contact>(references, new ContactExecutionOptions(new ContactExpandOptions(emailsFacetKey)
                    {
                    }));

                    if (contacts != null && contacts.Any())
                    {
                        foreach (var c in contacts)
                        {
                            // For each contact, retrieve the facet - will return null if contact does not have this facet set
                            EmailAddressList emailsFacetData = c.Entity.GetFacet<EmailAddressList>(emailsFacetKey);

                            if (emailsFacetData != null)
                            {
                                // Do something with data - e.g. display in view
                                EmailAddress preferred = emailsFacetData.PreferredEmail;
                            }
                        }
                    }
                }
                catch (XdbExecutionException ex)
                {
                    // Handle exceptions
                }
            }
        }
    }
}
Note

All built-in facet models have a DefaultFacetKey property - for example, WebVisit.DefaultFacetKey.

Get facets using the default facet key

All built-in facet models have a FacetKey attribute that associates the default facet key with the facet model.

[FacetKey(CollectionModel.FacetKeys.EmailAddressList)]
public class EmailAddressList : Facet

If a facet key is not specified, xConnect will fall back to the default value. Add the FacetKey attribute to your own facet models to mimic this behavior. In the following example, .Expand<EmailAddressList>() and .GetFacet<EmailAddressList>() are used without specifying a facet key.

Important

An exception will be thrown if the facet model does not have a FacetKey attribute.

using Sitecore.XConnect.Collection.Model;
using Sitecore.XConnect.Operations;
using System;
using System.Collections.Generic;
using System.Linq;
using Sitecore.XConnect;
using Sitecore.XConnect.Client;

namespace Documentation
{
    public class GetFacetsMultipleDefaultKey
    {
        // Asyc example
        public async void ExampleAsync()
        {
            using (XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    var contactsTask = client.GetAsync<Sitecore.XConnect.Contact>(new ContactReference(new Guid("{A2814105-1F45-E611-52E6-34E6D7117DCB}")),
                    new ContactExecutionOptions(new ContactExpandOptions().Expand<EmailAddressList>()));

                    Contact contact = await contactsTask;

                    if (contact != null)
                    {
                        // For each contact, retrieve the facet - will return null if contact does not have this facet set
                        EmailAddressList emailsFacetData = contact.GetFacet<EmailAddressList>();

                        if (emailsFacetData != null)
                        {
                            // Do something with data - e.g. display in view
                            EmailAddress preferred = emailsFacetData.PreferredEmail;
                        }
                    }
                }
                catch (XdbExecutionException ex)
                {
                    // Handle exceptions
                }
            }
        }

        // Asyc example
        public void Example()
        {
            using (XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    Contact contact = client.Get<Sitecore.XConnect.Contact>(new ContactReference(new Guid("{A2814105-1F45-E611-52E6-34E6D7117DCB}")),
                    new ContactExecutionOptions(new ContactExpandOptions().Expand<EmailAddressList>()));

                    if (contact != null)
                    {
                        // For each contact, retrieve the facet - will return null if contact does not have this facet set
                        EmailAddressList emailsFacetData = contact.GetFacet<EmailAddressList>();

                        if (emailsFacetData != null)
                        {
                            // Do something with data - e.g. display in view
                            EmailAddress preferred = emailsFacetData.PreferredEmail;
                        }
                    }
                }
                catch (XdbExecutionException ex)
                {
                    // Handle exceptions
                }
            }
        }
    }
}
Note

If you have used a facet model (such as EmailAddressList) to define multiple facets, consider storing the non-default facet keys as constants in your model class.

Setting or updating facets

You must use the .SetFacet() extension method to update facets. For more information, see: Set a contact facet.

If you have suggestions for improving this article, let us know!