"I love GitHub - TurnerSoftware/MongoFramework: An "Entity Framework"-like interface for MongoDB"

2022-09-30 03:57:03

Skip to content Toggle navigation Signup Product Actions Automate any workflow Packages Host and manage packages Security Find and fix vulnerabilities Codespaces Instant dev environments Copilot Write better code with AI Code review Manage code changes Issues Plan and track work Discussions Collaborate outside of code Explore All features Documentation GitHub Skills Blog Solutions By Plan Enterprise Teams Compare all By Solution CI/CD & Automation DevOps DevSecOps Case Studies Customer Stories Resources Open Source GitHub Sponsors Fund open source developers The ReadME Project GitHub community articles Repositories Topics Trending Collections Pricing Sign in Sign up {{ message }} TurnerSoftware / MongoFramework Public Notifications Fork 28 Star 251 An "Entity Framework"-like interface for MongoDB License MIT license 251 stars 28 forks Star Notifications Code Issues 26 Pull requests 2 Actions Projects 2 Security Insights More Code Issues Pull requests Actions Projects Security Insights TurnerSoftware/MongoFramework This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. main Switch branches/tags Branches Tags Could not load branches Nothing to show {{ refName }} default View all branches Could not load tags Nothing to show {{ refName }} default View all tags 3 branches 33 tags Code Clone HTTPS GitHub CLI Use Git or checkout with SVN using the web URL. Work fast with our official CLI. Learn more. Open with GitHub Desktop Download ZIP Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching Xcode If nothing happens, download Xcode and try again. Launching Visual Studio Code Your codespace will open once ready. There was a problem preparing your codespace, please try again. Latest commit dependabot[bot] Bump Microsoft.NET.Test.Sdk from 17.3.1 to 17.3.2 (#309) … 833cfcb Sep 27, 2022 Bump Microsoft.NET.Test.Sdk from 17.3.1 to 17.3.2 (#309) Bumps [Microsoft.NET.Test.Sdk](https://github.com/microsoft/vstest) from 17.3.1 to 17.3.2.- [Release notes](https://github.com/microsoft/vstest/releases)- [Commits](microsoft/[email protected])---updated-dependencies:- dependency-name: Microsoft.NET.Test.Sdk dependency-type: direct:production update-type: version-update:semver-patch...Signed-off-by: dependabot[bot] Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] 833cfcb Git stats 730 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time .github Fix MacOS CI Builds (#303) Aug 3, 2022 images Updated logo Oct 21, 2021 src Bump MongoDB.Driver from 2.17.0 to 2.17.1 (#301) Aug 8, 2022 tests Bump Microsoft.NET.Test.Sdk from 17.3.1 to 17.3.2 (#309) Sep 27, 2022 .appveyor.yml update dotnet6 Dec 27, 2021 .codecov.yml Remove codecov PR comments Dec 3, 2018 .editorconfig Added .editorconfig (#13) Feb 25, 2018 .gitignore Added MacOS Annoyances to gitignore Sep 26, 2020 CodeCoverage.runsettings Exclude methods by attribute Oct 10, 2020 License.txt Updated to use PackageLicenseFile for NuGet May 13, 2019 MongoFramework.sln Simplify AppVeyor building Mar 6, 2021 README.md Updated badges Oct 21, 2021 View code MongoFramework Overview Licensing and Support MongoFramework Extensions MongoFramework.Profiling.MiniProfiler Documentation Core Entity Mapping Indexing Special Index Types Contexts and Connections Special Queries Entity Buckets Extra Elements Runtime Type Discovery Complete Example README.md MongoFrameworkAn "Entity Framework"-like interface for MongoDBOverviewMongoFramework tries to bring some of the nice features from Entity Framework into the world of MongoDB.Some of the major features include:Entity mapping for collections, IDs and properties through attributesIndexing through attributes (including text and geospatial)Entity change trackingChangeset support (allowing for queuing multiple DB updates to run at once)Diff-updates (only changes to an entity to be written)Entity Buckets (clustering of small documents together, improving index performance)Runtime type discovery (serialize and deserialize without needing to specify every "known" type)MongoFramework is currently built on-top of the official MongoDB C# driver.Licensing and SupportMongoFramework is licensed under the MIT license. It is free to use in personal and commercial projects.There are support plans available that cover all active Turner Software OSS projects.Support plans provide private email support, expert usage advice for our projects, priority bug fixes and more.These support plans help fund our OSS commitments to provide better software for everyone.MongoFramework ExtensionsThese extensions are official packages that enhance the functionality of MongoFramework, integrating it with other systems and tools.MongoFramework.Profiling.MiniProfilerSupports profiling database reads and writes, pushing the data into MiniProfiler.DocumentationCore Entity MappingThe core mapping of entities and their properties is automatic however there are certain attributes you can apply to your properties to alter this behaviour.These attributes (and a few others) are part of the System.ComponentModel.Annotations package.AttributeDescription[Table("MyFancyEntity", Schema = "MyNamespace")]Map the Entity to the collection specified. When a schema is specified, it is prefixed onto the name with a "." (dot) separator.[Key]Map the property as the "Id" for the entity. Only required if your key doesn't have a common name like "Id" etc.[NotMapped]Unmaps the property from the entity when reading/writing.[Column("NewColumnName")]Remaps the property with the specified name when reading/writing.IndexingMongoFramework supports indexing specified through the IndexAttribute class. This is applied to the properties you want indexed and will apply the changes to the database when the context is saved.public class IndexExample{ public string Id { get; set; } [Index("Email", IndexSortOrder.Ascending)] public string EmailAddress { get; set; } public string Name { get; set; }}The following variations of indexes are supported across various property types:Single fieldCompoundMultikey indexesTo support compound indexes, define indexes with the same name across multiple properties.When doing this, you will want to control the order of the individual items in the compound index which is available through the IndexPriority property on the attribute.Special Index TypesMongoFramework supports Text and 2dSphere special indexes.These special index types are selected through the IndexType property on the Index attribute.Please consult MongoDB's documentation on when the indexes are appropriate and their restrictions.Contexts and ConnectionsLike Entity Framework, MongoFramework is built around contexts - specifically the MongoDbContext.An example context would look like:public class MyContext : MongoDbContext{ public MyContext(IMongoDbConnection connection) : base(connection) { } public MongoDbSet MyEntities { get; set; } public MongoDbSet MyOtherEntities { get; set; }}While it mostly feels the same as creating contexts in Entity Framework, there are a number of differences still with the biggest being in the creation of contexts.The IMongoDbConnection is the core infrastructure that allows connection to MongoDB and is required to instantiate a context.You can create an instance of a connection in two ways:IMongoDbConnection connection;//FromUrlconnection = MongoDbConnection.FromUrl(new MongoUrl("mongodb://localhost:27017/MyDatabase")); //MongoUrl comes from the official MongoDB driver//FromConnectionStringconnection = MongoDbConnection.FromConnectionString("mongodb://localhost:27017/MyDatabase");Special QueriesYou can perform text queries (with a Text index), geospatial distance queries (with a 2dSphere index) and geospatial intersecting queries.myContext.MyDbSet.SearchText("text to search");myContext.MyDbSet.SearchGeoIntersecting(e => e.FieldWithCoordinates, yourGeoJsonPolygon);myContext.MyDbSet.SearchGeoNear(e => e.FieldWithCoordinates, yourGeoJsonPoint);Each of these returns an IQueryable which you can continue to narrow down the results like you would normally with LINQ.For SearchGeoNear specifically, there are optional parameters for setting the distance result field, the minimum distance and the maximum distance.Entity BucketsEntity buckets are a method of storing many smaller documents in fewer larger documents. MongoFramework provides various classes that help in creating and managing buckets.A typical setup for using an entity bucket might look like:public class MyBucketGrouping{ public string SensorId { get; set; } public DateTime Date { get; set; }}public class MyBucketItem{ public DateTime EntryTime { get; set; } public int Value { get; set; }}public class MyContext : MongoDbContext{ public MyContext(IMongoDbConnection connection) : base(connection) { } [BucketSetOptions(bucketSize: 1000, entityTimeProperty: nameof(MyBucketItem.EntryTime))] public MongoDbBucketSet MyBuckets { get; set; }}The attribute BucketSetOptions is required.The bucketSize is the maximum number of items in a single bucket.The entityTimeProperty identifies the property name in the sub-entity where a timestamp is stored.Keep in mind the limitations of MongoDB (size of document) when determining the number of items in a bucket.Managing buckets is very similar to managing normal entities though are currently limited to add data only.using (var context = new MyContext(MongoDbConnection.FromConnectionString("mongodb://localhost:27017/MyDatabase"))){ context.MyBuckets.AddRange(new MyBucketGrouping { SensorId = "ABC123", Date = DateTime.Parse("2020-04-04") }, new [] { new MyBucketItem { EntryTime = DateTime.Parse("2020-04-04T01:00"), Amount = 123 }, new MyBucketItem { EntryTime = DateTime.Parse("2020-04-04T02:00"), Amount = 456 }, new MyBucketItem { EntryTime = DateTime.Parse("2020-04-04T03:00"), Amount = 789 } }); await context.SaveChangesAsync();}Extra ElementsSometimes your model in the database will have more fields than the model you are deserializing to. You have two options to control the behaviour: ignore the fields or accept, mapping the extra fields to a specific dictionary.To ignore the fields, you need to specify the IgnoreExtraElements attribute on the entity's class definition.To map the fields, you need to specify the ExtraElements attribute on an IDictionary property.Runtime Type DiscoveryMongoFramework provides runtime type discovery in two methods: automatically for any properties of type object and for any entities that specify the RuntimeTypeDiscovery attribute on their class definition.This type discovery means that you don't need to know what potential types extend any others which you would otherwise need to set via the BsonKnownTypes attribute by the MongoDB driver.[RuntimeTypeDiscovery]public class KnownBaseModel{}public class UnknownChildModel : KnownBaseModel{}public class UnknownGrandChildModel : UnknownChildModel{}Without the RuntimeTypeDiscovery attribute in this scenario, the model will fail to deserialize properly from the database.Complete Exampleusing MongoFramework;using System.ComponentModel.DataAnnotations;public class MyEntity{ public string Id { get; set; } public string Name { get; set; } public string Description { get; set; }}public class MyContext : MongoDbContext{ public MyContext(IMongoDbConnection connection) : base(connection) { } public MongoDbSet MyEntities { get; set; }}...var connection = MongoDbConnection.FromConnectionString("YOUR_CONNECTION_STRING");using (var myContext = new MyContext(connection)){ var myEntity = myContext.MyEntities.Where(myEntity => myEntity.Name == "MongoFramework").FirstOrDefault(); myEntity.Description = "An 'Entity Framework'-like interface for MongoDB"; await myContext.SaveChangesAsync();} About An "Entity Framework"-like interface for MongoDB Topics orm mongodb entity-mapping Resources Readme License MIT license Stars 251 starsWatchers 20 watchingForks 28 forks Releases 33 tags Sponsor this project Sponsor Learn more about GitHub Sponsors Packages 2 Used by 14 + 6 Contributors 7 Languages C# 100.0% Footer © 2022 GitHub, Inc. Footer navigation Terms Privacy Security Status Docs Contact GitHub Pricing API Training Blog About You can’t perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.