Read about the updates and bug fixes that have been included in this release.

blog-thumb-rocket-launch.png

Elastic Stack 8.0.1 released with Log4j update

The NEST and Elasticsearch.Net 7.0 clients are now GA. Learn more about performance improvements, a simplified codebase, and parity with Elasticsearch 7.0+.

blog-banner-release-elasticsearch.png

blog-thumb-release-elasticsearch.png

NEST and Elasticsearch.Net 7.0 now GA

<html><head></head><body><p>Today we are pleased to announce the General Availability (GA) release of our .NET clients for Elasticsearch 6.x.
</p><p><em>&quot;But wait, wasn&apos;t Elasticsearch <strong>6.1</strong> just released?&quot;</em>
</p><p>Yes, this is true; whilst the .NET clients have had several pre-releases compatible with Elasticsearch 6.0 and 6.1, we intentionally pushed back on our GA release until we were overwhelmingly happy it was ready. We hope that the reasoning for this delay will become clear as you read through this post.
</p><h2 id="6-0-compatibility">6.0 Compatibility</h2><p>This client has full feature parity with Elasticsearch 6.0 and has been tested against all currently released Elasticsearch 6.x versions. You will be able use this release with versions 6.1 and the forthcoming 6.2 release without issue.
</p><p>For some of the newer features in Elasticsearch 6.1, such as the <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-composite-aggregation.html">composite aggregation</a> and <a href="https://www.elastic.co/blog/elasticsearch-machine-learning-on-demand-forecasting">machine learning forecasting</a>, we&apos;ll push out a newer release of 6.x in the future, to incorporate these.
</p><h2 id="ch-ch-changes">Ch... Ch... Changes</h2><p>The 6.0 GA release comprises well over <strong>650</strong> commits and, in the process, has shrank our Github issues down from four pages to just half of one. We&apos;ll spare you from all the gory details and effort that went into this, and call out only the most impactful changes that you&apos;re likely to come across.
</p><p>As with any major client release, <a href="https://www.elastic.co/guide/en/elasticsearch/client/net-api/6.x/_breaking_changes.html" target="_blank">we publish an exhaustive list of all the binary breaking changes</a>. Please don&apos;t let this long list intimidate you! Most of these you are unlikely to encounter, and we provide them all simply for completeness. So, onto the big changes!
</p><h2 id="serialization-changes">Serialization changes</h2><p>There are two big changes related to how we now perform serialization within the NEST client.
</p><h3 id="user-defined-types">User defined types</h3><p>We now have an explicit path for user defined types in the client serialization pipeline.
</p><p>In NEST 5.x, if you were to use a custom serializer with the client by implementing <code>IElasticsearchSerializer</code> and passing it to the client configuration, the custom serializer would take charge of serializing the <em>entire</em> request and response, including the underlying client types within NEST used to model requests and responses. Now in NEST 6.x, a custom serializer is used <em>only</em> in places where a user defined type is expected, for example,
</p><ul>
	<li>The <code>_source</code> and <code>fields</code> on <code>hits</code> in the response</li>
	<li>The term query <code>value</code></li>
	<li>A document sent as part of the Multi Term Vector API</li>
	<li>A document returned by the Get API</li>
	<li>A document sent through the Bulk API</li>
	<li>An upsert or document part of the Upsert API</li>
</ul><p>This change allows you to use your own serialization for your own user defined types without fear of affecting the rest of the client behaviour.
</p><h3 id="newtonsoft-json">Newtonsoft.Json</h3><p>NEST 6.x no longer depends on the popular <a href="https://www.nuget.org/packages/newtonsoft.json/" target="_blank">Newtonsoft.Json a.k.a. Json.NET library</a> directly as a nuget package reference. We&apos;ve taken the leap and internalized Newtonsoft.Json within the NEST assembly, and <em>shaded</em> the dependency by re-namespacing it to Nest.Json. This required some IL and assembly rewriting using <a href="https://github.com/gluck/il-repack" target="_blank">ILRepack</a> and <a href="http://www.mono-project.com/docs/tools+libraries/libraries/Mono.Cecil/" target="_blank">Mono.Cecil</a> to get it to work for both .NET Framework and .NET Core target platforms.
</p><p>What this means in practice as a consumer, is that your application is now free to use whatever version of Newtonsoft.Json that you desire without conflicting with the version that NEST uses. What this means for us as client authors, is that we are now free to work on improving the client serialization pipeline over the course of NEST 6.x without having to wait until NEST 7.x. There are many exciting developments happening in the .NET ecosystem around performance with the likes of <a href="https://msdn.microsoft.com/en-us/magazine/mt814808.aspx" target="_blank"><code>Span&lt;T&gt;</code></a>, <a href="http://adamsitnik.com/Array-Pool/" target="_blank"><code>ArrayPool&lt;T&gt;</code></a> and active discussion around a more <a href="https://github.com/dotnet/coreclr/issues/7083" target="_blank">compact UTF-8 string representation</a>, and we would like to be able to explore these unhindered.
</p><p><strong>Note</strong> we have been indexing our client benchmarking CI test runs into an Elasticsearch cluster running in <a href="https://www.elastic.co/cloud" data-vivaldi-spatnav-clickable="1">Elastic Cloud</a> for a while, and will be looking to expose these results publicly in the future. We&apos;ll also look at creating an Elasticsearch <a href="https://github.com/dotnet/BenchmarkDotNet" target="_blank">BenchmarkDotNet</a> reporter, to allow anyone running benchmarking tests with BenchmarkDotNet to easily index results into Elasticsearch. For the time being however, our implementation is wired together in our <a href="https://github.com/elastic/elasticsearch-net/blob/master/build/scripts/Benchmarking.fsx" data-vivaldi-spatnav-clickable="1">FAKE build</a>.
</p><h2 id="caution-breaking-changes-ahead">Caution! Breaking changes ahead</h2><h3 id="single-types">Single types</h3><p>The <a href="https://www.elastic.co/guide/en/elasticsearch/reference/master/removal-of-types.html" data-vivaldi-spatnav-clickable="1">staged removal of types</a> means that in Elasticsearch 6.0 onwards, <strong>multiple types in a single index are no longer allowed</strong>. This will impact your NEST code in several ways.
</p><p>As an example, if you are using NEST 5.x to index <code>Company</code> and <code>Employee</code> types in the following way:
</p><pre class="prettyprint">var settings = new ConnectionSettings()
    .DefaultIndex(&quot;my-index&quot;);
