Configuration

Configuration sections

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-COGNITIVE-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 Cognitive 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)

Available from ExamineX 6.1.9, 7.0.6, 8.0.5 and 9.0.3, and in every 10.x release.

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.Identity

Then configure ExamineX to use your chosen TokenCredential in Program.cs (or Startup.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 identity
options.TokenCredential = new ManagedIdentityCredential("<client-id>");

// Client secret credential
options.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

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

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

"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

"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

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

It is possible to disable specific indexes from being initialized with ExamineX. In cases where you are close to your Azure Search service’s index limit, you may wish to disable one of the ExamineX indexes and let it remain as a default Lucene index instead. This is generally only useful if the index you are disabling isn’t used. As an example, you may not use the Members index in your site but you want to use the Umbraco Forms index. By disabling the Members index this now provides you with a free index to use for Umbraco Forms.

"ExamineX": {
    "DisabledIndexes": [
        "MembersIndex"
    ]
}

You can add any number of disabled index names to the DisabledIndexes array.

Disabling ExamineX

You can disable ExamineX entirely with this setting

"ExamineX": {
    "Disabled": true
}

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"
        }
    }
}