Configuration
Configuration sections
Section titled “Configuration sections”Key-based authentication (default)
Section titled “Key-based authentication (default)”There are 3 required configuration options when using key-based authentication:
This is the typical JSON configuration that you should add to your appsettings.json
"ExamineX": { "AzureSearchServiceName": "YOUR-AZURE-AI-SEARCH-ADMIN-SERVICE-NAME", "AzureSearchServiceKey": "35A7420DE8D1D1F7095AB929E0F71420", "SiteFriendlyName": "Your site's Friendly name associated with your license"}The ExamineX:SiteFriendlyName setting is associated with your license and must the same value you used when creating your license.
If you are trialing ExamineX then you can enter any site friendly name and then if purchasing you should use the same name.
This setting is also used to name the indexes in your Azure Search service.
The Azure AI Search admin key is required for the ExamineX:AzureSearchKey setting because ExamineX needs to create and modify index, indexers and data source definitions.
Authentication with Managed Identity (Token-based)
Section titled “Authentication with Managed Identity (Token-based)”If your environment prohibits the use of API keys, you can authenticate using Azure Managed Identity or any other TokenCredential implementation from the Azure.Identity package. When using token-based authentication, the ExamineX:AzureSearchServiceKey configuration setting is not required.
First, install the Azure.Identity NuGet package:
dotnet add package Azure.IdentityThen configure ExamineX to use your chosen TokenCredential in Program.cs:
using Azure.Identity;
// Using Managed Identity (e.g. for Azure App Service / Azure VMs)builder.CreateUmbracoBuilder() .AddBackOffice() .AddWebsite() .AddComposers() .AddExamineXAzureSearch(options => { options.TokenCredential = new ManagedIdentityCredential(); }) .Build();You can supply any TokenCredential implementation. ExamineX does not hardcode DefaultAzureCredential — you choose the credential that suits your environment:
// User-assigned managed identityoptions.TokenCredential = new ManagedIdentityCredential("<client-id>");
// Client secret credentialoptions.TokenCredential = new ClientSecretCredential("<tenant-id>", "<client-id>", "<client-secret>");When using token-based authentication, only 2 configuration options are required in appsettings.json:
"ExamineX": { "AzureSearchServiceName": "YOUR-AZURE-AI-SEARCH-SERVICE-NAME", "SiteFriendlyName": "Your site's Friendly name associated with your license"}Required Azure RBAC roles
Section titled “Required Azure RBAC roles”When using Managed Identity instead of an admin key, the identity must be assigned the following roles on the Azure AI Search resource:
- Search Index Data Contributor — allows reading, writing, and deleting indexes and documents
- Search Service Contributor — allows managing the search service, indexes, indexers, and data sources
You can assign these roles in the Azure portal under your Azure AI Search resource → Access control (IAM).
If you store your license file in Blob Storage, you can also use Managed Identity to access it, see Blob Storage with Managed Identity.
Pre-production sites
Section titled “Pre-production sites”The Standard licenses type supports pre-production indexes. An optional configuration setting can be used to configure a pre-production site while running under the same single license. These 2 configuration options provide the flexibility you may require to have pre-production site indexes in either a separate search service or separate indexes within the same search service depending on your requirements.
By Index
Section titled “By Index”"ExamineX": { "EnvironmentType": "ByIndex"}If this config option is applied, then the index names within the same search service will be suffixed with -staging. For example, for the Internal index with a friendly site name of “My Website”, the index name would now be my-website-internal-staging
By Service
Section titled “By Service”"ExamineX": { "EnvironmentType": "ByService"}If this config value is applied, then the search service that will be used will be the search service name suffixed with -staging. For example, if you’re search service name is “website-search” then this will configure indexes and the client to use a search service called website-search-staging
NOTE: Any other value specified for this optional app setting will just be treated as if there is no environment configured.
Multiple pre-production sites
Section titled “Multiple pre-production sites”You may have multipe pre-production websites and in this case there is another config option you can use to name that pre-production site:
"ExamineX": { "EnvironmentName": "-staging"}Changing this value will result in a different -staging term being suffixed. For example, if this was “dev” then the suffix would become -dev.
Disabling Specific Indexes
Section titled “Disabling Specific Indexes”It is possible to disable specific indexes from being initialized with ExamineX, so they remain default Lucene indexes. This is generally only useful if the index you are disabling isn’t used, or to reduce the number of indexes in your Azure AI Search service. As an example, you may not use the Members index in your site:
"ExamineX": { "DisabledIndexes": [ "Umb_Members" ]}You can add any number of disabled index names to the DisabledIndexes array. ExamineX:DisabledIndexes applies to both Azure AI Search and Elasticsearch, and ExamineX:AzureSearch:DisabledIndexes applies to Azure AI Search only.
Using Azure AI Search and Elasticsearch together
Section titled “Using Azure AI Search and Elasticsearch together”ExamineX for Azure AI Search and ExamineX for Elasticsearch can be added to the same site, each with its own license. Each index uses the product it isn’t disabled for, which is set with each product’s own DisabledIndexes (ExamineX:AzureSearch:DisabledIndexes and ExamineX:ElasticSearch:DisabledIndexes). An index disabled for both uses the default Lucene implementation.
builder.CreateUmbracoBuilder() .AddBackOffice() .AddWebsite() .AddDeliveryApi() .AddComposers() .AddExamineXAzureSearch() .AddExamineXElasticSearch() .Build();For example, the Azure AI Search Free tier is limited to 3 indexes, so you can keep Azure AI Search for the indexes that benefit most from its AI features and use Elasticsearch, which has no index limit, for the rest. Here Azure AI Search keeps Umb_PublishedContent for front-end search with semantic ranking and Umb_Media for media file content indexing, and Elasticsearch takes the backoffice content, members and elements indexes:
"ExamineX": { "AzureSearch": { "DisabledIndexes": [ "Umb_Content", "Umb_Members", "Umb_Elements" ] }, "ElasticSearch": { "DisabledIndexes": [ "Umb_PublishedContent", "Umb_Media" ] }}This uses 2 of the Free tier’s 3 indexes, which leaves room for the additional index that zero downtime rebuilds need while they run. With 3 Azure AI Search indexes on the Free tier, rebuilds delete and recreate the index instead.
If an index is enabled for both, the product added last is used and a warning is logged.
Zero downtime rebuilds
Section titled “Zero downtime rebuilds”ExamineX rebuilds your indexes with zero downtime. Each index name in your Azure AI Search service (i.e. my-site-umb-content) is an index alias that points to a physical index named with a timestamp suffix (i.e. my-site-umb-content-20261015093000).
When Umbraco rebuilds an index, ExamineX creates a new physical index alongside the current one and writes everything to it while your site keeps searching the current index. Once the rebuild is complete and the new index contains documents, the alias is swapped to it and the previous index is deleted. Because the alias lives in your search service, every server in a load balanced environment switches to the rebuilt index at the same time.
Some things to be aware of:
-
Umbraco’s own zero downtime indexing isn’t needed. Umbraco’s Examine search provider has a
Umbraco:CMS:Search:Examine:ZeroDowntimeIndexingsetting (disabled by default) which keeps two copies of every index. Zero downtime rebuilds are built into ExamineX, so if that setting is enabled ExamineX turns it off, logs a warning on startup and uses its own. -
A rebuild needs one additional index while it runs. ExamineX rebuilds the indexes in a search service one at a time so that only one additional index exists at any time. If your service has no spare index quota (i.e. the free tier’s 3 indexes are in use), the index is deleted and recreated instead, which means searches fail or return partial results until the rebuild is complete.
-
Existing indexes are migrated the first time they are rebuilt. Indexes created by previous ExamineX versions don’t have an alias. The first rebuild creates the new physical index, deletes the existing index and creates the alias in its place, so searches fail for a few seconds while this happens.
-
Changes made during a rebuild only go to the new index. Content published while a rebuild is running is written to the new index (the same as Umbraco’s own zero downtime indexing), so it shows up in searches once the rebuild completes. If the rebuild fails, the new index is discarded and the current index is kept.
-
The previous index is kept for a short time after a rebuild. Azure AI Search can take a little while to propagate an alias update to all of its nodes, and until it has, requests through the alias can still use the previous index. So once the alias has been swapped, ExamineX keeps the previous index for the alias propagation delay (10 seconds) plus
PreviousIndexDeletionDelay(30 seconds by default), then deletes it in the background. Rebuilds don’t wait for this, but the previous index still counts towards your index quota until it’s deleted, so the next rebuild in the same search service waits for it. If it can’t be deleted (i.e. the site stops first), the next rebuild deletes it.This matters for requests you make yourself with
AzureSearchIndex.IndexClient(i.e. suggestions or autocomplete), which would fail with 404 (Not Found) if the previous index was deleted too soon. ExamineX’s searchers fall back to the new index automatically. Change the delay in your configuration, or set it to00:00:00to delete the previous index as soon as the alias update has propagated:"ExamineX": {"AzureSearch": {"PreviousIndexDeletionDelay": "00:00:30"}} -
Rebuilds outside of Umbraco Search (i.e. calling
IIndex.CreateIndex()yourself) swap the alias to the new index straight away, so searches don’t fail but return partial results until the index is repopulated. For zero downtime, callIExamineXIndex.BeginRebuild()before andIExamineXIndex.CompleteRebuild()after repopulating the index.
If your search service doesn’t support index aliases you can disable them, in which case rebuilds delete and recreate the index:
services.ConfigureAll<AzureSearchIndexOptions>(options => options.UseIndexAlias = false);Field query expansions
Section titled “Field query expansions”Field query expansions make queries on one field also search other fields. This is useful for queries you don’t control, such as the Umbraco backoffice search, which only searches its own aggregated text field. When a query searches a field that has an expansion, the same value (including wildcards and boosts) is also searched on each of the expanded fields. A document matches if any of these fields match.
- The keys (the fields being queried) match case-insensitively, so
Sys_aggregated_textsalso expands a query onsys_aggregated_texts. - Each expanded field is searched using the name of the matching field in the index schema.
- Expanded fields that don’t exist in the index, or aren’t searchable, are skipped.
For example, to make the Umbraco backoffice content search also search a field that you populate yourself:
services.PostConfigure<AzureSearchIndexOptions>( Umbraco.Cms.Core.Constants.Search.IndexAliases.DraftContent, options => options.FieldQueryExpansions["Sys_aggregated_texts"] = ["myCustomField"]);The ExamineX Media package uses this to make the backoffice media search include the AI generated media fields, see BackOfficeSearchFields.
Disabling ExamineX
Section titled “Disabling ExamineX”You can disable ExamineX entirely with this setting
"ExamineX": { "Disabled": true}Verbose Logging
Section titled “Verbose Logging”You can adjust the logging output for debugging purposes for ExamineX by modifying Serilog config
and adding an Override entry. For example:
"Serilog": { "MinimumLevel": { "Default": "Information", "Override": { "ExamineX.AzureSearch.AzureSearchIndex": "Debug" } }}