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.

Upgrading to v11

ExamineX v11 targets Umbraco 19 and the new Umbraco Search (Umbraco.Cms.Search) on .NET 11. If you’re upgrading from ExamineX v10 or earlier (Umbraco 13 - 18), read this page first. Most sites only need to update packages and rebuild their indexes.

Umbraco Search replaces Umbraco’s Examine indexes, so update any code or configuration (DisabledIndexes, ConfigureIndex, TryGetIndex and so on) that uses the old index names:

Umbraco 13 - 18 Umbraco 19 Constant
InternalIndex Umb_Content Constants.Search.IndexAliases.DraftContent
ExternalIndex Umb_PublishedContent Constants.Search.IndexAliases.PublishedContent
MembersIndex Umb_Members Constants.Search.IndexAliases.DraftMembers
DeliveryApiContentIndex No separate index, the Delivery API uses Umbraco Search
Umb_Media Constants.Search.IndexAliases.DraftMedia
Umb_Elements Constants.Search.IndexAliases.DraftElements

The indexes in your search service get new names too (for example my-site-umb-publishedcontent), see Azure AI Search index names or Elasticsearch index names. The indexes created by previous versions aren’t used, so you can delete them once you’ve upgraded.

ExamineX now depends on Examine 4 (4.0.1) instead of Examine 3. Most queries won’t need to change, but a few Examine APIs did:

  • Examineness.Explicit, Examineness.Escaped and Examineness.Boosted are obsolete. If you were using .Escape() to match an exact phrase, use .Phrase() instead, e.g. .Field("nodeName", "codegarden 09".Phrase()).
  • new ExamineValue(...) is replaced by ExamineValue.Create(...).
  • Facets are new, see Faceting for Azure or Elastic. To get facet counts a field needs to be defined with one of the FieldDefinitionTypes.Facet* types.

See the Examine documentation for the full details.

Any DateTime value with DateTimeKind.Unspecified is now treated as UTC, both when indexing and when querying (e.g. RangeQuery<DateTime>). Previously Azure Search treated these as the server’s local time and converted them to UTC, so the stored value was shifted by whatever the server’s time zone was.

  • DateTimeKind.Utc - used as-is (no change)
  • DateTimeKind.Local - converted to UTC (no change to the stored value, except for date facet fields, see below)
  • DateTimeKind.Unspecified - treated as UTC, this is the change. This includes date strings without an offset like "2024-02-01".
  • DateTimeOffset - used as-is (no change)

This makes indexed dates independent of the server’s time zone which matters when you are load balancing across regions, or around daylight saving changes. Umbraco 19 (Umbraco Search) indexes UTC dates with an Unspecified kind, so without this change all Umbraco dates would be off by the server’s UTC offset.

If your server isn’t running in UTC and you index Unspecified dates, you’ll want to rebuild your indexes after upgrading, and check any queries that pass in local wall clock times with an Unspecified kind - either convert them to UTC or use DateTimeKind.Local.

Date-resolution facet fields (FacetDateYear, FacetDateMonth, FacetDateDay, FacetDateHour, FacetDateMinute and their FacetTaxonomyDate* equivalents) are rounded down on UTC boundaries. If your server isn’t running in UTC and these fields are populated from DateTimeKind.Local values, a value near a local midnight is stored in the UTC day, month or year, which can differ from the local one. Indexes built with an earlier ExamineX version (including v11 pre-releases) have different stored boundaries, so rebuild the indexes that contain these fields after upgrading.

Elasticsearch: NEST replaced by Elastic.Clients.Elasticsearch

Section titled “Elasticsearch: NEST replaced by Elastic.Clients.Elasticsearch”

ExamineX for Elastic Search v11 now uses Elastic’s official Elastic.Clients.Elasticsearch client instead of the end of life NEST client. The new client talks to both Elasticsearch 8.x and 9.x servers.

If you only use ExamineX through the Examine APIs, nothing changes. If you use any of the customization APIs above, or the Elastic Search APIs directly, the following changes apply:

  • Namespaces. Nest is gone. FieldType is now Elastic.Clients.Elasticsearch.Mapping.FieldType, and the analyzer types (CustomAnalyzer, tokenizers, token filters) are in Elastic.Clients.Elasticsearch.Analysis.
  • ElasticSearchIndex.ServiceClient is now an ElasticsearchClient instead of an IElasticClient.
  • CreatingOrUpdatingIndexEventArgs now exposes Request as an Elastic.Clients.Elasticsearch.Requests.Request and ElasticClient as an ElasticsearchClient. To modify the mapping, check for CreateIndexRequest or PutMappingRequest and mutate Mappings.Properties / Properties.
  • Properties no longer know their own name. IProperty only exposes Type; a field’s name is the PropertyName key it is stored under in the Properties dictionary. ElasticField therefore exposes a collection of ElasticFieldProperty name/property pairs rather than named properties. For the same reason ElasticSearchFieldReferences.SearchableFields values are ElasticFieldProperty (use .Property for the mapping and .Name for the field’s real name in the index), and a custom IElasticSearchFieldValueType.AddValues receives an ElasticFieldProperty. Write values under field.Name, not your own formatted name: lookups are case insensitive so the index’s field may differ by case, and writing a differently cased name makes Elasticsearch map a duplicate field.
  • Properties must be cast to be enumerated - it implements IDictionary<PropertyName, IProperty> explicitly.
  • The NEST marker interfaces are gone (ITextProperty, IDocValuesProperty, INumberProperty, and so on). ExamineX exposes ElasticPropertyExtensions with IsAnalyzedText(), IsSearchable(), HasDocValues(), GetAnalyzer(), TrySetIndexable(), and TryGetOriginalAlias() to replace them.
  • Numeric properties are now distinct types. There is no NumberProperty/NumberType; an integer field maps to IntegerNumberProperty, a double to DoubleNumberProperty, and so on.
  • FieldType member changes. FieldType.Murmur3Hash is now FieldType.Murmur3, and FieldType.Point no longer exists. New members include MatchOnlyText, Version, DenseVector, SparseVector, SemanticText, CountedKeyword, Passthrough and IcuCollationKeyword.
  • Sort order. SortOrder.Ascending/SortOrder.Descending are now SortOrder.Asc/SortOrder.Desc.
  • Response validity. response.IsValid is now response.IsValidResponse, and response.OriginalException is now response.TryGetOriginalException(out var exception).
  • Serialization now uses System.Text.Json rather than Utf8Json.

Index rebuilds now swap an index alias, so your site keeps searching while an index rebuilds. Existing indexes are migrated the first time they are rebuilt. Each rebuild needs one spare index in your search service, see Azure Search Limits.

See also Known limitations.