Get contacts
Use the client.Get<Contact>()
or client.GetAsync<Contact>
method to retrieved by ID or by an identifier. You can retrieve a single contact or a batch of contacts.
Get contact by ID
The following example demonstrates how to retrieve a single contact by ID:
using Sitecore.XConnect.Operations;
using System;
using System.Threading.Tasks;
using Sitecore.XConnect;
using Sitecore.XConnect.Client;
namespace Documentation
{
public class GetContact
{
// Async example
public async void ExampleAsync()
{
using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
{
try
{
var reference = new Sitecore.XConnect.ContactReference(Guid.Parse("B9814105-1F45-E611-82E6-34E6D7117DCB"));
Task<Sitecore.XConnect.Contact> contactTask = client.GetAsync<Sitecore.XConnect.Contact>(reference, new ContactExecutionOptions(new
ContactExpandOptions() { });
Contact contact = await contactTask;
}
catch (XdbExecutionException ex)
{
// Manage exceptions
}
}
}
// Sync example
public void Example()
{
using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
{
try
{
var reference = new Sitecore.XConnect.ContactReference(Guid.Parse("B9814105-1F45-E611-82E6-34E6D7117DCB"));
Contact contact = client.Get<Contact>(reference, new ContactExecutionOptions(new
ContactExpandOptions() { });
}
catch (XdbExecutionException ex)
{
// Manage exceptions
}
}
}
}
}
Get contact by identifier
The following examples demonstrate how to retrieve a contact by an identifier. Use the same method for both known and anonymous identifiers. Refer to the contacts overview topic for more information about identifiers
Both source and identifier are case sensitive.
using Sitecore.XConnect;
using System.Threading.Tasks;
using Sitecore.XConnect.Client;
namespace Documentation
{
public class GetContactByIdentifier
{
// Async example
public async void ExampleAsync()
{
using (XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
{
try
{
var reference = new IdentifiedContactReference("twitter", "myrtlesitecore");
Task<Contact> contactTask = client.GetAsync<Contact>(reference, new ContactExecutionOptions(new
ContactExpandOptions() { }));
Contact contact = await contactTask;
}
catch (XdbExecutionException ex)
{
// Manage exceptions
}
}
}
// Sync example
public void Example()
{
using (XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
{
try
{
var reference = new IdentifiedContactReference("twitter", "myrtlesitecore");
Contact contact = client.Get<Contact>(reference, new ContactExecutionOptions(new
ContactExpandOptions() { }));
}
catch (XdbExecutionException ex)
{
// Manage exceptions
}
}
}
}
}
Get contact by alias identifier
All contacts have an alias identifier that consist of a GUID and source defined by Sitecore.XConnect.Constants.AliasIdentifierSource
.
using Sitecore.XConnect;
using System.Threading.Tasks;
using Sitecore.XConnect.Client;
namespace Documentation
{
public class GetContactByAliasIdentifier
{
// Async example
public async void ExampleAsync()
{
using (XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
{
try
{
var reference = new IdentifiedContactReference(Sitecore.XConnect.Constants.AliasIdentifierSource, "1c59d6f4-1ea6-4219-887b-d8f5a0b8104a");
Task<Contact> contactTask = client.GetAsync<Contact>(reference, new ContactExecutionOptions(new
ContactExpandOptions() { }));
Contact contact = await contactTask;
}
catch (XdbExecutionException ex)
{
// Manage exceptions
}
}
}
// Sync example
public void Example()
{
using (XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
{
try
{
var reference = new IdentifiedContactReference(Sitecore.XConnect.Constants.AliasIdentifierSource, "1c59d6f4-1ea6-4219-887b-d8f5a0b8104a");
Contact contact = client.Get<Contact>(reference, new ContactExecutionOptions(new
ContactExpandOptions() { }));
}
catch (XdbExecutionException ex)
{
// Manage exceptions
}
}
}
}
}
Use the .GetAlias()
extension on the Contact
class to retrieve a contact’s alias identifier.
Get multiple contacts
You can use .GetAsync<Contact>()
and .Get<Contact>()
methods to retrieve multiple contacts by passing in an array of contact references. Contacts are returned as a single batch. As shown in the following example, it is possible to retrieve contacts using a mixture of IDs and identifiers:
using Sitecore.XConnect.Operations;
using System;
using System.Collections.Generic;
using Sitecore.XConnect;
using Sitecore.XConnect.Client.Configuration;
using Sitecore.XConnect.Client;
namespace Documentation
{
public class GetMultipleContacts
{
// Async example
public async void AsyncExample()
{
using (XConnectClient client = SitecoreXConnectClientConfiguration.GetClient())
{
try
{
var references = new List<IEntityReference<Contact>>()
{
// Contact ID
new ContactReference(new Guid("{A2814105-1F45-E611-52E6-34E6D7117DCB}")),
// Known identifier
new IdentifiedContactReference("twitter", "myrtlesitecore"),
// Anonymous identifier
new IdentifiedContactReference("adnetwork", "AB973934540244")
};
var contactsTask = client.GetAsync<Contact>(references, new ContactExecutionOptions(new
ContactExpandOptions() { }));
IReadOnlyCollection<IEntityLookupResult<Contact>> contactsResult = await contactsTask;
foreach (var result in contactsResult)
{
if (result.Exists)
{
Contact contact = result.Entity;
}
}
}
catch (XdbExecutionException ex)
{
// Manage exceptions
}
}
}
// Sync example
public void Example()
{
using (XConnectClient client = SitecoreXConnectClientConfiguration.GetClient())
{
try
{
var references = new List<IEntityReference<Contact>>()
{
// Contact ID
new ContactReference(new Guid("{A2814105-1F45-E611-52E6-34E6D7117DCB}")),
// Known identifier
new IdentifiedContactReference("twitter", "myrtlesitecore"),
// Anonymous identifier
new IdentifiedContactReference("adnetwork", "AB973934540244")
};
IReadOnlyCollection<IEntityLookupResult<Contact>> contacts = client.Get<Contact>(references, new ContactExecutionOptions(new
ContactExpandOptions() { }));
foreach (var result in contacts)
{
if (result.Exists)
{
Contact contact = result.Entity;
}
}
}
catch (XdbExecutionException ex)
{
// Manage exceptions
}
}
}
}
}
xConnect returns a IEntityLookupResult<Contact>
for each operation even if the contact was not found. If the contact exists, the Exists
property will be set to true
and the contact can be accessed via the Entity
property. If the contact exists but could not be retrieved, inspect the Exception
property for more information.
If multiple contact references refer to the same contact, xConnect cannot consolidate the list, and returns the contact multiple times.
Get contact facets and related interactions
By default, contacts are returned without facets or related interactions. Use expand options to determine which facets and which range of related interactions should be returned.