Skip to content
ExamineX
These docs are for ExamineX 11 · Umbraco 19 (pre-release). For the current release see ExamineX 6–10 · Umbraco 13–18.

Configuration

This is the typical JSON configuration that you should add to your appsettings.json

"ExamineX": {
"SiteFriendlyName": "Your Site Friendly Name",
"ElasticSearch": {
"ApiKey": "YourApiKey",
"CloudId": "YourElasticSearchCloudId"
}
}

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 Elastic Search service.

The ApiKey is required for the ExamineX:ElasticSearch:ApiKey setting in order for ExamineX to create and modify indexes. You can generate an API Key for ExamineX in Kibana or via the Elastic API.

There are some additional configuration options within the "ElasticSearch" section of your appsettings.json file:

  • CloudId - The CloudId of your Elastic Search Deployment.
  • Endpoint - If you are self hosting Elastic Search (i.e. Docker), then you can use Endpoint as a URL instead of the CloudId.
  • ApiKey - The ApiKey to use for authentication.
  • Thumbprint - If you are self hosting Elastic Search (i.e. Docker), then you can use the copied Thumbprint instead for authentication.
  • BasicAuthUsername - If you cannot use ApiKey for some reason and need to use basic authentication, then you can supply the username with this config option.
  • BasicAuthPassword - If you cannot use ApiKey for some reason and need to use basic authentication, then you can supply the password with this config option.
  • EnableDebugMode - Turns on settings that aid in debugging like DisableDirectStreaming() and PrettyJson() so that the original request and response JSON can be inspected. It also always asks the server for the full stack trace on errors. Defaults to false.
  • IncludeServerStackTraceOnError - Forces all requests to have ?error_trace=true querystring parameter appended, causing Elasticsearch to return stack traces as part of serialized exceptions. Defaults to false.

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 existing side by side within the same search service.

"ExamineX": {
"EnvironmentType": "ByIndex"
}

If this config option is applied, then the index names within the same search service will be suffixed (for example) 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.

NOTE: Any other value specified for this optional app setting will just be treated as if there is no environment configured.

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.

It is possible to disable specific indexes from being initialized with ExamineX. 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. By disabling the Members index, it would now just operate as the default Lucene implementation and an Elasticsearch index would not be created.

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

You can add any number of disabled index names to the DisabledIndexes array. ExamineX:DisabledIndexes applies to both Elasticsearch and Azure AI Search, and ExamineX:ElasticSearch:DisabledIndexes applies to Elasticsearch only.

Using Elasticsearch and Azure AI Search together

Section titled “Using Elasticsearch and Azure AI Search 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.

You can disable ExamineX entirely with this setting

"ExamineX": {
"Disabled": true
}

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.ElasticSearch.ElasticSearchIndex": "Debug"
}
}
}