Krebil.UmbracoAzureSearch
18.2.2
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
<PackageReference Include="Krebil.UmbracoAzureSearch" Version="18.2.2" />
<PackageVersion Include="Krebil.UmbracoAzureSearch" Version="18.2.2" />
<PackageReference Include="Krebil.UmbracoAzureSearch" />
paket add Krebil.UmbracoAzureSearch --version 18.2.2
#r "nuget: Krebil.UmbracoAzureSearch, 18.2.2"
#:package Krebil.UmbracoAzureSearch@18.2.2
#addin nuget:?package=Krebil.UmbracoAzureSearch&version=18.2.2
#tool nuget:?package=Krebil.UmbracoAzureSearch&version=18.2.2
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
);
}
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.
Suggestionsisnullwhen there are none:maxSuggestionsis 0, the query is blank, or nothing matches. Handlenull, 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.
IntegerExactFacetandIntegerRangeFacetcannot 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 | Versions 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. |
-
net10.0
- Azure.Search.Documents (>= 12.1.0-beta.1)
- Throw (>= 1.4.0)
- Umbraco.Cms.Api.Common (>= 18.0.0 && < 19.0.0)
- Umbraco.Cms.Api.Management (>= 18.0.0 && < 19.0.0)
- Umbraco.Cms.Search.Core (>= 18.0.0 && < 19.0.0)
- Umbraco.Cms.Web.Common (>= 18.0.0 && < 19.0.0)
- Umbraco.Cms.Web.Website (>= 18.0.0 && < 19.0.0)
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 |