---
title: Customizing Azure Search
related:
- https://docs.kentico.com/13/configuring-xperience/setting-up-search-on-your-website/using-azure-cognitive-search/creating-azure-search-indexes.md
- https://docs.kentico.com/13/configuring-xperience/setting-up-search-on-your-website/using-azure-cognitive-search/integrating-azure-search.md
---
> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).
Xperience provides a customization model that allows developers to extend or adjust how the system builds and maintains [Azure Search](https://docs.kentico.com/13/configuring-xperience/setting-up-search-on-your-website/using-azure-cognitive-search.md) indexes. Customization provides a way to set up Azure Search features that require advanced configuration, as well as adapt to changes in the Azure Search functionality and leverage new features.
For example, you can achieve the following scenarios by customizing the Azure Search:
- [Add scoring profiles for indexes](https://docs.kentico.com/13/configuring-xperience/setting-up-search-on-your-website/using-azure-cognitive-search/customizing-azure-search/adding-scoring-profiles-to-azure-search-indexes.md)
- [Add suggesters for indexes](https://docs.kentico.com/13/configuring-xperience/setting-up-search-on-your-website/using-azure-cognitive-search/customizing-azure-search/implementing-suggestions-for-azure-search.md)
- [Set language analyzers for index fields](https://docs.kentico.com/13/configuring-xperience/setting-up-search-on-your-website/using-azure-cognitive-search/customizing-azure-search/setting-analyzers-for-azure-search.md)
- [Register custom data types for Azure Search](https://docs.kentico.com/13/configuring-xperience/setting-up-search-on-your-website/using-azure-cognitive-search/customizing-azure-search/registering-custom-data-types-for-azure-search.md)
- [Configure the retry policy and batch size used by indexing operations](#configuring-the-azure-search-retry-policy-and-batch-size)
To customize Azure Search, you need to run code during the initialization of the application. Add the required code by creating a custom module class.
1. Open your Xperience solution in Visual Studio.
2. [Add a custom assembly](https://docs.kentico.com/13/custom-development/adding-custom-assemblies.md) (_Class Library_ project) with class discovery enabled to the solution.
3. Reference the project from both your live site and Xperience administration (_CMSApp_) projects.
4. Create the [custom module class](https://docs.kentico.com/13/custom-development/creating-custom-modules/initializing-modules-to-run-custom-code.md) in the class library project.
You can now add Azure Search customizations by overriding the module's **OnInit** method. For most typical scenarios, you need to assign handler methods for [Azure Search indexing events](#reference---azure-search-events).
> **Note:** **Azure Search SDK requirement**
>
> Most types of customizations additionally require usage of the [Azure Search .NET SDK](https://docs.microsoft.com/en-us/azure/search/search-howto-dotnet-sdk), which you can integrate by installing the **Microsoft.Azure.Search** [NuGet package](https://www.nuget.org/packages/Microsoft.Azure.Search) into your custom project.
## Configuring the Azure Search retry policy and batch size
In addition to custom handling of [Azure Search indexing events](#reference---azure-search-events), the Xperience API allows developers to configure the retry policy and batch size that the system uses when performing Azure Search indexing operations.
Get an **instance** of the **SearchEngineConfiguration** class within the initialization code of your custom module class and set its properties (see the sections below).
### Retry policy
Because Azure Search indexes are cloud-based and hosted outside of the Xperience application, requests that interact with indexes may fail due to network errors, service unavailability, or other connection problems. To prevent any issues, the system sends all indexing requests using a retry policy with exponential backoff. Requests that fail are automatically repeated several times with exponentially growing time intervals.
If necessary, you can adjust the parameters of the retry policy by setting the following properties of the **SearchEngineConfiguration** class:
- **RetryCount** – sets the maximum number of retry attempts that the system performs after an indexing operation fails. Setting the value to 0 disables the retry functionality (not recommended). The default value is 5.
- **MaxBackoffTimeSeconds** – sets the ceiling for the time interval between retry attempts (in seconds). The default value is 8.
For example, if you set **RetryCount** to 7 and **MaxBackoffTimeSeconds** to 16, the system retries failed indexing operations up to 7 times, with the following intervals between the attempts (in seconds): 0, 1, 2, 4, 8, 16, 16
### Batch size
The **DocumentsBatchSize** property of the **SearchEngineConfiguration** class sets the maximum number of [search documents](https://docs.microsoft.com/en-us/azure/search/search-what-is-an-index) processed by a single request to the Azure Search service. For example, when building a new index that covers 2500 pages in Xperience with a maximum batch size of 1000, the system first creates the Azure Search index with 1000 documents, and then updates the index twice by adding 1000 and 500 documents.
The default document batch size value is **1000.** When setting a custom value, you need to respect the [API Request limits of the Azure Search service](https://docs.microsoft.com/en-us/azure/search/search-limits-quotas-capacity). For example, you may need to decrease the batch size if the total request size exceeds the maximum limit of 16 MB (when indexing a large number of objects with long text values).
> **Info:** **Azure Search document batch size vs. Index batch size**
>
> The maximum number of search documents processed per request is also limited by the **Batch size** setting of individual search indexes, which can be configured in the Xperience administration interface. The index batch size sets the maximum number of records that the system retrieves per query when loading data from the Xperience database, which effectively also limits the document batch size of Azure Search requests. By default, the index batch size is **500**.
>
> The **SearchEngineConfiguration.DocumentsBatchSize** property only has an effect for indexes whose batch size setting is greater than the property's value.
### Example
```csharp
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();
var azureSearchConfiguration = SearchEngineConfiguration.Instance;
// Customizes the Azure Search retry policy
azureSearchConfiguration.RetryCount = 7;
azureSearchConfiguration.MaxBackoffTimeSeconds = 16;
// Sets the maximum number of search documents processed by each request to the Azure Search service
azureSearchConfiguration.DocumentsBatchSize = 500;
}
}
```
## Changing the default domain suffix of Azure search services
By default, the system assumes your Azure Search services are hosted on the _search.windows.net_ domain (true for the majority of commercial subscriptions). Search requests for Azure indexes are generated using this suffix and the provided search service name.
However, certain Azure subscriptions or licenses host search services under a different domain. For example, [Azure Government](https://azure.microsoft.com/en-us/global-infrastructure/government/get-started/) subscriptions use the _search.azure.us_ domain. If your services are hosted on a different domain, you can set the **CMSAzureSearchDnsSuffix** configuration key to change the suffix used by the system when generating Azure search requests.
**MVC 5 development model.** Applies only when building with ASP.NET MVC 5. If this page also covers ASP.NET Core, that version is in its own block.
```xml title="web.config"
...
```
**ASP.NET Core development model.** Applies only when building with ASP.NET Core. If this page also covers MVC 5, that version is in its own block.
The following example configures the system to generate requests in format: _myazureservice.search.azure.us_
```js title="appsettings.json"
"CMSAzureSearchDnsSuffix": "search.azure.us",
```
## Reference - Azure Search events
This section provides an overview of system events that developers can handle to customize how the system builds and maintains Azure Search indexes.
> **Info:** For general information about Azure Search indexes and their structure, refer to the [Create an Azure Search index](https://docs.microsoft.com/en-us/azure/search/search-what-is-an-index) article.
### Indexes
Class: **SearchServiceManager**
| Event | Event types | Description |
| ----------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CreatingOrUpdatingIndex | Execute | Occurs when the system sends requests to create or update the definition of an index within an Azure Search service, for example when rebuilding Azure Search indexes in Xperience.
The event is NOT triggered when adding, updating or removing documents within an existing index, unless an update of the index's definition is required (e.g. when adding a document with new fields for the first time).
Depending on the number of indexed pages or objects and the used batch size, the event may occur multiple times when building a single search index – separately for each batch of processed search documents that include a new field not yet contained by the index. When implementing handlers for the event, always consider cases where the related index already exists and does not yet contain all possible fields.
Examples of use:
[Adding a scoring profile for an index](https://docs.kentico.com/13/configuring-xperience/setting-up-search-on-your-website/using-azure-cognitive-search/customizing-azure-search/adding-scoring-profiles-to-azure-search-indexes.md)
[Adding a suggester for an index](https://docs.kentico.com/13/configuring-xperience/setting-up-search-on-your-website/using-azure-cognitive-search/customizing-azure-search/implementing-suggestions-for-azure-search.md)
Handler parameters: **CreateOrUpdateIndexEventArgs**
**Index** (Microsoft.Azure.Search.Models.Index) – Azure Search .NET SDK object representing the related index.
**SearchService** (CMS.Search.Azure.SearchService) – provides information about the Azure Search service specified for the index. |
### Documents
Class: **DocumentCreator** (access an **Instance** of the class to assign event handlers)
| Event | Event types | Description |
| ------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CreatingDocument | Before
After
Failure | Occurs when the system creates individual documents within an Azure Search index. Triggered separately for every indexed object.
Use the **Before** event if you wish to modify the processed source data for the given document (_SearchDocument_ property of the handler's _CreateDocumentEventArgs_ parameter). Use the **After** event to adjust the properties of the resulting _Document_ object (_Document_ property of the handler's _CreateDocumentEventArgs_ parameter) or its fields _(Fields_ property of the handler's _CreateDocumentEventArgs_ parameter).
Handler parameters: **CreateDocumentEventArgs**
**Document** (Microsoft.Azure.Search.Models.Document) – Azure Search .NET SDK object representing the related document.
**Fields** (IEnumerable) – A collection of Azure Search .NET SDK objects containing fields of the created document.
**SearchDocument** (CMS.DataEngine.SearchDocument) – object holding the fields and values of the indexed data for the given object.
**Searchable** (CMS.DataEngine.ISearchable) – the Xperience object whose data is being indexed. Can be converted to a specific [Info object](https://docs.kentico.com/13/custom-development/database-table-api.md).
**SearchIndex** (CMS.DataEngine.ISearchIndexInfo) – object representing the related search index in Xperience. |
| AddingDocumentValue | Execute | Occurs when the system sets the values of individual fields for documents within an Azure Search index. Triggered separately for each field of every indexed object.
You can use the event to modify the **AzureName** and **Value** properties of the handler's _AddDocumentValueEventArgs_ parameter before the value is converted to an [Azure Search data type](https://docs.kentico.com/13/configuring-xperience/setting-up-search-on-your-website/using-azure-cognitive-search/customizing-azure-search/registering-custom-data-types-for-azure-search.md) and saved to the document.
Handler parameters: **AddDocumentValueEventArgs**
**AzureName** (string) – name of the resulting field in the Azure Search document (Microsoft.Azure.Search.Models.Document).
**Document** (Microsoft.Azure.Search.Models.Document) – Azure Search .NET SDK object representing the related document.
**Fields** (IEnumerable) – A collection of Azure Search .NET SDK objects containing all fields of the processed document.
**Name** (string) – the name of the source field in the _SearchDocument_ data.
**SearchDocument** (CMS.DataEngine.SearchDocument) – object holding the fields and values of the indexed data for the given object.
**Searchable** (CMS.DataEngine.ISearchable) – the Xperience object whose data is being indexed. Can be converted to a specific [Info object](https://docs.kentico.com/13/custom-development/database-table-api.md).
**SearchIndex** (CMS.DataEngine.ISearchIndexInfo) – object representing the related search index in Xperience.
**Value** (object) – the value assigned to the resulting field in the Azure Search document. |
### Fields
Class: **DocumentFieldCreator** (access an **Instance** of the class to assign event handlers)
| Event | Event types | Description |
| -------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CreatingField | Before
After
Failure | Occurs when the system creates individual fields for a document within an Azure Search index. Triggered separately for each field of every indexed object.
Use the **Before** event if you wish to manually initialize the _Field_ object (Microsoft.Azure.Search.Models.Field). Use the **After** event to adjust the properties of the resulting _Field_ object (_Field_ property of the handler's _CreateFieldEventArgs_ parameter).
Example of use: [Setting language analyzers for index fields](https://docs.kentico.com/13/configuring-xperience/setting-up-search-on-your-website/using-azure-cognitive-search/customizing-azure-search/setting-analyzers-for-azure-search.md)
Handler parameters: **CreateFieldEventArgs**
**Field** (Microsoft.Azure.Search.Models.Field) – Azure Search .NET SDK object representing the related field.
**SearchField** (CMS.DataEngine.ISearchField) – object representing the search settings of the field in Xperience.
**Searchable** (CMS.DataEngine.ISearchable) – the Xperience object whose data is being indexed. Can be converted to a specific [Info object](https://docs.kentico.com/13/custom-development/database-table-api.md).
**SearchIndex** (CMS.DataEngine.ISearchIndexInfo) – object representing the related search index in Xperience. |
| CreatingFields | Before
After
Failure | Occurs when the system creates the set of fields for a document within an Azure Search index. Triggered separately for every indexed object.
Use the **Before** event if you wish to modify or extend the collection of processed source fields (_SearchFields_ property of the handler's _CreateFieldsEventArgs_ parameter). Use the **After** event to modify the resulting list of Azure Search fields (_Fields_ property of the handler's _CreateFieldsEventArgs_ parameter).
Handler parameters: **CreateFieldsEventArgs**
**Fields** (List) – list of Azure Search .NET SDK objects representing the related fields.
**SearchFields** (IEnumerage) – collection of objects representing the search settings of the given fields in Xperience.
**Searchable** (CMS.DataEngine.ISearchable) – the Xperience object whose data is being indexed. Can be converted to a specific [Info object](https://docs.kentico.com/13/custom-development/database-table-api.md).
**SearchIndex** (CMS.DataEngine.ISearchIndexInfo) – object representing the related search index in Xperience. |
> **Info:** **Xperience system fields**
>
> Search indexes in Xperience contain special system fields that are required for general functionality and various other features. For example _\_content_, _\_index_, _\_idcolumnname_. We do not recommend modifying or renaming the system fields within custom handlers of field or search document events.
>
> In most cases, the names of system fields in Xperience start with an underscore. When creating matching fields within Azure Search indexes, the **sys\_** prefix is used instead (to comply with the [Azure Search naming rules](https://docs.microsoft.com/en-us/rest/api/searchservice/naming-rules)).