Registering custom data types for Azure Search

Azure Search index fields and the fields of objects in Kentico each use a different set of data types. See the Supported data types (Azure Search) article for details.

When building Azure Search indexes, Kentico performs data type mapping and conversions for field values. By default, the following data type mapping is used:

Kentico field data typeC# typeAzure Search data type
Boolean (Yes/No)boolEdm.Boolean
Date
Date and time
DateTimeEdm.DateTimeOffset
Decimal numberdecimalEdm.Double
Floating point number (Double precision)doubleEdm.Double
Integer numberintEdm.Int32
Long integer numberlongEdm.Int64
Long text
Text
stringEdm.String
Time intervalTimeSpanNot mapped
Unique identifier (GUID)GuidEdm.String

If you wish to add values with a custom data type into Azure Search indexes, you first need to register the given data type, and prepare a conversion function that maps the type to one of the types supported by Azure Search. You can also use the same approach if you wish to change how the default Kentico data types map to Azure Search types.

  1. Open your Kentico solution in Visual Studio.
  2. Create a custom module class.
  3. Override the module's OnInit method and call the RegisterMapping method of the CMS.Search.Azure.DataMapper class. The method's parameters specify:
    • The original C# data type
    • The corresponding value from the Microsoft.Azure.Search.Models.DataType enumeration
    • A conversion method
  4. Implement the conversion methods used in your RegisterMapping calls.

When creating Azure Search indexes, the system now uses the specified data types for the appropriate fields.

Index rebuild required

To apply the custom data types to existing Azure Search indexes:

  1. Sign in to the Kentico administration interface.
  2. Open the Smart search application.
  3. Rebuild any related Azure Search indexes.

Example

The following example demonstrates how to re-map the Decimal number data type of Kentico fields to the Edm.String data type used by Azure Search.

Start by preparing a separate project in your Kentico solution for the custom module class:

  1. Open your Kentico solution in Visual Studio.
  2. Create a new Class Library project in the Kentico solution named SearchCustomization.
  3. Add references to the required Kentico libraries (DLLs) for the new project:
    1. Right-click the project and select Add -> Reference.
    2. Switch to the Browse tab, click Browse, and navigate to the Lib folder of your Kentico web project.
    3. Add references to the following libraries:

      • CMS.Base.dll
      • CMS.Core.dll
      • CMS.DataEngine.dll
      • CMS.Search.Azure.dll
  4. Right-click the SearchCustomization project in the Solution Explorer and select Manage NuGet Packages.
  5. Install the Microsoft.Azure.Search package.
  6. Reference the SearchCustomization project from the Kentico web project (CMSApp or CMS).
  7. Edit the SearchCustomization project's AssemblyInfo.cs file (in the Properties folder). 

  8. Add the AssemblyDiscoverable assembly attribute:

    using CMS;
    
    [assembly:AssemblyDiscoverable]

Continue by implementing the custom module class and rebuilding the related search indexes:

  1. Create a new class named CustomAzureSearchModule under the SearchCustomization project, with the following code:

    using CMS;
    using CMS.DataEngine;
    using CMS.Search.Azure;
    
    // Registers the custom module into the system
    [assembly: RegisterModule(typeof(CustomAzureSearchModule))]
    
    public class CustomAzureSearchModule : Module
    {
        // Module class constructor, the system registers the module under the name "CustomAzureSearch"
        public CustomAzureSearchModule()
            : base("CustomAzureSearch")
        {
        }
    
        // Contains initialization code that is executed when the application starts
        protected override void OnInit()
        {
            base.OnInit();
    
            // Registers custom mapping of the decimal data type in Kentico to strings in Azure Search indexes
            DataMapper.Instance.RegisterMapping(typeof(decimal), Microsoft.Azure.Search.Models.DataType.String, ConvertDecimalToString);
        }
    
    	// Converts decimal values to strings
        // The resulting strings use ',' as the group separator, '.' as the decimal separator, and two decimal places
        private string ConvertDecimalToString(object decimalValue)
        {
            return ((decimal)decimalValue).ToString("N2", System.Globalization.CultureInfo.InvariantCulture);
        }
    }
  2. Save all changes and Build the SearchCustomization project.
  3. Sign in to the Kentico administration interface.
  4. Open the Smart search application and Rebuild your Azure indexes.

Any Kentico object fields that use the Decimal number data type are now created as Edm.String type fields within Azure Search indexes.