Server: Running an Embedded Instance

RavenDB makes it very easy to be embedded within your application, with RavenDB Embedded package you can integrate your RavenDB server with a few easy steps.

EmbeddedServer.Instance.StartServer();
using (var store = EmbeddedServer.Instance.GetDocumentStore("Embedded"))
{
    using (var session = store.OpenSession())
    {
        // Your code here
    }
}

EmbeddedServer.Instance.StartServer();
using (var store = await EmbeddedServer.Instance.GetDocumentStoreAsync("Embedded"))
{
    using (var session = store.OpenAsyncSession())
    {
        // Your code here
    }
}

There is one prerequisite and one recommendation for the Embedded package:

Prerequsite:

• Install .NET Core runtime either manually or along with a RavenDB full version
  • Be sure that the RavenDB server FrameworkVersion definition matches the .NET Core version that you install.

Recommendation:

• Projects targeting .NET Framework 4.6.1+ that use old packages.config for maintaining NuGet packages should be migrated to PackageReference package management (please refer to section below on how to achieve this)

Could not load file or assembly 'System.Runtime.CompilerServices.Unsafe, Version=4.0.4.0, Culture=neutral, 
PublicKeyToken=b03f5f7f11d50a3a' or one of its dependencies. The located assembly's manifest definition does not 
match the assembly reference. (Exception from HRESULT: 0x80131040)

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <startup> 
        <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2" />
    </startup>
  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly>
        <assemblyIdentity name="System.Runtime.CompilerServices.Unsafe" publicKeyToken="b03f5f7f11d50a3a" culture="neutral" />
        <bindingRedirect oldVersion="0.0.0.0-4.0.4.1" newVersion="4.0.4.1" />
      </dependentAssembly>
      <dependentAssembly>
        <assemblyIdentity name="System.Buffers" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
        <bindingRedirect oldVersion="0.0.0.0-4.0.3.0" newVersion="4.0.3.0" />
      </dependentAssembly>
    </assemblyBinding>
  </runtime>
</configuration>

Installation

• Create a new project (.NET Standard 2.0+, .NET Core 2.0+, .NET Framework 4.6.1+).
• Grab the package from our NuGet

  Install-Package RavenDB.Embedded -Version 4.1.0

Starting the Server

RavenDB Embedded Server is available under EmbeddedServer.Instance.
In order to start it, call StartServer method.

// Start RavenDB Embedded Server with default options
EmbeddedServer.Instance.StartServer();

For more control on how to start the server, pass to StartServer method a ServerOptions object.

ServerOptions

Set ServerOptions to change server settings such as .NET FrameworkVersion, DataDirectory or other ServerOptions.

.NET FrameworkVersion

The default FrameworkVersion is defined to work with any .NET version from the time of the RavenDB server release and newer by using the + moderator. For example, ServerOptions.FrameworkVersion = 3.1.17+.

Thus, by leaving the default FrameworkVersion definition, RavenDB embedded servers will automatically look for the .NET version that is currently running on the machine, starting from the version at the time of the server release.

To stay within a major or minor .NET release, but ensure flexibility with patch releases, use a floating integer x.
It will always use the newest version found on your machine.

For example, ServerOptions.FrameworkVersion = 3.x will look for the newest 3.x release.
...= 3.2.x will look for the newest 3.2 release.
Neither will look for 4.x.

EmbeddedServer.Instance.StartServer(new ServerOptions
{
    FrameworkVersion = "3.1.15+",
});

Other ServerOptions

EmbeddedServer.Instance.StartServer(new ServerOptions
{
    DataDirectory = "C:\\RavenData",
    ServerUrl = "http://127.0.0.1:8080"
});

Without the ServerOptions, RavenDB server will start with a default value of 127.0.0.1:{Random Port}.

Setting Server Directory

In case you're not interested in installing the .Net run-time environment on your system, you can -

• Download a full RavenDB version.
  This version already includes a .Net run-time environment.
• Extract the downloaded version to a local folder.
  E.g. C:\RavenDB.
• Set the ServerDirectory server option to the RavenDB subfolder that contains -
  • Raven.Server.exe in Windows
  • Raven.Server in Posix

EmbeddedServer.Instance.StartServer(new ServerOptions
{
    ServerDirectory = @"C:\RavenDB\Server"
});

Restarting the Server

To restart the server, use the method <embedded server>.RestartServerAsync().

public async Task RestartServerAsync();

In code:

await EmbeddedServer.Instance.RestartServerAsync();

ServerProcessExited Event

Use <embedded server>.ServerProcessExited to observe when the server has crashed or exited.

event EventHandler<ServerProcessExitedEventArgs>? ServerProcessExited;

Event data is of type ServerProcessExitedEventArgs.

Security

RavenDB Embedded supports running a secured server. Just run Secured method in the ServerOptions object.

Set up security using the certificate path

var serverOptions = new ServerOptions();
serverOptions.Secured(
    certificate: "PathToServerCertificate",
    certPassword: "CertificatePassword");

The first way to enable authentication is to set the certificate with the path to your .pfx server certificate. You may supply the certificate password using certPassword.

Set up security using a custom script

To access the certificate via logic that is external to RavenDB, you can use the following approach:

var serverOptionsWithExec = new ServerOptions();
var certificate = new X509Certificate2();
serverOptionsWithExec.Secured(
    certLoadExec: "powershell",
    certExecArgs: "C:\\secrets\\give_me_cert.ps1",
    serverCertThumbprint: certificate.Thumbprint,
    clientCert: certificate);

This option is useful when you want to protect your certificate (private key) with other solutions such as "Azure Key Vault", "HashiCorp Vault" or even Hardware-Based Protection. RavenDB will invoke a process you specify, so you can write your own scripts / mini-programs and apply the logic that you need.

It creates a clean separation between RavenDB and the secret store in use.

RavenDB expects to get the raw binary representation (byte array) of the .pfx certificate through the standard output.

Document Store

After starting the server you can get the DocumentStore from the Embedded Server and start working with RavenDB. Getting the DocumentStore from The Embedded Server is pretty easy you only need to call GetDocumentStore or GetDocumentStoreAsync with the name of the database you like to work with.

EmbeddedServer.Instance.GetDocumentStore("Embedded");

await EmbeddedServer.Instance.GetDocumentStoreAsync("Embedded");

For more control on the process you can call the methods with DatabaseOptions object.

var databaseOptions = new DatabaseOptions(new DatabaseRecord
{
    DatabaseName = "Embedded"
});
EmbeddedServer.Instance.GetDocumentStore(databaseOptions);

var databaseOptions = new DatabaseOptions(new DatabaseRecord
{
    DatabaseName = "Embedded"
});
await EmbeddedServer.Instance.GetDocumentStoreAsync(databaseOptions);

Get Server URL and Process ID

Server URL

The GetServerUriAsync method can be used to retrieve the Embedded server URL. It must be called after server was started, because it waits for the server initialization to complete. The URL can be used for example for creating a custom document store, omitting the GetDocumentStore method entirely.

Uri url = await EmbeddedServer.Instance.GetServerUriAsync();

Process ID

The GetServerProcessIdAsync method can be used to retrieve the system-generated process ID for the embedded server.

public async Task<int> GetServerProcessIdAsync(CancellationToken token = default);

int processID = await EmbeddedServer.Instance.GetServerProcessIdAsync();

• You can have only one instance of EmbeddedServer
• Method EmbeddedServer.Instance.OpenStudioInBrowser() can be used to open an browser instance with Studio