var client = new ElasticClient(settings);

client.IndexDocument(new Company { Id = 1 })
client.IndexDocument(new Employee { Id = 1 })
</pre><p>The documents would end up as different types within the same index in versions of Elasticsearch prior to 6.0
</p><pre class="prettyprint">/my-index/company/1
/my-index/employee/1
</pre><p>This will no longer work in Elasticsearch 6.0, and both <code>Company</code> and <code>Employee</code> types will now need to live in their own index. When upgrading to NEST 6.x, you can use the <a href="https://www.elastic.co/guide/en/elasticsearch/client/net-api/6.x/configuration-options.html#_options_on_connectionsettings" target="_blank"><code>DefaultMappingFor&lt;T&gt;()</code></a> method for each type so that documents are indexed into their own index. Rewriting the above example to take this approach would look as follows
</p><pre class="prettyprint">var settings = new ConnectionSettings()
  .DefaultIndex(&quot;my-index&quot;)
  .DefaultMappingFor&lt;Company&gt;(m =&gt; m.IndexName(&quot;company-index&quot;))
  .DefaultMappingFor&lt;Employee&gt;(m =&gt; m.IndexName(&quot;employee-index&quot;));
var client = new ElasticClient(settings);

client.IndexDocument(new Company { Id = 1 })
client.IndexDocument(new Employee { Id = 1 })
</pre><p>and results in documents ending up in their own index:
</p><pre class="prettyprint">/company-index/company/1
/employee-index/employee/1
</pre><p>If you <em>really need</em> multiple .NET types in a single index, you need to ensure that both .NET types are indexed using the same type name, which can be done using <code>DefaultTypeName()</code>
</p><pre class="prettyprint">var settings = new ConnectionSettings()
  .DefaultIndex(&quot;my-index&quot;)
  .DefaultTypeName(&quot;doc&quot;);
var client = new ElasticClient(settings);  

