xConnect: Creating Contacts in Sitecore 9

As discussed in the previous post, the schema for the collection model in xDB changed from earlier versions, making it simpler and more flexible for different types of interactions. Also, the way you connect to xDB to search, add or retrieve data has changed. Now, everything goes through the XConnectClient.

Initializing the XConnectClient

In this example, I will be creating a connection to the xConnect services using a basic console app. Start off by creating a new Console application in Visual Studio, targeting the 4.6.2 version of the .NET Framework. Then, add references to the following assemblies:

• Sitecore.XConnect.dll
• Sitecore.XConnect.Client.dll
• Sitecore.XConnect.Collection.Model.dll

You will also need to add the following NuGet packages to your solution:

• Newtonsoft.Json
• System.Interactive.Async.Providers
• System.Net.Http.Formatting.Extension

in the Main method, create an instance of the XConnectClientConfiguration object, initialize it, then use it to create an instance of the XConnectClient.

static void Main(string[] args)
{
    var config = new XConnectClientConfiguration(
        new XdbRuntimeModel(CollectionModel.Model),
        new Uri("https://sc9_xconnect"),
        new Uri("https://sc9_xconnect"));

    try
    {
        config.Initialize();
    }
    catch (XdbModelConflictException ex)
    {
        Console.WriteLine(ex.Message);
        return;
    }

    using (var client = new XConnectClient(config))
    {
        // We'll create our new contact here in a moment.
    }
}

When creating the XConnectClientConfiguration object, I am using the overload requiring three parameters:

1. The Collection model needed for this connection – I specified the default collection model, but in a future post, I will explain how to pass in a custom, extended model.
2. The Uri for the Collection service
3. The Uri for the Search service

Once we have our configuration defined, we call Initialize() or InitializeAsync() to validate the model against a remote model configured in xConnect.

Creating a new Contact

When creating a new Contact, start by creating a new ContactIdentifier object.

var identifier = new ContactIdentifier("twitter", "longhorntaco", ContactIdentifierType.Known);

Because xDB now supports multiple identifiers for a contact, you could also create an array of identifiers:

var identifiers = new ContactIdentifier[]
{
    new ContactIdentifier("twitter", "longhorntaco", ContactIdentifierType.Known),
    new ContactIdentifier("domain", "longhorn.taco", ContactIdentifierType.Known)
}

Now, create a Contact object with this/these identifiers.

var contact = new Contact(identifiers);

All that’s left to do is submit this new Contact to xConnect!

client.AddContact(contact);
client.Submit(); // or client.SubmitAsync();

Altogether, it should look something like this:

static void Main(string[] args)
{
    var config = new XConnectClientConfiguration(
        new XdbRuntimeModel(CollectionModel.Model),
        new Uri("https://sc9_xconnect"),
        new Uri("https://sc9_xconnect"));

    try
    {
        config.Initialize();
    }
    catch (XdbModelConflictException ex)
    {
        Console.WriteLine(ex.Message);
        return;
    }

    using (var client = new XConnectClient(config))
    {
        var identifiers = new ContactIdentifier[]
        {
            new ContactIdentifier("twitter", "longhorntaco", ContactIdentifierType.Known),
            new ContactIdentifier("domain", "longhorn.taco", ContactIdentifierType.Known)
        };
        var contact = new Contact(identifiers);
        client.AddContact(contact);
        client.Submit();
    }
}

Adding info to the Contact

In the example above, we only created a contact with an identifier. We didn’t do anything to add personal data like First Name, Last Name, Email Address, etc…

To do this, simply instantiate the appropriate Facet object and call the SetFacet method on the XConnectClient.

var contact = new Contact(identifiers);

var personalInfoFacet = new PersonalInformation
{
    FirstName = "Longhorn",
    LastName = "Taco"
};
client.SetFacet<PersonalInformation>(contact, PersonalInformation.DefaultFacetKey, personalInfoFacet);

var emailFacet = new EmailAddressList(new EmailAddress("longhorn@taco.com", true), "twitter");
client.SetFacet<EmailAddressList>(contact, EmailAddressList.DefaultFacetKey, emailFacet);

client.AddContact(contact);

And that’s how you create a new Contact in xDB using the xConnect client!

Source code can be found on GitHub.

Happy Sitecore Trails, my friend!