rhighs / mongodb.embedded

A .NETCore cross-platform library that embeds a mongod executable into its dll, useful for integration testing

MongoDB.Embedded

A .NET package that provides an easy way to integrate and manage a MongoDB server within your .NET applications. It abstracts the complexities of setting up and running a MongoDB instance, allowing the embedded MongoDB executable to be packaged directly within your application's DLLs. This package supports Windows, Linux, and OSX platforms, ensuring a seamless MongoDB experience across different environments. Such a package is particularly useful for testing purposes, in particular, intergration testing.

Getting Started

1. Installation

Installing this as a dotnet package is discouraged as the binary is already built containing an unlikely working mongod version for your system. Instead it is encouraged to add this package as a git submodule into your project:

$ git submodule add https://github.com/rhighs/MongoDB.Embedded.git

NOTE: this ensures the installer task runs as part of your build steps

How mongod binaries are handled

A custom MSBuild task, executed prior to compilation, is designated to download a version of mongod that is compatible with the operating system and CPU architecture of the user. This task triggers every time a project that incorporates this package is built. It specifically downloads and sets up a mongod installation package, currently targeting version 6.0.13. Notably, this process is conducted once for each project, thereby avoiding repetition across subsequent builds.

Below is the comprehensive list of mongod community versions as indicated by the installer.

MongoDB Community Releases

Example case scenarios

Basic Operations

using MongoDB.Embedded.Crossplatform;
using MongoDB.Driver;

// Start the embedded MongoDB server
using (var embeddedServer = new Server())
{
    var client = embeddedServer.Client;
    var database = client.GetDatabase("test");
    var collection = database.GetCollection<YourDataType>("yourCollection");
    {
        // perform some operations...
    }
} // <-- server teardown, all data is deleted

Dual Server Operations

Simultaneously operate two MongoDB servers, showcasing the package's ability to handle multiple instances:

using MongoDB.Embedded.Crossplatform;
using MongoDB.Driver;

using (var server1 = new Server())
using (var server2 = new Server())
{
    var client1 = server1.Client;
    var db1 = client1.GetDatabase("test");
    var collection1 = db1.GetCollection<YourDataType>("yourCollection");

    var client2 = server2.Client;
    var db2 = client2.GetDatabase("test");
    var collection2 = db2.GetCollection<YourDataType>("yourCollection");

    {
        // perform operations using both servers...
    }
}

You could really do as much as you want, given you got enough memory in your system and you don't run out of ports to be used. In fact, every new Server() will allocate a new mongod binary in a temporary directory. TODO: this will be optimised away in next releases

Managed Server Instance

An additional layer of abstraction providing more control over the server's lifecycle:

using MongoDB.Embedded.Crossplatform;
using MongoDB.Driver;

using (var manager = new ManagedServerInstance())
{
    var instance = manager.Instance;
    var client = instance.Client;
    var db = client.GetDatabase("test");
    var collection = db.GetCollection<YourDataType>("yourCollection");
    {
        // perform operations on the collection...
    }
    manager.TeardownServer();
}

the ManagedServerInstance allows for access on a mutably shared server instance, this is of help when we need to preserve the database state across code paths and we don't necessarily need to create a fresh binary right over again.

The Server instance takes care of setting up and tearing down the MongoDB server automatically, along with it's data (everything will be stored under a temporary directory that lives as long as the Server instance).

Testing with Server

This package comes really handy for integration testing, allowing you to run tests against a real MongoDB instance with minimal setup. Here's an example of how you might write tests:

using MongoDB.Driver;
using MongoDB.Embedded;
using Xunit;

public class MongoDBTests
{
    [Fact]
    public void BasicStartupTest()
    {
        using (var embedded = new Server())
        {
            var client = embedded.Client;
        }
    }

    [Fact]
    public async Task ReadWriteTest()
    {
        using (var embedded = new Server())
        {
            var client = embedded.Client;
            var db = client.GetDatabase("test");
            var collection = db.GetCollection<TestClass>("col");

            await collection.InsertOneAsync(new TestClass { Id = 12345, TestValue = "Hello world." });
            var retrieved = await collection.Find(x => x.Id == 12345).SingleOrDefaultAsync();

            Assert.NotNull(retrieved);
            Assert.Equal("Hello world.", retrieved.TestValue);
        }
    }
}

Support and Contributions

For support, questions, or contributions, please consider the following:

• Issues: If you encounter any issues or bugs, please report them in the issues section of the GitHub repository.
• Contributions: Contributions are welcome! If you'd like to improve or add new features, feel free to fork the repository and submit a pull request.

MIT License.

mongodb.embedded's Issues

Nuget generated package should be source code only

This package simply doesn't work the way it was meant to be. Generating a nupkg file causes the installer to be run by the package creator, resulting pretty much in the loss of the "crossplatform" feature as the mongod executable will be installed by the package builder.

A couple solutions to address the issue:

• Create a source only package, forcing every project referencing this package to go through the build steps. This would ensure the installer is run for the correct platform.
• Include this package as a git submodule in your project, forcing anyone to build and trigger the installer