client.IndexDocument(new Company { Id = 1 });
client.IndexDocument(new Employee { Id = 1 });
</pre><p><em>However</em>, in doing this, you will now face another problem! Both documents will end up being indexed with the same id
</p><pre class="prettyprint">/my-index/doc/1
/my-index/doc/1
</pre><p>with the last document indexed overwriting the previous. The solution here is to change your .NET classes to give the documents a unique id when invoking <code>client.IndexDocument&lt;T&gt;()</code>.
</p><p>Another problem you&apos;ll encounter if you decide to index multiple .NET types into a single index is when you need to search. When searching in NEST 5.x using
</p><pre class="prettyprint">client.Search&lt;Company&gt;();
</pre><p>a search request would be made against the <code>company</code> type within the index
</p><pre class="prettyprint">/my-index/company/_search
</pre><p>and result in a collection of <code>Company</code> types being returned from the deserialized _source documents. Now that Elasticsearch 6.0 allows only a single type name within an index <em>and in future, no type name at all</em>, the previous search request will now translate to the following in NEST 6.x
</p><pre class="prettyprint">/my-index/doc/_search
</pre><p>which will now be searching across both <code>Company</code> and <code>Employee</code> types within the one index, since they are both indexed using the <code>doc</code> type name. If you are looking to constrain the search to <em>only</em> <code>Company</code> types, you can use a discriminator field within the document source, and apply a query on this field to the search criteria:
</p><pre class="prettyprint">client.Search&lt;Company&gt;(s =&gt; s
  .Query(q =&gt; +q
    .Term(&quot;my_type_field&quot;, &quot;company&quot;)
  )
);
</pre><h3 id="covariant-searches">Covariant search results</h3><p>NEST 5.x used to support returning covariant search results by inspecting the <code>_type</code> metadata for each hit, mapping each _type back to a .NET type <em>automagically</em>. For example
</p><pre class="prettyprint">client.Search&lt;IInterface&gt;(s =&gt; s.Types(typeof(A), typeof(B), typeof(C)));
</pre><p>would perform a search on <code>a</code>, <code>b</code> and <code>c</code> types within an index. NEST would then use the <code>_type</code> field in the response to deserialize each <code>_source</code> document into the the correct .NET type, and not the common interface <code>IInterface</code>. Since you can no longer have multiple types within the one index, this feature no longer makes sense in NEST 6.x.
</p><p>It is still possible to achieve covariant search results going forward, but not without telling NEST 6.x how to do so. There is now a new nuget package, <a href="https://www.nuget.org/packages/NEST.JsonNetSerializer/" target="_blank"><code>Nest.JsonNetSerializer</code></a>, with a dependency on Newtonsoft.Json, that you can reference to configure Json.NET to use <a href="https://www.newtonsoft.com/json/help/html/SerializeTypeNameHandling.htm" target="_blank"><code>TypeNameHandling.All</code></a>, such that <code>_source</code> documents are deserialized into the .NET types you expect. You can of course also implement your own <code>IElasticsearchSerializer</code> implementation to use a discriminator field with the <code>_source</code> to control deserialization to your own user defined types instead.
</p><h3 id="parent-child-joins">Parent/Child joins</h3><p>If you rely on the parent and child mapping in your usage of Elasticsearch, you still need to, conceptually at least, index multiple types into a single Elasticsearch index. Elasticsearch 6.0 introduced the <a href="https://www.elastic.co/guide/en/elasticsearch/reference/6.0/parent-join.html" target="_blank"><code>join</code> data type</a> as a mechanism to support parent/child relationships.
</p><p>The NEST documentation has a <a href="https://www.elastic.co/guide/en/elasticsearch/client/net-api/6.x/parent-child-relationships.html" data-vivaldi-spatnav-clickable="1">full example</a> of how to use the <code>join</code> data type, illustrating the removal of the <code>_parent</code> mapping and request parameter. Be sure to have a thorough read of the documentation if you&apos;re using this feature.
</p><h3 id="mapping-attributes">Mapping attributes</h3><p>Since the Newtonsoft.Json package dependency has now been removed, NEST provides additional attributes you can use to decorate your user defined types to indicate how properties should be serialized when sent to Elasticsearch. This allows you to include and rename properties without having to reference <code>Nest.JsonNetSerializer</code> and provide your own serializer instance.
</p><p>For example:
</p><pre class="prettyprint">[ElasticsearchType(Name = &quot;employee&quot;)]
public class Employee
{
    [Text(Name = &quot;first_name&quot;)]
    public string FirstName { get; set; }
    [Text(Name = &quot;last_name&quot;)]
    public string LastName { get; set; }
    [Ignore] // Property will not be included in serialization
    public bool IsSmith =&gt; !string.IsNullOrEmpty(LastName) &amp;&amp; LastName.Equals(&quot;smith&quot;, StringComparison.OrdinalIgnoreCase);
    [Number(DocValues = false, IgnoreMalformed = true, Coerce = true)]
    public int Salary { get; set; }
    [Date(Format = &quot;MMddyyyy&quot;)]
    public DateTime Birthday { get; set; }
    [Boolean(NullValue = false, Store = true)]
    public bool IsManager { get; set; }
    [Nested]
    [PropertyName(&quot;empl&quot;)] // serialize this property to a field named &quot;empl&quot; in JSON
    public List&lt;Employee&gt; Employees { get; set; }
}
</pre><h2 id="low-level-client">Low-Level Client</h2><h3 id="code-generation-fixes">Code generation improvements</h3><p>In generating parts of the low-level client, <a href="https://www.nuget.org/packages/Elasticsearch.Net/" target="_blank">Elasticsearch.Net</a>, we take the <a href="https://github.com/elastic/elasticsearch/tree/master/rest-api-spec" data-vivaldi-spatnav-clickable="1">Elasticsearch REST API specifications</a> and use it to generate C# source code. This code generation implementation has been mostly untouched since the days of NEST 1.x. With this release however, we&apos;ve taken the opportunity to fix several outstanding issues, one of which was that request parameters were fluent methods, meaning it was possible to write code such as
</p><pre class="prettyprint">client.Search&lt;dynamic&gt;(r =&gt; r.Parameter())
</pre><p>This was done in the beginning to facilitate the high-level client but now is no longer needed, thus has been removed. Instead of using fluent methods, one can use
</p><pre class="prettyprint">client.Search&lt;DynamicResponse&gt;(new OperationRequestParameters { Parameter = .. })
</pre><h3 id="response-types">Response types</h3><p>In previous versions of Elasticsearch.Net, any operation such as <code>client.Search&lt;T&gt;(..)</code> accepted any of <code>string</code>, <code>byte[]</code>, <code>dynamic</code>, <code>Stream</code>, <code>VoidResponse</code> or an <code>object</code> as the generic type parameter <code>T</code>, to deserialize the response from Elasticsearch into, and the return value of the method call was of type <code>ElasticsearchResponse&lt;T&gt;</code>.
</p><p>In NEST 6.x, the generic type parameter <code>T</code> is now constrained to be of type <code>IElasticsearchResponse</code> and returns <code>T</code> instead of <code>ElasticsearchResponse&lt;T&gt;</code>. To help aid the transition for the common use cases, Elasticsearch.Net provides <code>BytesResponse</code>, <code>StringResponse</code>, <code>DynamicResponse</code>, <code>VoidResponse</code> and <code>ElasticsearchResponse&lt;T&gt;</code> where <code>T</code> can be any object to deserialize the response into.
</p><p>As part of this change, support has been removed for returning the response from Elasticsearch as a <code>Stream</code>. This was a potentially dangerous feature because the onus for disposing this stream lay with the consumer, and the result of not disposing it could result in memory leaks and keeping connections open to Elasticsearch. If you do need to access the response stream directly for some reason, this is best handled by creating a custom <code>IElasticsearchSerializer</code> implementation.
</p><h3 id="exception-handling">Exceptions</h3><p>In previous versions, the low-level client was in charge of deserializing exceptions from the server, and would short-circuit this deserialization if a <em>bad</em> HTTP status code such as a 400 were returned from Elasticsearch. This approach was fine for Elasticsearch 2.x, but starting with Elasticsearch 5.x, several endpoints could also return additional information for <em>bad</em> HTTP status codes, and the client needed to perform a double-read of the response stream in order to surface this additional information to the consumer. How inefficient!
</p><p>Starting with NEST 6.x, the response stream is now fed directly into the configured serializer for both <em>good</em> and <em>bad</em> HTTP status codes, for deserialization. No more double reads, yay! If you want to disable this behaviour, you can set <code>DisableDirectStreaming()</code> or <code>DebugMode()</code> on the instance of <code>ConnectionSettings</code> that is passed to instantiate the client. This will result in the request and response bytes becoming available on the response through the <code>response.DebugInformation</code> property.
</p><p>The built-in <code>BytesResponse</code> and <code>StringResponse</code> types within Elasticsearch.Net both have a <code>TryGetServerError()</code> method to access an instance of <code>ServerError</code> from the exception that occurred on the server.
</p><p>For the high-level client NEST, nothing changes with usage here; the <code>.ServerError</code> property is still available on all responses, but what this does change is that serializer used by NEST is now in charge of deserializing the server error within the response, and not the low-level client.
</p><h2 id="summary">Summary</h2><p>Quite a few changes to digest, but we hope you&apos;ll agree that these continue to make working with the client as smooth as possible. We&apos;d like to give a shout out to the community who contributed to this 6.0 GA release by finding and reporting issues, opening pull requests and generally helping to further the betterment of Elasticsearch with .NET. Your contributions are highly appreciated!
</p><p>Please feel free to take NEST 6.0 and Elasticsearch.Net 6.0 for a spin, and <a href="https://github.com/elastic/elasticsearch-net/issues" target="_blank">let us know if you come across issues</a> &#x1F60A;
</p></body></html>

