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)

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

There are 3x required appSettings:

<add key="ExamineX.AzureSearchServiceName" 
     value="your-azure-cognitive-search-service-name" />

<add key="ExamineX.SiteFriendlyName"
     value="Your site's Friendly name associated with your license" />

<add key="ExamineX.AzureSearchKey" 
     value="YOUR-AZURE-COGNITIVE-SEARCH-ADMIN-SERVICE-KEY" />

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.

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

<add key="ExamineX.EnvironmentType" value="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"
}

<add key="ExamineX.EnvironmentType" value="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"
}

<add key="ExamineX.EnvironmentName" value="-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 want to use the free tier of Azure search which limits you to 3 indexes total, you may wish to disable one of 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.

Replace the {IndexName} token with the Examine index name you wish to disable in ExamineX.

<add key="ExamineX.Umbraco.Disable.{IndexName}" value="true" />

For example:

<add key="ExamineX.Umbraco.Disable.MembersIndex" value="true" />

Disabling ExamineX

You can disable ExamineX entirely with this setting

"ExamineX": {
    "Disabled": true
}

<add key="ExamineX.Disabled" value="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"
        }
    }
}

You can adjust the logging output for debugging purposes for ExamineX by modifying the Umbraco file:

~/config/serilog.config

And adding this line under appSettings

<add key="serilog:minimum-level:override:ExamineX.AzureSearch.AzureSearchIndex" value="Verbose" />