Reference Data Service

Reference Data Client API

Version:

The Reference Data Client API accesses the Reference Data Service over HTTPS. It is represented by the ReferenceDataHttpClient class, and implements the IReferenceDataClient interface.

Note

Synchronous and asynchronous versions of each method are available. For example, EnsureDefinitionType() and EnsureDefinitionTypeAsync().

All examples use a basic Definition<string,string> defintion type, but you can also create custom types.

Get the Reference Data Client API in a Sitecore context

The following example demonstrates how to retrieve a read-only and a read/write instance of the Reference Data Client API in a Sitecore context:

using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Core;
namespace Documentation
{
    public class RefDataClients
    {
        public async void AsyncExample()
        {
            // Read-write client
            var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;

            // Read-only client
            var readOnlyClient = ServiceLocator.ServiceProvider.GetService(typeof(IReadOnlyReferenceDataClient)) as IReadOnlyReferenceDataClient;
        }
    }
}

Note

In a Sitecore context, configuration controls whether the service implementation or the HTTP client implementation is returned.

Get the Reference Data Client API in a non-Sitecore context

The following example demonstrates how to construct the ReferenceDataHttpClient in a non-Sitecore context:

using System;
using Microsoft.Extensions.Logging;
using Sitecore.Xdb.Common.Web;
using Sitecore.Xdb.ReferenceData.Client;
using Sitecore.Xdb.ReferenceData.Core.Converter;

namespace TestConsoleApp
{
    public class RefDataHttpClientNonSitecore
    {
        public async void AsyncExample()
        {
            var url = "https://refdata/";

            var converter = new DefinitionEnvelopeJsonConverter();

            // Valid certificate thumbprints must be passed in
            var options = CertificateHttpClientHandlerModifierOptions.Parse(
"StoreName=My;StoreLocation=LocalMachine;FindType=FindByThumbprint;FindValue=BC6DBAC6D7E7796E5816DBA268FE2B7036F0F8D9");

            // Optional timeout modifier
            IHttpClientHandlerModifier[] handlers = { new CertificateHttpClientHandlerModifier(options) };

            var logger = new Logger<ReferenceDataHttpClient>(new LoggerFactory());

            var client = new ReferenceDataHttpClient(
                converter,
                new Uri(url),
                handlers,
                logger
             );
         }
     }
 }

Retrieve a definition

The following example demonstrates how to retrieve a definition. If you do not specify a culture, all available cultures are returned.

using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Client;
using Sitecore.Xdb.ReferenceData.Core;
using System.Globalization;

namespace Documentation
{
    public class RefDataGetDefinition
    {
        public async void AsyncExample()
        {
            var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;

            var definitionType = await client.EnsureDefinitionTypeAsync("starfleet ships");
            var criteria = new DefinitionCriteria("voyager", definitionType);

            var definition = await client.GetDefinitionAsync<string, string>(criteria, false);

            var definitionData = definition.CultureData[new CultureInfo("en-us")]; // Get language from e.g. Sitecore.Context.CurrentLanguage.CultureInfo
        }
    }
}

Retrieve a culture-specific definition

The following example demonstrates how to retrieve a culture-specific definition:

using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Client;
using Sitecore.Xdb.ReferenceData.Core;
using System.Globalization;

namespace Documentation
{
    public class RefDataGetDefinitionCulture
    {
        public async void AsyncExample()
        {
            var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;

            // Retrieve Latest Active Definition with Danish Culture Only
            var definitionType = await client.EnsureDefinitionTypeAsync("starfleet ships");
            var criteria = new DefinitionCriteria("voyager", definitionType)
            {
                Culture = new CultureInfo("da") // Get language from e.g. Sitecore.Context.CurrentLanguage.CultureInfo
            };

            var definition = await client.GetDefinitionAsync<string, string>(criteria, false);

            // Get Danish culture
            var data = definition.CultureData[new CultureInfo("da")]; // Get language from e.g.Sitecore.Context.CurrentLanguage.CultureInfo
        }
    }
}

Retrieve culture-invariant definition

The following example demonstrates how to retrieve a culture invariant definition:

using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Client;
using Sitecore.Xdb.ReferenceData.Core;
using System.Globalization;

