Install-Package EasyMongo -Version 0.1.3-alpha -Pre
MongoDB and it's C# driver are great but its operations aren't driven by interfaces, making dependency injection, Inversion of Control and testing in support of composite architectures additional development effort.
EasyMongo addresses this to support componentized connection, database, collection and document Read, Write Update operations. Operational scoping supports the principle of least responsibility/LoD and is helpful in developing reusable and maintanable software and applications - thus EasyMongo.
Succinctly you might say that EasyMongo:
- Is a facade and superset of the official 10gen MongoDB C# driver
- Supplies additional asynchronous functionality in two flavors: - asynchronous delegate callbacks - System.Threading.Tasks
- Interface-driven object model simplifies testing and supports DI/IoC.
- Reinterfaces operations of the underlying 10gen driver for simplistic client consumption supporting rapid application development.
- Is predecated on architectural operational granularity and least responsibility
- .Net 4.5
- Built on top of MongoDB C# driver 1.9.2
- 350+ end-to-end NUnit integration tests written to execute against a localhost mongoDB server
- 93.2% code coverage
- Execute in 4 minutes
- Useful as documentation of functionality
- Executes against started, localhost mongoDB server (accessible via the connection string: "mongodb://localhost", or within MongoVue simply "localhost")
Install the latest nuget package via Visual Studio's Package Manager Console:
Install-Package EasyMongo -Version 0.1.3-alpha -Pre
When using EasyMongo you will be referencing components using the interfaces within the EasyMongo.Contract namespace:
IAsyncDelegateReader - granual asynch CRUD operations with delegate callback
IAsyncDelegateReaderT (generic impl)
IAsyncDelegateUpdater
IAsyncDelegateUpdaterT
IAsyncDelegateWriter
IAsyncDelegateWriterT
IAsyncReader - granular asynch CRUD operations with System.Threading.Tasks
IAsyncReaderT
IAsyncUpdater
IAsyncUpdaterT
IAsyncWriter
IAsyncWriterT
ICollectionReader - synchronous and asynch operations for a single collection
ICollectionReaderT
ICollectionUpdater
ICollectionUpdaterT
ICollectionWriter
ICollectionWriterT
IDatabaseConnection - connection operations for a database
IDatabaseReader - synchronous and asynch operations for a single database
IDatabaseReaderT
IDatabaseUpdater
IDatabaseUpdaterT
IDatabaseWriter
IDatabaseWriterT
IReader - granual CRUD operations
IReaderT
IServerConnection - connection operations for a server/
IUpdater
IUpdaterT
IWriter
IWriterT
These interfaces are implemented by the following classes:
EasyMongo.Async.Delegates.AsyncDelegateReader
EasyMongo.Async.Delegates.AsyncDelegateReaderT
EasyMongo.Async.Delegates.AsyncDelegateUpdater
EasyMongo.Async.Delegates.AsyncDelegateUpdaterT
EasyMongo.Async.Delegates.AsyncDelegateWriter
EasyMongo.Async.Delegates.AsyncDelegateWriterT
EasyMongo.Async.AsyncReader
EasyMongo.Async.IAsyncReaderT
EasyMongo.Async.AsyncUpdater
EasyMongo.Async.AsyncUpdaterT
EasyMongo.Async.AsyncWriter
EasyMongo.Async.AsyncWriterT
EasyMongo.Collection.CollectionReader
EasyMongo.Collection.CollectionReaderT
EasyMongo.Collection.CollectionUpdater
EasyMongo.Collection.CollectionUpdaterT
EasyMongo.Collection.CollectionWriter
EasyMongo.Collection.CollectionWriterT
EasyMongo.DatabaseConnection
EasyMongo.Database.DatabaseReader
EasyMongo.Database.DatabaseReaderT
EasyMongo.Database.DatabaseUpdater
EasyMongo.Database.DatabaseUpdaterT
EasyMongo.Database.DatabaseWriter
EasyMongo.Database.DatabaseWriterT
EasyMongo.Reader
EasyMongo.ReaderT
EasyMongo.ServerConnection
EasyMongo.Updater
EasyMongo.UpdaterT
EasyMongo.Writer
EasyMongo.WriterT
You can manually wire them up like so:
IServerConnection serverConnection = new ServerConnection("mongodb://localhost");
IDatabaseConnection databaseConnection = new DatabaseConnection(serverConnection, "MyMongoDatabase");
IReader reader = new Reader(databaseConnection);
...but it's really designed to integrate into your favorite dependency injection framework. The registrations are simplistic and intuitive so integrating the parts of EasyMongo you need (and nothing else!) is meant to be easy.
-
Startup a localhost MongoDB server.
-
Step through the following [TestFixture] located at EasyMongo.Test.ReadmeExampleTestFixture.cs to see execution paths. The free MongoDB visualization tool, MongoVue may be useful for following CRUD operations against the MongoDB.
namespace EasyMongo.Readme.Example.Test { using System; using System.Collections.Generic; using System.Linq; using System.Threading; using EasyMongo; using EasyMongo.Async; using EasyMongo.Async.Delegates; using EasyMongo.Collection; using EasyMongo.Contract; using EasyMongo.Database; using MongoDB.Bson; using MongoDB.Driver; using MongoDB.Driver.Builders; using Ninject; using NUnit.Framework;
/// <summary> /// A cute overview of how EasyMongo functions /// </summary> /// <remarks>Requires localhost MongoDB server running at execution time!</remarks> [TestFixture] public class ReadmeExampleTestFixture { readonly string LOCAL_MONGO_SERVER_CONNECTION_STRING = "mongodb://localhost"; AutoResetEvent _readerAutoResetEvent = new AutoResetEvent(false); protected Exception _asyncException = null; protected List<Entry> _asyncReadResults = new List<Entry>(); IServerConnection _serverConnection; IDatabaseConnection _databaseConnection; [TestFixtureSetUp] public void TestFixtureSetUp() { // initialize a server connection to a locally-running MongoDB server _serverConnection = new ServerConnection(LOCAL_MONGO_SERVER_CONNECTION_STRING); // connect to the existing db on the server (or create it if it does not already exist) _databaseConnection = new DatabaseConnection(_serverConnection, "MyFirstDatabase"); } [Test] public async void Test() { _databaseConnection.Connect(); ///////////////////////////////////// // OPERATIONAL, CONTEXUAL SCOPE... // ///////////////////////////////////// // create a Writer to write to the database IWriter writer = new Writer(_databaseConnection); // create a Reader to read from the database IReader reader = new Reader(_databaseConnection); // create an Updater to update the database IUpdater updater = new Updater(_databaseConnection); Entry exampleMongoDBEntry = new Entry(); exampleMongoDBEntry.Message = "Hello"; // write the object to the "MyFirstCollection" Collection that exists within the // previously referenced "MyFirstDatabase" that was used to create the "writer" object writer.Write<Entry>("MyFirstCollection", exampleMongoDBEntry); IEnumerable<Entry> readEntrys = reader.Read<Entry>("MyFirstCollection", // within this collection... "Message",// for the object field "Description" "Hello");// return matches for 'Hello' Assert.AreEqual(1, readEntrys.Count()); //////////////////////////////////// // AND ASYNCHRONOUS OPERATIONS... // //////////////////////////////////// // read, write and update asynchronously using System.Threading.Task IAsyncReader asyncReader = new AsyncReader(reader); readEntrys = await asyncReader.ReadAsync<Entry>("MyFirstCollection", "Message", "Hello"); Assert.AreEqual(1, readEntrys.Count()); IAsyncWriter asyncWriter = new AsyncWriter(writer); IAsyncUpdater asyncUpdater = new AsyncUpdater(updater); // or delegate call backs IAsyncDelegateReader asyncDelegateReader = new AsyncDelegateReader(reader); asyncDelegateReader.AsyncReadCompleted += new ReadCompletedEvent(readerCallBack); asyncDelegateReader.ReadAsync<Entry>("MyFirstCollection", "Message", "Hello"); _readerAutoResetEvent.WaitOne(); Assert.AreEqual(1, _asyncReadResults.Count()); IAsyncDelegateWriter asyncDelegateWriter = new AsyncDelegateWriter(writer); IAsyncDelegateUpdater asyncDelegateUpdater = new AsyncDelegateUpdater(updater); ///////////////////////////////////////////// // FOR A SERVER, DATABASE OR COLLECTION... // ///////////////////////////////////////////// // get a little higher level with the EasyMongo.Database namespace to target a database for operations IDatabaseReader databaseReader = new DatabaseReader(reader, asyncReader); IDatabaseWriter databaseWriter = new DatabaseWriter(writer, asyncWriter); IDatabaseUpdater databaseUpdater = new DatabaseUpdater(updater, asyncUpdater); // or a little lower level with the EasyMongo.Collection namespace to target a specific Collection ICollectionReader collectionReader = new CollectionReader(databaseReader, "MyFirstCollection"); ICollectionWriter collectionWriter = new CollectionWriter(databaseWriter, "MyFirstCollection"); ICollectionUpdater collectionUpdater = new CollectionUpdater(databaseUpdater, "MyFirstCollection"); /////////////////////////////////////////////// // TO RESTRICT CLIENT SCOPE (LAW OF DEMETER) // /////////////////////////////////////////////// // operate only against "MyFirstDatabase"'s "MySecondCollection" readEntrys = collectionReader.Read<Entry>("Message", "Hello"); Assert.AreEqual(1, readEntrys.Count()); ///////////////////// // GENERIC CLASSES // ///////////////////// // Instead of defining generic type arguments at the method level, // you can do it once at the class declaration IWriter<Entry> writerT = new Writer<Entry>(writer); writerT.Write("MySecondCollection", new Entry() { Message = "Goodbye World (Generically)" }); /////////////////////////////// // SIMPLIFY CREATION VIA IoC // /////////////////////////////// // because EasyMongo is a componentized framework built with blocks of functionality, EasyMongo // works great with DI containers and Inversion of Control. // here's an example of using the nuget Ninject extension to load EasyMongo mappings and a conn // string from configuration Ninject.IKernel kernel = new Ninject.StandardKernel(); ICollectionUpdater<Entry> collectionUpdaterT = kernel.TryGet<ICollectionUpdater<Entry>>(); // the alternative to this would be: IServerConnection serverConn = new ServerConnection(LOCAL_MONGO_SERVER_CONNECTION_STRING); IDatabaseConnection databaseConnn = new DatabaseConnection(serverConn, "MyFirstDatabase"); IDatabaseUpdater databaseUpdatr = new DatabaseUpdater(updater, asyncUpdater); ICollectionUpdater collectionUpdaterTheHardWay = new CollectionUpdater(databaseUpdater, "MySecondCollection"); ///////////////////////// // SIMPLE QUERIES... // ///////////////////////// databaseReader.Read<Entry>("MyFirstCollection", "Message", "Hello"); readEntrys = await databaseReader.ReadAsync<Entry>("MyFirstCollection", "Message", "Hello"); Assert.AreEqual(1, readEntrys.Count()); ///////////////////////// // POWERFUL QUERIES... // ///////////////////////// // when more robust querying is needed leverage power of underlying MongoDB driver IMongoQuery IMongoQuery query1 = Query.Matches("Message", new BsonRegularExpression("HE", "i")); IEnumerable<Entry> queryResults = reader.Execute<Entry>("MyFirstCollection", query1); Assert.AreEqual(1, queryResults.Count()); Assert.AreEqual("Hello", queryResults.ElementAt(0).Message); ////////////////////// // AND COMBINATIONS // ////////////////////// Entry exampleMongoDBEntry2 = new Entry(); exampleMongoDBEntry2.Message = "Hello Again"; Entry exampleMongoDBEntry3 = new Entry(); exampleMongoDBEntry3.Message = "Goodbye"; writer.Write<Entry>("MyFirstCollection", exampleMongoDBEntry2); writer.Write<Entry>("MyFirstCollection", exampleMongoDBEntry3); // "AND" multiple IMongoQueries... IMongoQuery query2 = Query.Matches("Message", new BsonRegularExpression("Again")); queryResults = reader.ExecuteAnds<Entry>("MyFirstCollection", new []{ query1, query2}); Assert.AreEqual(1, queryResults.Count()); Assert.AreEqual("Hello Again", queryResults.ElementAt(0).Message); // "OR" multiple IMongoQueries... IMongoQuery query3 = Query.Matches("Message", new BsonRegularExpression("Goo")); queryResults = reader.ExecuteOrs<Entry>("MyFirstCollection", new[] { query1, query2, query3 }); Assert.AreEqual(3, queryResults.Count()); Assert.AreEqual("Hello", queryResults.ElementAt(0).Message); Assert.AreEqual("Hello Again", queryResults.ElementAt(1).Message); Assert.AreEqual("Goodbye", queryResults.ElementAt(2).Message); } [TestFixtureTearDown] public void TestFixtureTearDown() { _databaseConnection.DropCollection<Entry>("MyFirstCollection");// remove test entrys _databaseConnection.DropCollection<Entry>("MySecondCollection"); } void readerCallBack(object e, Exception ex) { _asyncException = ex; IEnumerable<Entry> results = (IEnumerable<Entry>)e; _asyncReadResults.AddRange(results); _readerAutoResetEvent.Set(); } }}