nest-elasticsearch-6-ga.jpg

nest-elasticsearch-6-ga-thumb.jpg

NEST and Elasticsearch.Net 6.0: Now GA!

<html><head></head><body><p>This marks the first GA release of our 2.0 client with well over a 1000 commits since 1.7.1 (the currently last released NEST version in the 1.x range).
</p><h2>Back to the drawing board</h2><p>We took some time to go back to the drawing board. NEST was originally started in 2010 and there are many choices that have accumulated in the code base that don&apos;t make sense anymore. So we stepped back to properly formalize how we see the lifetime of a call and worked off of that. Armed with the following diagram, we completely rewrote NEST&apos;s internals; The old <a href="https://msdn.microsoft.com/en-us/library/dd460717.aspx">Task Parallel Library (TPL)</a> based code is now replaced with <a href="https://msdn.microsoft.com/en-us/library/hh191443.aspx">async/await</a> with a much saner approach to exceptions and errors in addition to exposing enough information as an audit trail so you don&apos;t ever have to guess what went down during a call.
</p><p><img src="https://api.contentstack.io/v2/assets/575e4d2b3dc542cb38c09d96/download?uid=bltec66d884d4f8e393?uid=bltec66d884d4f8e393" alt="Request pipeline in NEST 2.0" style="max-width:100%;">
</p><p>Our internals now also reflect this:
</p><ul>
	<li><code>IElasticClient</code> exposes all the Elasticsearch API endpoints e.g <code>client.Search</code> this calls into <code>ITransport</code>&apos;s 2 methods <code>Request</code> and <code>RequestAsync</code> </li>
	<li>the default <code>ITransport</code> uses the passed in <code>IRequestPipelineFactory</code> to create an <code>RequestPipeline</code> which implements <code>IPipeline</code>.</li>
