GXE.Umbraco.AzureAISearch 1.10.1

Umbraco.AzureAISearch

Azure AI Search provider for Umbraco Search — designed to work seamlessly with Microsoft Foundry while also supporting direct ranked search via the ISearcher interface.

Requires Umbraco 17+ and an Azure AI Search instance.

Why this package?

Microsoft Foundry expects an Azure AI Search index with specific fields — content, url, and title — to ground AI responses. This package indexes Umbraco content directly into that schema, so you can connect your CMS to Foundry without any manual field mapping or data transformation.

At the same time, it maintains relevance tiers and a scoring profile for high-quality direct search results when querying outside of Foundry.

Foundry uses: content, url, title
Direct search uses: contentR1 (4×), contentR2 (3×), contentR3 (2×), content (1×)

Quick Start

1. Install

dotnet add package Umbraco.Cms.Search.Core
dotnet add package GXE.Umbraco.AzureAISearch

2. Configure

Add to appsettings.json:

{
  "AzureAISearch": {
    "Endpoint": "https://your-service.search.windows.net",
    "Key": "your-admin-api-key",
    "BaseUrl": "https://www.your-umbraco-site.com",
    "ExcludedContentTypes": [],
    "Environment": null
  }
}

3. Register

Create a composer:

using Umbraco.AzureAISearch.Extensions;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Cms.Search.Core.DependencyInjection;

public sealed class SearchComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.AddSearchCore();
        builder.AddUmbracoAzureAISearch(builder.Config)
               .RebuildAzureAISearchOnStartup(); // optional: full re-index on every startup
    }
}

That's it. On startup, the index is created automatically. Content is indexed incrementally on save & publish.

Initial Index Population

By default, only new content published after the package is installed gets indexed. To populate the index with all existing content, chain .RebuildAzureAISearchOnStartup():

builder.AddUmbracoAzureAISearch(builder.Config)
       .RebuildAzureAISearchOnStartup();

This triggers a full rebuild via IContentIndexingService on every application start. Once your index is populated, you can remove this call to avoid unnecessary rebuilds — incremental indexing on save/publish will keep the index up to date.

Index Schema

The generated Azure AI Search index contains:

Searching

Inject IAzureAISearchSearcher for direct search with full scoring:

using Umbraco.AzureAISearch.Services.Searcher;

public class SiteSearchService(IAzureAISearchSearcher searcher)
{
    public async Task<SearchResult> SearchAsync(string query, string? culture = null)
        => await searcher.SearchAsync(
            indexAlias: Umbraco.Cms.Search.Core.Constants.IndexAliases.PublishedContent,
            query: query,
            culture: culture,
            skip: 0,
            take: 20);
}

The scoring profile automatically boosts contentR1 (4×) over contentR2 (3×) over contentR3 (2×) over content (1×).

Microsoft Foundry Integration

Once content is indexed, connect the Azure AI Search index in Foundry:

1. Go to your Foundry project → Data sources
2. Add an Azure AI Search connection pointing to your search service
3. Select the index (e.g. publishedcontent or dev-publishedcontent)
4. Foundry will use the content field for search and url/title for grounding responses

No additional mapping or field configuration is needed in Foundry.

Server Role Awareness

On multi-server deployments, only the primary node manages the index. Subscriber nodes skip all write operations automatically.

Releasing a New Version

1. Ensure all changes are committed and pushed to main
2. Tag the release with the version number:

   git tag v1.2.0
   git push --tags
   

3. The GitHub Actions workflow automatically builds, tests, and publishes to NuGet.org via Trusted Publishing (no API key required)

The version in the tag (e.g. v1.2.0) is used as the package version — no need to update .csproj manually.

License

MIT