Krebil.UmbracoAzureSearch 18.3.5

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"
  }
}

For a serverless Azure AI Search service, also set Serverless:

{
  "UmbracoAzureSearch": {
    "Serverless": true
  }
}

The package also reads the older key IsServerless. When both keys are set, IsServerless wins.

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. To change the Azure settings of an index, see Index configuration.

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
        );
}

Features

• Index configuration: settings per index, from appsettings or code.
• Index definition: choose the content, fields and field attributes of an index.
• Analyzers: language analyzers per culture, in one index or one index per culture.
• Customizing Azure: change the Azure index definition and queries in code.
• Zero-downtime rebuild: rebuild into a second index and swap, so searches keep working.
• Scoring profiles: field boosts, your own profiles, and a profile per query.
• Spell check: correct mistyped query terms per culture.
• Suggestions: complete the last word of a query, or suggest documents, for a search box.
• Azure AI Search limitations: Azure limits that change how some Umbraco Search features behave.

Upgrading

Read the upgrade guide before you update the package.