A Tutorial: Getting Started With Elastic Using .Net NEST Library, Part One

In this four-part series, I will show you how to use Elastic from .NET. I will use the officially-supported Elastic client library for .NET: NEST. The first part will cover the reasons for choosing NoSQL, an explanation of Elastic, and installing and communicating with Elastic.

A Tutorial: Getting Started With Elastic Using .Net NEST Library, Part One

Why NoSQL?

In my opinion, the two man reasons for using NoSQL database are as follows:

  • Horizontally scaling relational databases is hard

  • Impedance mismatch between object-oriented modeling and relational modeling

Elastic combines the ability to easily scale, rich search capabilities and JSON as a data model into a very attractive mix.

What is Elastic?

Formerly known as Elasticsearch, and according to Wikipedia, "Elastic is a search server based on Lucene. It provides a distributed, multitenant-capable full-text search engine with a RESTful web interface and schema-free JSON documents. Elastic is developed in Java and is released as open source under the terms of the Apache License."

"Elastic is distributed, which means that indices can be divided into shards and each shard can have zero or more replicas. Each node hosts one or more shards, and acts as a coordinator to delegate operations to the correct shard(s). Rebalancing and routing are done automatically."

"Elastic supports real-time GET requests, which makes it suitable as a NoSQL solution, but it lacks distributed transactions."

We will start our journey in part one by installing Elastic node on a windows machine. In parts two and beyond, we will dive in to creating an index and mapping. After that, we will cover CRUD operations, and then NEST Bulk API and document migration.

Quick Elastic Installation on a Windows Machine

If you do not have Java (JVM) installed on your computer, you should download and install it now.

From the official Elastic setup documentation:

"Elastic is built using Java, and requires at least Java 7 in order to run. Only Oracle's Java and the OpenJDK are supported. ... We recommend installing the Java 8 Update 20 or later, or Java 7 update 55 or later. Previous versions of Java 7 are known to have bugs that can cause index corruption and data loss. ... The version of Java to use can be configured by setting the "JAVA_HOME" environment variable.

If you have not already downloaded the latest release of Elastic, download it now here. Extract it to your preferred directory on your local disk. Go to that directory and then deeper into the "config" subdirectory. Open "elasticsearch.yml" in your favorite text editor and change the following settings:

node.name: node_name

cluster.name: cluster_name

discovery.zen.ping.multicast.enabled: false

discovery.zen.ping.unicast.hosts: ["0.0.0.0"]

By default, Elastic nodes use the TCP 9300 port for inter-node communication and the TCP 9200 port for communication with clients. You should configure your firewall to allow network traffic for those ports.

Alright, so now you are ready to start your Elastic node. Navigate to the "bin" subdirectory of your Elastic directory and execute the "elasticsearch.bat" batch file. Your node will start, allowing you to run simple queries to get a first taste of Elastic REST API. I use Fiddler web debugging proxy for this.

Start Fiddler and run the following command:

GET http://localhost:9200/ HTTP/1.1

Accepts: application/json

Content-Type: application/json

User-Agent: Fiddler

Host: localhost:9200

You should get the following response:

HTTP/1.1 200 OK

Content-Type: application/json; charset=UTF-8

Content-Length: 362

{

"status" : 200,

"name" : "darius_test_node",

"cluster_name" : "darius_test_cluster",

"version" : {

"number" : "1.4.2",

"build_hash" : "927caff6f05403e936c20bf4529f144f0c89fd8c",

"build_timestamp" : "2014-12-16T14:11:12Z",

"build_snapshot" : false,

"lucene_version" : "4.10.2"

},

"tagline" : "You Know, for Search"

}

Alternatively, you could point your browser here and you would get the same response, but Fiddler will be very useful later when we debug more advanced queries, so I advise getting used to it now.

Communicating with Elastic from .NET

You now have Elastic node up and running; let's connect to it from your .NET program.

First, create a .NET program. To do so, start VisualStudio and then create a new "Console Application" project. Then, add NEST library using NuGet package manager. In the "Program.cs" file, enter the following code (in Program class):

using Nest;

using System;

namespace ElasticBlogPost

{

public class Program

{

public static void Main()

{

var local = new Uri("http://localhost:9200");

var settings = new ConnectionSettings(local, null);

var elastic = new ElasticClient(settings);

var res = elastic.Raw.ClusterHealth();

Console.WriteLine(res.SuccessOrKnownError);

}

}

}

Please note that this is the only time that I will give the whole program source code at once. I will be adding other pieces of code to this program bit by bit. In other words, all other code fragments should be appended to this initial code.

Now, build and run your program. You should see the following output in your console: True. This means that we have successfully connected to your Elastic server from .NET.

In part two of this series, we will create your first index. Stay tuned.