Umbraco Search

This repo contains the "New Search" (henceforth referred to as "Umbraco Search") for Umbraco CMS.

Important

This is a work in progress. While we urge interested parties to try it out, things might change at moment's notice.

Background and motivation

The project was started in an effort to improve the search experience in Umbraco - both for the backoffice and the frontend. It is founded in the Umbraco RFC "The Future of Search",

Umbraco Search will eventually replace the current search implementation in Umbraco, at the earliest starting from Umbraco v18.

Intended audience

Umbraco Search is in beta, meaning it's ready to adopt for a wider audience. While changes will continue to happen during the beta period, we do not anticipate any major, breaking changes before the final release.

As we progress with the project, it will eventually be released as an official and production ready add-on for Umbraco V17 and V18.

Installation

Important

Umbraco Search is only compatible with Umbraco v17 at this time.

To get started, install Umbraco Search and the Examine search provider from NuGet:

dotnet add package Umbraco.Cms.Search.Core
dotnet add package Umbraco.Cms.Search.Provider.Examine

With these packages installed, enable Umbraco Search using a composer:

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Search.Core.DependencyInjection;
using Umbraco.Cms.Search.Provider.Examine.DependencyInjection;

namespace Site.DependencyInjection;

public sealed class SiteComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder
            // add core services for search abstractions
            .AddSearchCore()
            // add the Examine search provider
            .AddExamineSearchProvider();
    }
}

Umbraco Search covers three different aspects of search in Umbraco:

• The frontend search.
• The backoffice search.
• The Delivery API querying endpoint.

At this time, the backoffice and the Delivery API parts are built as individual NuGet packages, so they can be added/removed independently in case they misbehave.

The backoffice search

To include the backoffice search, run:

dotnet add package Umbraco.Cms.Search.BackOffice

And add this to the composer:

// use Umbraco Search for backoffice search
builder.AddBackOfficeSearch();

The Delivery API querying

To include the Delivery API querying, run:

dotnet add package Umbraco.Cms.Search.DeliveryApi

And add this to the composer:

// use Umbraco Search for the Delivery API querying
builder.AddDeliveryApiSearch();

Documentation

• Searching with Umbraco Search - The ISearcher API: filtering, faceting, sorting, pagination, content variations, and protected content.
• The Examine search provider - Configuring the Examine/Lucene provider: directory factory, field options, searcher options.
• Indexing and searching custom data formats - Custom IndexValue, Indexer, Filter, Searcher, and IContentIndexer implementations.
• The backoffice - User guide for interacting with search indexes in the Umbraco backoffice.
• Extending the search backoffice - Developer guide for adding detail boxes, entity actions, workspace views, and routable modals.
• Handling data from others sources - Indexing and searching data that does not originate from Umbraco.
• Reindexing content programmatically - How to trigger reindexing of content programmatically.