Krebil.UmbracoAzureSearch 18.2.2

There is a newer version of this package available.
See the version list below for details.
dotnet add package Krebil.UmbracoAzureSearch --version 18.2.2
                    
NuGet\Install-Package Krebil.UmbracoAzureSearch -Version 18.2.2
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Krebil.UmbracoAzureSearch" Version="18.2.2" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Krebil.UmbracoAzureSearch" Version="18.2.2" />
                    
Directory.Packages.props
<PackageReference Include="Krebil.UmbracoAzureSearch" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Krebil.UmbracoAzureSearch --version 18.2.2
                    
#r "nuget: Krebil.UmbracoAzureSearch, 18.2.2"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Krebil.UmbracoAzureSearch@18.2.2
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Krebil.UmbracoAzureSearch&version=18.2.2
                    
Install as a Cake Addin
#tool nuget:?package=Krebil.UmbracoAzureSearch&version=18.2.2
                    
Install as a Cake Tool

Krebil.UmbracoAzureSearch

An Azure AI Search provider for Umbraco Search.

NuGet

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

Prerequisites

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

Suggestions

Pass maxSuggestions to get suggested next queries for a search box. Each suggestion is the typed query with its last word completed, so "red bo" can give "red boat" and "red board". Suggestions come back in the same response as the results.

[ApiController]
[Route("api/search")]
public class SearchController(IAzureSearchSearcher searcher) : ControllerBase
{
    [HttpGet]
    public async Task<IActionResult> Get(string query)
    {
        var result = await searcher.SearchAsync(
            indexAlias: SearchConstants.IndexAliases.PublishedContent,
            query: query,
            maxSuggestions: 5);

        return Ok(new { result.Total, suggestions = result.Suggestions ?? [] });
    }
}
  • Suggestions are lowercase.
  • Suggestions is null when there are none: maxSuggestions is 0, the query is blank, or nothing matches. Handle null, not only an empty list.
  • Suggestions use the same culture, segment, protected-content and filter rules as the results, except text filters (see the limitations below).
  • The Delivery API and the backoffice do not ask for suggestions, so only your own code triggers the extra request.

By default every index suggests from its highest-relevance texts, such as content names. Configure an index under its alias to change that:

{
  "UmbracoAzureSearch": {
    "Suggestions": {
      "Umb_PublishedContent": {
        "Fields": [ "title", "subtitle" ]
      },
      "Umb_Members": {
        "Enabled": false
      }
    }
  }
}
Setting Default Effect
Enabled true false gives the index no suggestions and saves the index space.
Fields Highest-relevance texts The Umbraco fields whose texts feed suggestions.

Upgrading

Existing indexes get suggestions added on startup when EnsureIndicesOnStartup() is registered, but their existing content has no suggestions yet. Rebuild each index in the backoffice to fill them. A rebuild also adds suggestions to an index on sites that do not ensure indexes on startup.

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.
  • Text filters do not narrow suggestions — Azure rejects them in suggestion requests, so suggestions ignore TextFilter. Suggestions still respect the culture, segment, protected-content and all other filters.
Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
18.3.5 90 10/30/2026
18.3.4 76 10/30/2026
18.3.3 70 10/30/2026
18.3.2 69 10/30/2026
18.3.1 78 10/29/2026
18.3.0 71 10/29/2026
18.2.2 681 10/20/2026
18.1.0 410 10/8/2026
18.0.0 74 10/8/2026
17.4.5 610 10/30/2026
17.4.4 71 10/30/2026
17.4.3 81 10/30/2026
17.4.2 73 10/30/2026
17.4.1 84 10/29/2026
17.4.0 163 10/29/2026
17.3.1 72 10/20/2026
17.2.0 75 10/8/2026
17.1.0 62 10/8/2026
17.0.0 71 10/8/2026
1.0.3 797 8/24/2026
Loading failed