</ul><p>This pipeline now handles all of the failover/sniffing/pinging logic and directly reflects the flow diagram.
</p><p>We also simplified <code>IConnection</code> down just 2 methods. This means the outer edges are clean (<code>ITransport</code> and <code>IConnection</code>) and implementing your own should be really really simple. All of these (and also <code>IMemoryStreamProvider</code> and <code>IDateTimeProvider</code>) can be injected on the constructor of the client.
</p><h2>Test Framework</h2><p>Another huge endeavour is the rework of our test framework. NEST 1.x was always well tested but used 5 different test projects and 5 years worth of changing our minds as how best to write tests and assertions, thus becoming a big hodgepodge of <a href="http://www.nunit.org/">NUnit assertions</a>, <a href="http://www.fluentassertions.com/">Fluent assertions</a>, <a href="https://fakeiteasy.github.io/">FakeItEasy</a>, <a href="http://www.moqthis.com/">Moq</a> combined with several different ways to compare json with object graphs and vice-versa. Trying to write a new test quickly became <a href="http://www.hanselman.com/blog/YakShavingDefinedIllGetThatDoneAsSoonAsIShaveThisYak.aspx">an exercise in yak shaving</a> because there was no clear cut way for how best to write said test.
</p><p>So the first thing we did as part of our 2.0 branch was to completely delete all of our tests. This <em>act of insanity</em> gave us carte blanche during our rewrite.
</p><p>As of 2.0, we have one test project, <strong>Tests</strong>, with all tests written in such a way that they can be run in unit test mode and integration test mode. <em>Write once, run differently</em>.
All of the API endpoint tests test all four request variations - two DSL&apos;s (using fluent and object initializer syntax) with both synchronous and asynchronous variations of each. We also test all of the moving parts of the Elasticsearch DSL (Aggregations, Sorting, IndexSettings, etc) in the same way.
</p><p>In addition to the more formal unit and integration tests, we also implemented a thing we dubbed <em>Literate Testing</em> to allow us to write tests in a more story telling form, with multi-line comments serving as the narrative for our asciidoc documentation while using the <a href="https://github.com/dotnet/roslyn/wiki/Roslyn%20Overview">Roslyn compiler</a> to pick out the interesting bits of code. This gives us the benefit of always compiling our documentation in addition to having only one place where we document, test and assert how a piece of code is supposed to work.
</p><p>Another huge component of our testing framework is the <em>Virtual Cluster</em> that allows us to write tests for any situation and how we expect the client to behave.
</p><p>For example:
</p><pre class="prettyprint">/** we set up a 10 node cluster with a global request time out of 20 seconds.
* Each call on a node takes 10 seconds. So we can only try this call on 2 nodes
* before the max request time out kills the client call.
*/
var audit = new Auditor(() =&gt; Framework.Cluster
  .Nodes(10)
  .ClientCalls(r =&gt; r.FailAlways().Takes(TimeSpan.FromSeconds(10)))
  .ClientCalls(r =&gt; r.OnPort(9209).SucceedAlways())
  .StaticConnectionPool()
  .Settings(s =&gt; s.DisablePing().RequestTimeout(TimeSpan.FromSeconds(20)))
);
audit = await audit.TraceCalls(
  new ClientCall {
    { BadResponse, 9200 }, //10 seconds
    { BadResponse, 9201 }, //20 seconds
    { MaxTimeoutReached }
  },
  /**
  * On the second client call we specify a request timeout override to 80 seconds
  * We should now see more nodes being tried.
  */
  new ClientCall(r =&gt; r.RequestTimeout(TimeSpan.FromSeconds(80)))
  {
    { BadResponse, 9203 }, //10 seconds
    { BadResponse, 9204 }, //20 seconds
    { BadResponse, 9205 }, //30 seconds
    { BadResponse, 9206 }, //40 seconds
    { BadResponse, 9207 }, //50 seconds
    { BadResponse, 9208 }, //60 seconds
    { HealthyResponse, 9209 },
  }
);
</pre><p>This showcases the <em>Virtual Cluster</em> tests combined with <em>Literate Tests</em> and the extensive audit trail information available on each response (or exception).
</p><p>I&apos;m pleased to say we are back at a decent coverage rate (60%) and will continue to iterate and improve this.
</p><h2>Exception handling</h2><p>Another big change in NEST 2.0 is how we deal with exceptions.
</p><p>In NEST 1.x, the client threw a multitude of exceptions: <code>MaxRetryException</code>, <code>ElasticsearchAuthException</code>, <code>ElasticsearchServerException</code>, <code>DslException</code>, etc.. This made it challenging for users to handle exceptions and invalid responses, and understand the root cause of errors. On top of that, the types of exceptions thrown depended on what kind of <code>IConnectionPool</code> was injected, in order to maintain maximum backwards compatibility with NEST 0.x.
</p><p>In NEST 2.x, exceptions are much more deterministic.  The former <code>ThrowOnElasticsearchServerExceptions()</code> setting has been replaced with the more succinct <code>ThrowExceptions()</code>, which determines whether the client should ever throw an exception or not (client side and server exceptions). Furthermore, the types of exceptions have been reduced and simplified down to three types of exceptions:
</p><p><strong>ElasticsearchClientException:</strong> These are <strong>known</strong> exceptions, either an exception that occurred in the request pipeline(such as max retries or timeout reached, bad authentication, etc...) or Elasticsearch itself returned an error (could not parse the request, bad query, missing field, etc...). If it is an Elasticsearch error, the <code>ServerError</code> property on the response will contain the the actual error that was returned.  The inner exception will always contain the root causing exception.
</p><p><strong>UnexpectedElasticsearchClientException:</strong>  These are <strong>unknown</strong> exceptions, for instance a response from Elasticsearch not properly deserialized.  These are usually bugs in the client and <a href="https://github.com/elastic/elasticsearch-net/issues">we encourage you to report them</a>.  This exception also inherits from <code>ElasticsearchClientException</code> so an additional catch block isn&apos;t necessary to handle but can be helpful in distinguishing between the two.
</p><p><strong>Runtime exceptions:</strong> These are CLR exceptions like <code>ArgumentException</code>, <code>NullArgumentException</code> etc. that are thrown when an API in the client is misused.
</p><h1>Breaking Changes</h1><p>Even though a lot of work went into the interior, the exterior did not escape unscathed! On top of the many breaking changes that Elasticsearch 2.0 introduces, there are more then a few NEST 2.0 introduces.
We revalidated all the request and response domain objects against Elasticsearch 2.0.
</p><p>A pretty complete list of breaking changes are available:
</p><ul>
	<li><a href="https://github.com/elastic/elasticsearch-net/blob/master/docs/2.0-breaking-changes/elasticsearch-net-breaking-changes.md">Low level client changes, Elasticsearch.NET</a></li>
	<li><a href="https://github.com/elastic/elasticsearch-net/blob/master/docs/2.0-breaking-changes/nest-breaking-changes.md">High level client changes, NEST</a></li>
