👁 Image
NEventStore.Persistence.MongoDB 12.1.0

NEventStore.Persistence.Mongo

Mongo Persistence Engine for NEventStore

NEventStore.Persistence.MongoDB currently supports:

• .net6.0+
• .net standard 2.1
• .net framework 4.7.2

Build Status

Branches:

• master 👁 CI
  
• develop 👁 CI
  

Information

ChangeLog can be found

How to Build (locally)

• clone the repository with:

git clone --recursive https://github.com/NEventStore/NEventStore.Persistence.MongoDB.git

or

git clone https://github.com/NEventStore/NEventStore.Persistence.MongoDB.git
git submodule update

To build the project locally on a Windows Machine:

• Optional: update .\src\.nuget\NEventStore.Persistence.MongoDB.nuspec file if needed (before creating relase packages).
• Open a Powershell console in Administrative mode and run the build script build.ps1 in the root of the repository.

How to Run Unit Tests (locally)

• Install Database engines or use Docker to run them in a container (you can use the scripts in ./docker folder).

• Define the following environment variables:

  NEventStore.MongoDB="mongodb://localhost:50002/NEventStore"
  

Run Benchmarks (locally)

• Build benchmark project:

dotnet build .\src\NEventStore.Persistence.MongoDB.Benchmark\NEventStore.Persistence.MongoDB.Benchmark.csproj -c Release

• Set benchmark connection string in current shell:

$env:NEventStore.MongoDB = 'mongodb://localhost:50002/NEventStore'

• List all discovered benchmark cases:

dotnet .\src\NEventStore.Persistence.MongoDB.Benchmark\bin\Release\net8.0\NEventStore.Persistence.MongoDB.Benchmark.dll --list flat

• Run all benchmark cases:

dotnet .\src\NEventStore.Persistence.MongoDB.Benchmark\bin\Release\net8.0\NEventStore.Persistence.MongoDB.Benchmark.dll --filter *

• Run specific benchmark class or method via filter:

dotnet .\src\NEventStore.Persistence.MongoDB.Benchmark\bin\Release\net8.0\NEventStore.Persistence.MongoDB.Benchmark.dll --filter *CheckpointGeneratorBenchmarks*
dotnet .\src\NEventStore.Persistence.MongoDB.Benchmark\bin\Release\net8.0\NEventStore.Persistence.MongoDB.Benchmark.dll --filter *ReadFromEventStoreAsyncBenchmarks.ReadFromEventStoreAsync*

Run Tests in Visual Studio

To run tests in visual studio using NUnit as a Test Runner you need to explicitly exclude "Explicit Tests" from running adding the following filter in the test explorer section:

-Trait:"Explicit"

GUID

Pay attention to GUID serialization and deserialization, MongoDB driver uses a specific representation for GUIDs.

Up to MongoDb 2.30.0 the driver uses the CSharpLegacy representation for GUIDs (drivers for other languages use a different byte ordering).

From 3.0.0 the driver default to the Standard representation (which has the same byte ordering in all the different drivers).

The CommitId of each CommitAttempt is actually a GUID, to guarantee compatibility for old projects you should to use the CSharpLegacy representation, you can do this either by:

• Configuring a GUID Serializer globally for the MongoDB driver:

  BsonSerializer.RegisterSerializer(new GuidSerializer(GuidRepresentation.CSharpLegacy));
  

• Customizing the serialization for the CommitId property of the MongoCommit class (see below):

  BsonClassMap.RegisterClassMap<MongoCommit>(cm =>
  {
   cm.AutoMap();
   cm.GetMemberMap(c => c.CommitId).SetSerializer(new GuidSerializer(GuidRepresentation.CSharpLegacy));
  });
  

To serialize GUIDs in Lists or Dictionary of objects, you should also remember to properly set the Guid representation for the object serializer, with something like:

BsonSerializer.RegisterSerializer(new ObjectSerializer(
 BsonSerializer.LookupDiscriminatorConvention(typeof(object)), GuidRepresentation.CSharpLegacy, ObjectSerializer.AllAllowedTypes));

