Skip to content

Latest commit

 

History

History
236 lines (178 loc) · 7.75 KB

README.md

File metadata and controls

236 lines (178 loc) · 7.75 KB
Raw

Unit 1, Lesson 3 - Let's Code!

Until now, we were only using the Management Studio. Now it's time to write some code.

In this lesson you will write some very simple C# programs which load data from the database.

You can also use Java, Node, Python, Ruby, Go... There are different syntaxes but the main idea remains the same.

This lesson picks up right where Lesson 2 left off.

Exercise 1: Your First RavenDB Client Application

In this exercise we will write a very basic RavenDB client application. You can use .NET core or .NET full.

Step 1: Create a New Project and Install the Latest RavenDB.Client Package

Start Visual Studio and create a new Console Application Project named Northwind. Then, in the Package Manager Console, issue the following command:

Install-Package RavenDB.Client -Version 5.4.5

This will install RavenDB.Client binaries which you will need in order to compile your code.

You will need to add the using namespace at the top of Program.cs:

using Raven.Client.Documents;

Step 2: Initialize the DocumentStore

Start your Main method with the following code:

var documentStore = new DocumentStore
{ 
    Urls = new [] {"http://localhost:8080"},
    Database = "Northwind"
};

documentStore.Initialize();

The document store is the starting point for all your interactions with RavenDB.

A document store is the main client API object which establishes and manages the connection channel between an application and a database instance. It acts as the connection manager and also exposes methods to perform all operations that you can run against an associated server instance. The document store object has an array of URL addresses to the cluster nodes. However, it can work against multiple databases that exist there.

To learn more about the DocumentStore, access the official documentation.

Step 3: Load a Document from the Server

After creating an instance of the DocumentStore we are ready to interact with the database.

After creating a RavenDB document store, we are ready to use the database server instance it is pointing at. For any operation we want to perform on the DB, we start by obtaining a new Session object from the document store. The Session object will contain everything needed to perform any operation necessary.

using (var session = documentStore.OpenSession())
{
    var p = session.Load<dynamic>("products/1-A");
    System.Console.WriteLine(p.Name);
}

RavenDB is schemaless. You don't need to create any class to load documents from the server.

When you want to store data in a relational database, you first define a schema - a defined structure for the database which says what tables and columns exist and which data types each columns can hold. With RavenDB, storing and loading data is much more casual.

Here is the complete code of this exercise.

using Raven.Client.Documents;

namespace Northwind
{
    class Program
    {
        static void Main()
        {
            var documentStore = new DocumentStore
            {
                Urls = new[] { "http://localhost:8080" },
                Database = "Northwind"
            };

            documentStore.Initialize();
            using (var session = documentStore.OpenSession())
            {
                var p = session.Load<dynamic>("products/1-A");
                System.Console.WriteLine(p.Name);
            }
            System.Console.WriteLine("Press <ENTER> to continue...");
            System.Console.ReadLine();
        }
    }
}

Understanding the Concept of Unique Identifiers

There is no need to inform the source collection when loading a document. It is possible because, as you learned in Lesson 1, the collection in RavenDB is just "virtual."

To load a document, you simply need to specify its ID. Any string can be used as a document ID. RavenDB uses a default convention where the collection name is used as a prefix followed by a unique value.

The document ID is equivalent for the primary key in a relational system. Unlike a primary key which is unique per table, the document ID is unique per database. This also means that whenever you store a new document using a key that is already used by a document, that document will get overwritten with the new document data.

You can learn more about how to work with document IDs reading the official documentation

Exercise 2: Improving the Code with Some Types

This exercise picks up right where the previous one left off.

In the previous exercise we started loading data from the server without defining any class. The schemaless nature of RavenDB, combined with the dynamic keyword in C# allows us to work in a completely dynamic world. But for most things, we do want some structure.

Step 1: Introducing Model Classes

You could define a very basic model to handle our product information.

public class Product
{
    public string Id { get; set; }
    public string Name { get; set; }
}

That's good enough if you just want to load partial information of the documents. But you should always define or model classes as complete as possible.

In this exercise, you can ask the Studio to provide type information compatible with Northwind through Settings/Create Sample Data/View C# classes.

You can even request the model class while editing a document clicking in the caret next to Copy to clipboard, then Copy as C# class.

public class Product
{
    public string Name { get; set; }
    public string Supplier { get; set; }
    public string Category { get; set; }
    public string QuantityPerUnit { get; set; }
    public float PricePerUnit { get; set; }
    public int UnitsInStock { get; set; }
    public int UnitsOnOrder { get; set; }
    public bool Discontinued { get; set; }
    public int ReorderLevel { get; set; }
}

You can see that there really isn't anything special about these classes. There is no base class, attributes or even virtual members.

Step 2: Using Your Model Class when Interacting with RavenDB

Starting to use model classes is really easy with RavenDB.

using (var session = documentStore.OpenSession())
{
    var p = session.Load<Product>("products/1-A");
    System.Console.WriteLine(p.Name);
}

The code is the same as before but you are using the Product class instead of dynamic.

It just works!

Here is the complete code for this exercise.

using Raven.Client.Documents;

namespace Northwind
{
    class Program
    {
        static void Main()
        {
            var documentStore = new DocumentStore
            {
                Urls = new { "http://localhost:8080" },
                Database = "Northwind"
            };

            documentStore.Initialize();

            using (var session = documentStore.OpenSession())
            {
                var p = session.Load<Product>("products/1-A");
                System.Console.WriteLine(p.Name);
            }
        }
    }

    public class Product
    {
        public string Name { get; set; }
        public string Supplier { get; set; }
        public string Category { get; set; }
        public string QuantityPerUnit { get; set; }
        public float PricePerUnit { get; set; }
        public int UnitsInStock { get; set; }
        public int UnitsOnOrder { get; set; }
        public bool Discontinued { get; set; }
        public int ReorderLevel { get; set; }
    }
}

Great job!

The third lesson is done.

Let's move on to Lesson 4 and learn more about the DocumentStore.