</ul><h2>Elasticsearch 2.x support</h2><p>NEST 2.0 supports all the new features in Elasticsearch 2.0 including pipeline aggregations. <a href="https://www.elastic.co/blog/elasticsearch-2-2-0-and-2-1-2-and-1-7-5-released">New features from Elasticsearch 2.2</a> have not yet been mapped.
</p><p>Here we&apos;ll just highlight a couple features that are reflected in the NEST changes to whet your appetite!
</p><h2>Filters are <strong>Gone Gone Gone</strong></h2><p>In Elasticsearch 2.0, <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/breaking_20_query_dsl_changes.html#_queries_and_filters_merged">query and filter constructs have merged into one concept called queries</a> and NEST 2.0 reflects this. So if you were previously using the <code>AndFilter</code>, this is now&#xA0;the <code>AndQuery</code>; beware however&#xA0;that some of these filters have been obsoleted and chances are high <a href="https://www.elastic.co/blog/all-about-elasticsearch-filter-bitsets">you were using them wrong!</a>.
</p><h2>Isolated descriptors</h2><p>In NEST 1.x we took pride in being a 1-to-1 mapping with the Elasticsearch API. In some cases however, this <em>purity</em> hid the real depth of parameters. As an example,
</p><p>in NEST 1.x you could add sorts on <code>Search()</code> using:
</p><pre class="prettyprint">client.Search&lt;Project&gt;(s=&gt;s
  .SortAscending(...)
  .SortScript(...)
)
</pre><p>in NEST 2.0 you have to stoop down a level first in order to access the same functionality
</p><pre class="prettyprint">client.Search&lt;Project&gt;(s=&gt;s
  .Sort(ss=&gt;ss
    .Field()
    .Script()
    .Ascending()
    .GeoDistance()
  )
)
</pre><p>This encapsulates all of the sort options properly and adheres stricter to the 1-to-1 mapping. NEST 1.x did also contain this full descriptor however the mix and matching
of the convenience methods of the parent meant that some fluent methods were additive whilst others overwrote what was previously set. With NEST 2.0, this discrepancy is gone!
</p><p>This happens in more places e.g index settings and mappings.
</p><h2>Filtered query deprecation</h2><p>With the removal of filters, NEST has added a special construct in its Query DSL to easily create a <a href="https://www.elastic.co/guide/en/elasticsearch/reference/2.0/query-dsl-bool-query.html">bool query</a> with a filter clause
</p><pre class="prettyprint">.Query(q=&gt; +q.Term(p=&gt;p.Name, &quot;NEST&quot;))
</pre><p>the <code>+</code> will cause&#xA0;the term query to be wrapped inside a bool query&apos;s <code>filter</code> clause
</p><p>You can even combine <code>+</code> with <code>!</code>
</p><pre class="prettyprint">.Query(q=&gt; !+q.Term(p=&gt;p.Name, &quot;NEST&quot;))
</pre><p>This will wrap the term query inside a <code>bool filter</code> and subsequently inside a <code>bool must_not</code>&#xA0;clause.&#xA0;This approach also works with the object initializer syntax (OIS)
</p><pre class="prettyprint">!+new TermQuery {}
</pre><h2>Attribute based mapping</h2><p>The single <code>ElasticPropertyAttribute</code> has been broken up into individual attributes per property type.
</p><p>For instance, the following:
</p><pre class="prettyprint">[ElasticType(Name = &quot;othername&quot;, IdProperty = &quot;MyId&quot;)]
public class Foo
{
  [ElasticProperty(Type = FieldType.String)]
  public Guid MyId { get; set; }
  [ElasticProperty(Type = FieldType.String)]
  public string Name { get; set; }
  [ElasticProperty(Type = FieldType.String, Analyzer = &quot;myanalyzer&quot;, TermVector = TermVectorOption.WithOffsets)]
  public string Description { get; set; }
  [ElasticProperty(Type = FieldType.Date, Format = &quot;mmmddyyyy&quot;)]
  public DateTime Date { get; set; }
  [ElasticProperty(Type = FieldType.Integer, Coerce = true)]
  public int Number { get; set; }
  [ElasticProperty(Type = FieldType.Nested, IncludeInParent = true)]
  public List&lt;Bar&gt; Bars { get; set; }
}
</pre><p>becomes
</p><pre class="prettyprint">[ElasticsearchType(Name = &quot;othername&quot;, IdProperty = &quot;MyId&quot;)]
public class Foo
{
  [String]
  public Guid MyId { get; set; }
  [String]
  public string Name { get; set; }
  [String(Analyzer = &quot;myanalyzer&quot;, TermVector = TermVectorOption.WithOffsets)]
  public string Description { get; set; }
  [Date(Format = &quot;mmddyyyy&quot;)]
  public DateTime Date { get; set; }
  [Number(NumberType.Integer, Coerce = true, DocValues = true)]
  public int Number { get; set; }
  [Nested(IncludeInParent = true)]
  public List&lt;Bar&gt; Bars { get; set; }
}
</pre><p>Aside from a simpler and cleaner API, this allows each attribute to only reflect the options that are available for the particular type instead of exposing options that may not be relevant (as <code>ElasticPropertyAttribute</code> did).
</p><h2>Inferred types</h2><p>Many places that only took a string or primitive type now take a more strongly typed object such as <code>Id</code>, <code>Field</code>, <code>Fields</code>, <code>Index</code>, <code>Indices</code>, <code>Type</code>, <code>Types</code>, <code>DocumentPath&lt;T&gt;</code>, etc. It&apos;s good to know that in most cases you can still pass a string or primitive type and it will be implicitly converted to the type where it makes sense.
</p><p>If you are using <code>C# 6</code> you can also statically import the <code>Infer</code> static class using <code>using static Nest.Infer</code>, allowing to write
</p><ul>
	<li><code>Field&lt;Project&gt;(p =&gt; p.Name)</code> any where that takes a <code>Field</code></li>
	<li><code>Field&lt;Project&gt;(p =&gt; p.Name).And(p=&gt;p.Description).And(&quot;field&quot;)</code> anywhere that takes <code>Fields</code></li>
	<li><code>Index&lt;Project&gt;()</code> for <code>Index</code></li>
