Configuration sections

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.

More Configuration

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.

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

By Index

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

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. 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 Elastic index would not be created.

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