Reference:

• GUIDs
• Guid Representation in Dictionary

Configure / Customize Commit Serialization

You can configure the serialization process using the standard methods offered by the MongoDB C# driver.

You'll need to specify the class mapping or implement an IBsonSerializationProvider for the MongoCommit class and register it before you start using any database operation.

For detailed information on how to configure the serialization in MongoDB head to the official Serialization page.

BsonClassMap

public static void MapMongoCommit()
{
 if (!BsonClassMap.IsClassMapRegistered(typeof(MongoCommit)))
 {
 BsonClassMap.RegisterClassMap<MongoCommit>(cm =>
 {
 cm.AutoMap();
 // change how the Headers collection is serialized
 cm.MapMember(c => c.Headers)
 .SetSerializer(
 new ImpliedImplementationInterfaceSerializer<IDictionary<string, object>, Dictionary<string, object>>()
 .WithImplementationSerializer(
 new DictionaryInterfaceImplementerSerializer<Dictionary<string, object>>(global::MongoDB.Bson.Serialization.Options.DictionaryRepresentation.Document)
 ));
 // your custom mapping goes here
 });
 }
}

IBsonSerializationProvider

class MongoCommitProvider : IBsonSerializationProvider
{
 public IBsonSerializer GetSerializer(Type type)
 {
 if (type == typeof(MongoCommit))
 {
 return new MongoCommitSerializer();
 }
 return null;
 }
}

class MongoCommitSerializer : SerializerBase<MongoCommit>
{
 public override MongoCommit Deserialize(BsonDeserializationContext context, BsonDeserializationArgs args)
 {
 // read the BsonDocument manually and return an instance of the MongoCommit class
 }

 public override void Serialize(BsonSerializationContext context, BsonSerializationArgs args, int value)
 {
 // write the BsonDocument manually serializing each property of the MongoCommit class
 }
}

You can then register the serialization provider using: BsonSerializer.RegisterSerializationProvider

How to contribute

Git-Flow

This repository uses GitFlow to develop, if you are not familiar with GitFlow you can look at the following link.

• A Successful Git Branching Model
• Git Flow Cheat-Sheet
• Git Flow for GitHub

Installing and configuring Git Flow

Probably the most straightforward way to install GitFlow on your machine is installing Git Command Line, then install the Visual Studio Plugin for Git-Flow. This plugin is accessible from the Team Explorer menu and allows you to install GitFlow extension directly from Visual Studio with a simple click. The installer installs standard GitFlow extension both for command line and for Visual Studio Plugin.

Once installed you can use GitFlow right from Visual Studio or from Command line, which one you prefer.

Build machine and GitVersion

Build machine uses GitVersion to manage automatic versioning of assemblies and Nuget Packages. You need to be aware that there are a rule that does not allow you to directly commit on master, or the build will fail.

A commit on master can be done only following the Git-Flow model, as a result of a new release coming from develop, or with an hotfix.

Quick Info for NEventStore projects

Just clone the repository and from command line checkout develop branch with

git checkout develop

Then from command line run GitFlow initialization scripts

git flow init

You can leave all values as default. Now your repository is GitFlow enabled.

Note on Nuget version on Nuspec

Remember to update .\src\.nuget\NEventStore.Persistence.MongoDB.nuspec file if needed (before creating relase packages).

The .nuspec file is needed because the new dotnet pack command has problems dealing with ProjectReferences, submodules get the wrong version number.

While we are on develop branch, (suppose we just bumped major number so the driver version number is 6.0.0-unstablexxxx), we need to declare that this persistence driver depends from a version greater than the latest published. If the latest version of NEventStore 5.x.x wave iw 5.4.0 we need to declare this package dependency as

(5.4, 7)

This means, that we need a NEventStore greater than the latest published, but lesser than the next main version. This allows version 6.0.0-unstable of NEventStore to satisfy the dependency. We remember that prerelease package are considered minor than the stable package. Es.

5.4.0 5.4.1 6.0.0-unstable00001 6.0.0