</ul><p>so on and so forth. If you are using the fluent API using these infer methods is not required since the fluent API is strongly typed through lambda expressions, but they are another tool at your disposal nonetheless.
</p><h2>C# 6 support</h2><p>NEST&apos;s codebase has been largely rewritten to take advantage of all the cool new c# features making almost all the fluent code one liners
</p><pre class="prettyprint">using static Nest.Infer;
//later..
Field&lt;Project&gt;(p =&gt; p.Name);
Index&lt;Project&gt;();
Indices&lt;Project&gt;().And&lt;Developer&gt;();
</pre><h2>DNX Support</h2><p>The 2.0 release has been released with a <code>dotnet5.1</code> version on nuget that can be used on both the Desktop and Core CLR runtimes of DNX rc1. We are actively tracking <a href="https://github.com/aspnet/Home/wiki/Roadmap">rc2</a>, the <a href="https://github.com/dotnet/cli">.NET Commandline interface (dotnet-cli)</a> and the new <code>netstandard</code> NuGet target framework, with a plan to release compatible packages once these hit the scene.
</p><h2>Feedback</h2><p>We&apos;d like to thank everyone who took the alpha and rc releases out for a spin and provided invaluable input while we incubated the 2.0 release. A special shoutout to <a href="https://github.com/niemyjski">Blake Niemyjski</a> for sharing his screen with us so we could see firsthand where the pain points were during an upgrade from 1.x to 2.0.
</p><p>As always we very much welcome all feedback on <a href="https://github.com/elastic/elasticsearch-net/issues">our github issues page.</a>
</p></body></html>

birds-nest.jpg

