---
title: Implementing suggestions for 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/customizing-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).

Azure Search provides a suggestions feature that allows users to view a list of potential search terms in response to partial string inputs.

If you wish to use search suggestions on your website, you need to add a _suggester_ construction to your search indexes. The suggester specifies a list of fields that are used as sources for the content of suggestions.

> **Info:** For detailed information, refer to the following articles:
>
> - [Suggesters](https://docs.microsoft.com/en-us/rest/api/searchservice/suggesters)
> - [Suggestions (Azure Search API)](https://docs.microsoft.com/en-us/rest/api/searchservice/suggestions)

To add a suggester for an Azure Search index managed by Xperience, you need to [customize](https://docs.kentico.com/13/configuring-xperience/setting-up-search-on-your-website/using-azure-cognitive-search/customizing-azure-search.md) the functionality that Xperience uses to build the indexes:

1. Open your Xperience solution in Visual Studio.

2. Create a [custom module class](https://docs.kentico.com/13/custom-development/creating-custom-modules/initializing-modules-to-run-custom-code.md).

3. Override the module's **OnInit** method and assign a handler to the **SearchServiceManager.CreatingOrUpdatingIndex.Execute** event.

4. Perform the following in the event's handler method:

   1. Access the **Microsoft.Azure.Search.Models.Index** object representing the processed index via the **Index** property of the handler's _CreateOrUpdateIndexEventArgs_ parameter.
   2. Write conditions to add different suggesters for specific indexes.
   3. Prepare a **Microsoft.Azure.Search.Models.Suggester** object according to your requirements and add it to the **Suggesters** list of the processed index.

   > **Note:** **Important**
   >
   > The system triggers the **CreatingOrUpdatingIndex** event both when building new indexes and when updating indexes that already exist under the specified Azure Search service. 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).
   >
   > Your code needs to handle the following scenarios:
   >
   > - The index already contains the suggester you are adding.
   > - The index does not yet contain all possible fields (for example in cases where the first processed batch of search documents does not include an object with the required fields).
   >
   > See the code of the example below.

5. Aso deploy the custom module class to the MVC application (otherwise indexing may not work correctly for changes performed through the live site).

6. Open the administration interface.

7. Open the **Smart search** application and **Rebuild** any related Azure Search indexes.

The system creates the customized Azure Search indexes with the specified suggester. You can see the suggester when viewing the details of index fields in the [Microsoft Azure portal](https://portal.azure.com/).

You can now adjust your search functionality to retrieve and display the suggestions – you need to call the **ISearchIndexClient.Documents.Suggest** method when users input search text and process the retrieved **DocumentsSuggestResult** data.

## Example

The following example demonstrates how to create a suggester for an Azure Search index named _dg-store_. The sample suggester uses the _skuname_ field (containing product names) as the source for suggestions.

Start by preparing a separate project in your Xperience solution for the 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, or re-use an existing assembly.
3. Reference the project from both your live site and Xperience administration (_CMSApp_) projects.

Continue by implementing the custom module class and rebuilding your search index:

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

   ```csharp

   using System;
   using System.Collections.Generic;
   using System.Linq;

   using CMS;
   using CMS.DataEngine;
   using CMS.Search.Azure;

   using Microsoft.Azure.Search.Models;

   // 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();

           // Assigns a handler to the CreatingOrUpdatingIndex event for Azure Search indexes
           SearchServiceManager.CreatingOrUpdatingIndex.Execute += AddSuggester;
       }

       private void AddSuggester(object sender, CreateOrUpdateIndexEventArgs e)
       {
           Microsoft.Azure.Search.Models.Index index = e.Index;

           // Ends the handler method if the index name is not 'dg-store'
           if (!index.Name.Equals("dg-store", StringComparison.InvariantCultureIgnoreCase))
           {
               return;
           }

           // Initializes the index's list of suggesters (if it does not exist)
           if (index.Suggesters == null)
           {
               index.Suggesters = new List<Suggester>();
           }

           // Used to determine whether a new suggester was created and needs to be added to the index
           bool newSuggester = false;

           // Checks whether the index already contains a suggester named 'productnamesuggester'
           Suggester suggester = index.Suggesters.FirstOrDefault(s => s.Name == "productnamesuggester");

           // Creates a new suggester if it does not exist
           if (suggester == null)
           {
               suggester = new Suggester
               {
                   Name = "productnamesuggester",
                   SourceFields = new List<string>()
               };
               // A new suggester was created, it needs to be added to the index
               newSuggester = true;
           }

           // Creates a dictionary containing the index's fields
           Dictionary<string, Field> indexFields = index.Fields.ToDictionary(f => f.Name, StringComparer.InvariantCultureIgnoreCase);

           // Confirms that the index contains the 'skuname' field and that it is not yet added as a suggester source field
           if (indexFields.ContainsKey("skuname") && !suggester.SourceFields.Contains("skuname", StringComparer.InvariantCultureIgnoreCase))
           {
               // Adds the 'skuname' fields as a source for suggestions
               suggester.SourceFields.Add("skuname");
           }

           // If a new suggester was created and is not empty, adds it to the index
           if (newSuggester && suggester.SourceFields.Count > 0)
           {
               index.Suggesters.Add(suggester);
           }
       }
   }

   ```
2. Save all changes and **Build** the _SearchCustomization_ project.
3. Sign in to the Xperience administration interface.
4. Open the **Smart search** application and **Rebuild** the _dg-store_ index.

The _dg-store_ Azure Search index now contains the _productnamesuggester_ suggester, using _skuname_ as the source field for the content of suggestions. To retrieve and display the suggestions, you need to implement the required logic in your search functionality (see [Integrating Azure Search](https://docs.kentico.com/13/configuring-xperience/setting-up-search-on-your-website/using-azure-cognitive-search/integrating-azure-search.md)). Call the **ISearchIndexClient.Documents.Suggest** method and process the retrieved **DocumentSuggestResult** data.

```csharp

using System;

using Microsoft.Azure.Search;
using Microsoft.Azure.Search.Models;

...

if (!String.IsNullOrWhiteSpace(searchString))
{
    // Retrieves suggestions based on search input using 'productnamesuggester'
    DocumentSuggestResult suggestResult = searchIndexClient.Documents.Suggest(searchString, "productnamesuggester");
}

```