Krebil.UmbracoAzureSearch 18.1.0

Krebil.UmbracoAzureSearch

An Azure AI Search provider for Umbraco Search.

Note: Umbraco Search is a work in progress. Things might change at a moment's notice.

Prerequisites

• Umbraco v17+
• An Azure AI Search instance (create one in the Azure portal)

Installation

Install the core Umbraco Search package and this provider:

dotnet add package Umbraco.Cms.Search.Core
dotnet add package Krebil.UmbracoAzureSearch

Configuration

Add your Azure AI Search credentials to appsettings.json:

{
  "UmbracoAzureSearch": {
    "Endpoint": "https://your-search-service.search.windows.net",
    "Key": "your-api-key"
  }
}

Microsoft Entra ID (managed identity)

To authenticate without an API key, pass a TokenCredential when registering and leave Key out of the configuration:

builder.Services.AddUmbracoAzureSearch(builder.Config, new DefaultAzureCredential());

DefaultAzureCredential comes from the Azure.Identity package. The search service's API access control must allow role-based access, and the identity needs the Search Service Contributor role (to create indexes) and the Search Index Data Contributor role (to index and query). A credential passed in code takes precedence over a configured Key.

Registration

Register the services via a composer:

public sealed class SearchComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.AddSearchCore();
        builder.Services.AddUmbracoAzureSearch(builder.Config);
    }
}

AddUmbracoAzureSearch registers the four default Umbraco Search indexes (Umb_Content, Umb_PublishedContent, Umb_Media and Umb_Members) against Azure AI Search. To change one of them or add your own, configure IndexOptions after this call; the last registration for an alias wins.

Usage

Inject IAzureSearchSearcher (or ISearcherResolver to resolve it by index alias) and call SearchAsync. See the Umbraco Search documentation for the full API: filtering, faceting, sorting, pagination, culture/segment variants, and protected content all work the same way.

public class MySearchService(IAzureSearchSearcher searcher)
{
    public async Task<SearchResult> SearchAsync(string query)
        => await searcher.SearchAsync(
            indexAlias: SearchConstants.IndexAliases.PublishedContent,
            query: query,
            filters:
            [
                new KeywordFilter("genre", ["rock", "pop"], Negate: false)
            ],
            facets:
            [
                new KeywordFacet("genre"),
                new IntegerRangeFacet("releaseYear",
                [
                    new("50s", 1950, 1960),
                    new("80s", 1980, 1990)
                ])
            ],
            sorters:
            [
                new IntegerSorter("releaseYear", Direction.Descending)
            ],
            skip: 0,
            take: 10
        );
}

Azure AI Search limitations

• No guaranteed ordering without an explicit sort — always provide a sorter when result order matters.
• No multiple facet types on the same field — e.g. IntegerExactFacet and IntegerRangeFacet cannot both be applied to the same field in a single query. The provider works around this internally by running a separate query per field, so mixed facet types across different fields work fine.