public class RefDataGetDefinitionCultureInvariant
{
    public async void AsyncExample()
    {
        var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;

        // Retrieve Latest Active Definition Culture Invariant
        var definitionType = await client.EnsureDefinitionTypeAsync("starfleet ships");
        var criteria = new DefinitionCriteria("voyager", definitionType)
        {
            Culture = CultureInfo.InvariantCulture
        };

        var definition = await client.GetDefinitionAsync<string, string>(criteria, false);

        var data = definition.CultureData[CultureInfo.InvariantCulture];
    }
}

Culture invariant data is used when data has a culture, but that culture is not explicitly defined by the source of the data. For example, an external provider might provide a list of city names in English, but does not explicitly specify the culture of the data. In such cases, data should be stored as culture invariant.

Save a Definition

The following example demonstrates how to create and save a new definition in various cultures:

using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Core;
using System.Globalization;

namespace Documentation
{
    public class RefDataSaveDefinition
    {
        public async void Example()
        {
            var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;

            var definitionType = await client.EnsureDefinitionTypeAsync("country");

            var definitionKey = new DefinitionKey("se", definitionType, 1);
            var definition = new Definition<string, string>(definitionKey)
            {
                IsActive = true,
                                    CommonData = "the common data",
                                    CultureData = {
                                            { new CultureInfo("en"), "Sweden" }
                                    }
            };

            // aDd another definition culture
            definition.CultureData[new CultureInfo("se")] = "Sverige";

            // Culture invariant data (has culture, but culture is unknown)
            definition.CultureData[CultureInfo.InvariantCulture] = "Swedenland";

            await client.SaveAsync(definition);
        }
    }
}

Save Multiple Definitions

The following example demonstrates how to save multiple definitions:

using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Core;
using System.Globalization;
using Sitecore.Xdb.ReferenceData.Core.Collections;

namespace Documentation
{
    public class RefDataSaveDefinition
    {
        public async void Example()
        {
            var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;

            var definitionType = await client.EnsureDefinitionTypeAsync("country");

            var definitionKey = new DefinitionKey("se", definitionType, 1);
            var definition = new Definition<string, string>(definitionKey)
            {
                IsActive = true
            };

            definition.CultureData[new CultureInfo("en")] = "Sweden";
            definition.CultureData[new CultureInfo("se")] = "Sverige";

            var definitionKey2 = new DefinitionKey("de", definitionType, 1);
            var definition2 = new Definition<string, string>(definitionKey)
            {
                IsActive = true
            };

            definition.CultureData[new CultureInfo("en")] = "Germany";
            definition.CultureData[new CultureInfo("se")] = "Tyskland";

            var definitions = new DefinitionCollection<string, string>
            {
                definition,
                definition2
            };

            await client.SaveAsync(definitions);
        }
    }
}

Activate a Definition

To activate a definition, set the IsActive property of the definition to true and save the definition.

using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Client;
using Sitecore.Xdb.ReferenceData.Core;
using System.Globalization;

namespace Documentation
{
    public class RefDataActivateDefinition
    {
        public async void AsyncExample()
        {
            var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;

            var definitionType = await client.EnsureDefinitionTypeAsync("starfleet ships");
            var criteria = new DefinitionCriteria("voyager", definitionType);

            var definition = await client.GetDefinitionAsync<string, string>(criteria, false);

            definition.IsActive = true;

            await client.SaveAsync(definition);
        }
    }
}

Get all definitions by a specific type

The following example demonstrates how to get all definitions by a specific type and paginate the results.

using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Core;
namespace Documentation
{
    public class RefDataActivateGetByType
    {
        public async void AsyncExample()
        {
            var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;

            var definitionType = await client.EnsureDefinitionTypeAsync("starfleet ships");

            // Gets the first 10 active definitions
            var definitions = await client.GetDefinitionsByTypeAsync<string, string>(definitionType, true, 1, 10);

            var pageOneDefinitions = definitions.Definitions;
            var currentPage = definitions.PageNumber;
            var currentPageSize = definitions.PageSize;
            var totalDefinitions = definitions.Total; // Total number of definitions with type 'starfleet ships'
        }
    }
}

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