GA Release of NEST 2.0, our .NET client for Elasticsearch

Start free trial

Blog Footer CTA

Sign up for Elastic Cloud free trial

Principal Software Engineer

Martijn Laarman

<p>By submitting you acknowledge that you've read and agree to our <a href="/legal/elastic-cloud-account-terms" target="_self">Terms of Service</a>, and you agree to receive the <a href="/legal/privacy-statement#how-we-use-the-information" target="_self">selected communications</a> at the contact details you provided above. See <a href="/legal/privacy-statement/" target="_self">Elastic’s Privacy Statement</a> for more details or to opt-out at any time.</p>

Communication Preferences - ONLY for /communication-preferences

<p>提交即表示您确认您已阅读并同意我们的<a href="/cn/legal/elastic-cloud-account-terms" target="_self">服务条款</a>，并且您同意通过您提供的上述联系方式接收<a href="/cn/legal/privacy-statement#how-we-use-the-information" target="_self">所选的通信</a>。如需了解更多信息，或想随时取消订阅，请参阅 <a href="/cn/legal/privacy-statement/" target="_self">Elastic 的隐私声明</a>。</p>

<p>By submitting you acknowledge that you've read and agree to our <a href="/legal/serverless-preview-terms" target="_blank">Terms of Service</a>, and that Elastic may <a href="/legal/privacy-statement#how-we-use-the-information" target="_blank">contact you</a> about our related products and services, using the details you provide above. See <a href="/legal/privacy-statement/" target="_blank">Elastic’s Privacy Statement</a> for more details or to opt-out at any time.</p>

Serverless GDPR Text

<p>提交即表示您确认您已阅读并同意我们的<a href="/cn/legal/serverless-preview-terms" target="_self">服务条款</a>，并且 Elastic 可以使用您提供的上述详细信息与您联系，以向您介绍我们相关的<a href="/cn/legal/privacy-statement#how-we-use-the-information" target="_self">产品和服务</a>。如需了解更多信息，或想随时取消订阅，请参阅 <a href="/cn/legal/privacy-statement/" target="_self">Elastic 的隐私声明</a>。</p>

<p>By submitting you agree to <a href="/agreements/global/cloud-services-monthly" rel="nofollow">Elastic Cloud Terms of Service</a>. Your personal data will be processed in accordance with <a href="/legal/privacy-statement">Elastic's Privacy Statement</a>.</p>

Cloud Trial GDPR Text

<p>提交即表示您同意 <a href="/cn/agreements/global/cloud-services-monthly" rel="nofollow">Elastic Cloud 服务条款</a>。我们将会按照 <a href="/cn/legal/privacy-statement">Elastic 的隐私声明</a>处理您的个人数据。
</p>

<p>By submitting you acknowledge that you've read and agree to our <a href="/legal/terms-of-use" target="_blank">Terms of Service</a>, and that Elastic may <a href="/legal/privacy-statement#how-we-use-the-information" target="_blank">contact you</a> about our related products and services, using the details you provide above. See <a href="/legal/privacy-statement/" target="_blank">Elastic’s Privacy Statement</a> for more details or to opt-out at any time.</p>

Newsletter GDPR Text

<p>提交即表示您确认您已阅读并同意我们的<a href="/cn/legal/terms-of-use" target="_self">服务条款</a>，并且 Elastic 可以使用您提供的上述详细信息与您联系，以向您介绍我们相关的<a href="/cn/legal/privacy-statement#how-we-use-the-information" target="_self">产品和服务</a>。如需了解更多信息，或想随时取消订阅，请参阅 <a href="/cn/legal/privacy-statement/" target="_self">Elastic 的隐私声明</a>。</p>

Explore similar demos

Overview

Speakers

Close

See more insights

The content on this page is not available in the selected language. As Elastic grows globally, we continue to support content in multiple languages.

The content on this page is not available in the selected language.

本页内容尚不支持所选语言。Elastic 正在不断努力，以实现对多种语言内容的支持。感谢您在此期间给予的耐心与陪伴！

Author

Articles by

Learn more

Watch now (no PT)

Watch now

See all top stories

All (no PT translation)

Contact information

Press Release

Share on Reddit

Share this story

Share by Email

Thank you for your interest!

Contact Info

Follow us on Youtube

Load More

Share on LinkedIn

Follow us on LinkedIn

Search Integrations

All Solutions

Video for

Follow us on Twitter

See when this webinar starts in my time zone

查看本次网络研讨会在我的时区的开始时间

Register to Watch

Register now

See All Posts

Can't make it? Register and we'll send you the recording. You'll also receive an email with related content

无法实时参加？注册后我们会给您发送录像。您还将收到相关内容的电子邮件。

Author

Articles by Martijn Laarman

Principal Software Engineer, Elastic

Elastic Stack 8.0.1 released with Log4j update

NEST and Elasticsearch.Net 7.0 now GA

NEST and Elasticsearch.Net 6.0: Now GA!

GA Release of NEST 2.0, our .NET client for Elasticsearch