DEV Community: Dĵ ΝιΓΞΗΛψΚ

Building REST APIs In .NET 8 The Easy Way!

Dĵ ΝιΓΞΗΛψΚ — Wed, 05 Jan 2022 12:36:49 +0000

The goal of this article is to introduce you to an alternative, more developer friendly way of building Web APIs with ASP.NET 8 instead of the more commonly used MVC controllers.

We will be exploring the open source library FastEndpoints which is built on top of Minimal APIs introduced in .NET 6, where we can get all the performance benefits without the pain-points of Minimal APIs. The resulting code-base is cleaner to navigate and project maintainability becomes a breeze when combined with Vertical Slice Architecture, no matter the size or complexity of the project, because the framework stays out of your way so you can focus on the engineering & functional aspects of your systems.

Let's get our hands dirty by building a REST API for a simplified version of Dev.to where authors/posters can sign up for an account and publish articles. New articles will go into a moderation queue where the site administrator would have to approve it before being publicly available.

The main entities in our system would be the following:

Admin
Author
Article

The features/user stories of the system could be classified as follows:

Admin
- Login to site
- Get a list articles to be moderated
- Approve an article to publish it
- Reject an article with a reason
Author
- Sign up on site
- Login to site
- Get a list of their own articles
  - See status [pending/approved/rejected]
- Create new article
- Edit existing article
Public Area
- Get a list of 50 latest articles
- Get article by id
- Get latest 50 comments for an article
- Post a comment on an article

The tech stack used will be the following:

Base framework: ASP.NET 8
Endpoint framework: FastEndpoints
Authentication scheme: JWT Bearer
Input validation: FluentValidations
Data storage: MongoDB
API visualization: SwaggerUI

Let's go...

Create a new web project and install the dependencies either using visual studio or by running the following commands in a terminal window:



dotnet new web -n MiniDevTo
dotnet add package FastEndpoints
dotnet add package FastEndpoints.Swagger
dotnet add package MongoDB.Entities

Create the folder structure for our features so that it looks like the following:

Each last level of the tree is going to be a single endpoint which could either be a command or a query which the ui/frontend of our app can call. Queries are prefixed with Get as a convention indicating it is a retrieval of data, whereas commands are prefixed with verbs such as Save, Approve, Reject, etc. indicating committing of some state change. This might sound familiar if you've come across CQRS before, but we're not separating reads vs. writes here as done in CQRS. Instead, we're organizing our features/endpoints in accordance with Vertical Slice Architecture.

FastEndpoints is an implementation of REPR pattern. This will be the last pattern I'll talk about in this article, I promise!

The REPR Design Pattern defines web API endpoints as having three components: a Request, an Endpoint, and a Response. It simplifies the frequently-used MVC pattern and is more focused on API development.

So, in order to give us some relief from the boring, repetitive task of creating the multiple class files needed for an endpoint, go ahead and install either the Visual Studio or VS Code extension provided by FastEndpoints. Or you can just create those files manually.

Program.cs

First thing's first... Let's update Program.cs file to look like the following:



global using FastEndpoints;
global using FluentValidation;

var builder = WebApplication.CreateBuilder();
builder.Services.AddFastEndpoints();

var app = builder.Build();
app.UseFastEndpoints();
app.Run();

This is all that's needed for this to be a web API project. but... If you try to run the program now, you will be greeted with a run-time exception such as the following:

InvalidOperationException: 'FastEndpoints was unable to find any endpoint declarations!'

Let's fix that by creating our very first endpoint using the VS Extension.

Author Signup Endpoint

right-click the Author/Signup folder in visual studio > add > new item. then select FastEndpoints Feature FileSet new item template located under the Installed > Visual C# node. then for the file name, enter Author.Signup.cs as shown below:

What that will do is, it'll create a new set of files under the folder you selected with a namespace specific for this endpoint. open up Endpoint.cs file and have a look at the namespace at the top. It is what we typed in as the file name earlier.

While we have the endpoint class opened, go ahead and replace it's contents with the code below:



namespace Author.Signup;

public class Endpoint : Endpoint<Request, Response, Mapper>
{
    public override void Configure()
    {
        Post("/author/signup");
        AllowAnonymous();
    }

    public override async Task HandleAsync(Request r, CancellationToken c)
    {
        await SendAsync(new Response()
        {
            //blank for now
        });
    }
}

What do we have here? We have an endpoint class definition that inherits from the generic base class Endpoint<TRequest, TResponse, TMapper>. it has 2 overridden methods Configure() and HandleAsync().

In the configure method, we're specifying that we want the endpoint to listen for the http verb/method POST on the route /author/signup. We're also saying that unauthenticated users should be allowed to access this endpoint by using the AllowAnonymous() method.

The HandleAsync() method is where you'd write the logic for handling the incoming request. For now it's just sending a blank response because we haven't yet added any fields/properties to our request & response DTO classes.

Models.cs

Open up the Models.cs file and replace request and response classes with the following:



public class Request
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Email { get; set; }
    public string UserName { get; set; }
    public string Password { get; set; }
}

public class Response
{
    public string Message { get; set; }
}

Swagger UI

Now, let's setup Swagger so we have a way to interact with our endpoints using a web browser as opposed to using something like Postman. Open up Program.cs again and make it look like this:



global using FastEndpoints;
using FastEndpoints.Swagger; //add this

var builder = WebApplication.CreateBuilder();
builder.Services.AddFastEndpoints();
builder.Services.SwaggerDocument() //add this

var app = builder.Build();
app.UseFastEndpoints();
app.UseSwaggerGen(); //add this
app.Run();

Then open up Properties/launchSettings.json file and replace contents with this:



{
  "profiles": {
    "MiniDevTo": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "applicationUrl": "http://localhost:8080",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Updating launch-settings is not mandatory but let's fix the listening port of our API server to 8080 for the purpose of this article.

Next build and run your project in debug mode (CTRL+F5 in Visual Studio). Fire up your web browser and head on over to the url http://localhost:8080/swagger to see the Swagger UI.

You should now be seeing something like this:

Expand the /author/signup endpoint, and modify the request body/json to look like this (click Try It Out button to do so):



{
  "FirstName": "Johnny",
  "LastName": "Lawrence",
  "Email": "what@is.uber",
  "UserName": "EagleFang",
  "Password": "death2kobra"
}

Before executing the request, head on over to the Endpoint.cs file and place a breakpoint on line 14. Then go ahead and hit the execute button in swagger. Once the breakpoint is hit, inspect the request DTO parameter of the HandleAsync() method where you will see something like this:

That is basically how you receive a request from a client (Swagger UI in this case). The handler method is supplied with a fully populated POCO from the incoming http request. For a detailed explanation of how this model binding works, please have a look at the documentation page here.

Let's return a response from our endpoint now. Stop debugging and update the HandleAsync() method to look like the following:



public override async Task HandleAsync(Request r, CancellationToken c)
{
    await SendAsync(new Response()
    {
        Message = $"hello {r.FirstName} {r.LastName}! your request has been received!"
    });
}

Start the app again and execute the same request in Swagger UI. Which should display the response from the server as follows:

There are multiple ways to send responses back to the client from a handler. here we're sending a new instance of a response DTO populated with a custom message.

Input Validation

Open the Models.cs file and make the validator class look like the following:



public class Validator : Validator<Request>
{
    public Validator()
    {
        RuleFor(x => x.FirstName)
            .NotEmpty().WithMessage("your name is required!")
            .MinimumLength(3).WithMessage("name is too short!")
            .MaximumLength(25).WithMessage("name is too long!");

        RuleFor(x => x.Email)
            .NotEmpty().WithMessage("email address is required!")
            .EmailAddress().WithMessage("the format of your email address is wrong!");

        RuleFor(x => x.UserName)
            .NotEmpty().WithMessage("a username is required!")
            .MinimumLength(3).WithMessage("username is too short!")
            .MaximumLength(15).WithMessage("username is too long!");

        RuleFor(x => x.Password)
            .NotEmpty().WithMessage("a password is required!")
            .MinimumLength(10).WithMessage("password is too short!")
            .MaximumLength(25).WithMessage("password is too long!");
    }
}

Here we're defining the input validation requirements using Fluent Validation rules. Let's see what happens when the user input doesn't meet the above criteria. Execute the same request in swagger with the following incorrect json content:



{
  "LastName": "Lawrence",
  "Email": "what is email?",
  "UserName": "EagleFang",
  "Password": "123"
}

The server will respond with this:



{
  "StatusCode": 400,
  "Message": "One or more errors occured!",
  "Errors": {
    "FirstName": [ "your name is required!" ],
    "Email": [ "the format of your email address is wrong!" ],
    "Password": ["password is too short!" ]
  }
}

As you can see, if the incoming request data does not meet the validation criteria, a http 400 bad response is returned with the details of what is wrong. The handler logic will not be executed in case there is a validation error in the incoming request. This default behavior can be changed like this if need be.

Handler Logic

Let's go ahead and persist a new Author entity to the database by modifying the handler logic.



public override async Task HandleAsync(Request r, CancellationToken c)
{
    var author = Map.ToEntity(r);

    var emailIsTaken = await Data.EmailAddressIsTaken(author.Email);

    if (emailIsTaken)
        AddError(r => r.Email, "Sorry! Email address is already in use...");

    var userNameIsTaken = await Data.UserNameIsTaken(author.UserName);

    if (userNameIsTaken)
        AddError(r => r.UserName, "Sorry! Ehat username is not available...");

    ThrowIfAnyErrors();

    await Data.CreateNewAuthor(author);

    await SendAsync(new()
    {
        Message = "Thank you for signing up as an author!"
    });
}

First, we're using the ToEntity() method on the Map property of the endpoint class to transform the request dto into an Author domain entity. The logic for mapping is in the Mapper.cs file which can be found here. you can read more about the mapper class here.

Then we're asking the database if this email address is already taken by someone (code here). If it's already taken we're adding a validation error to the collection of errors of the endpoint using the AddError() method.

Next, we're asking the db if the username is already taken by someone and add an error if it's taken.

After all the business rules are checked, we want to send an error response to the client if any of the previous business rule checks have failed. that's what the ThrowIfAnyErrors() does. When either the username or email address is taken, a response like the following will be sent to the client. Execution is stopped at that point and the proceeding lines of code are not executed.



{
  "StatusCode": 400,
  "Message": "One or more errors occured!",
  "Errors": {
    "Email": [ "sorry! email address is already in use." ],
    "UserName": [ "sorry! that username is not available." ]
  }
}

If there are no validation errors added, and author creation worked, the following json response will be received by the client.



{

  "Message": "Thank you for signing up as an author!"

}

Congratulations!

You've persevered thus far and have your first working endpoint. If you're interested in completing this exercise, head on over to github and have a look through the full source code. Things should now be self explanatory. If something is unclear, please comment here or open a github issue. I will try my best to answer within 24hrs. Also have a look through the following resources which will explain most of the code.

Resources

In search of the (at least damn near)perfect application architecture...

Dĵ ΝιΓΞΗΛψΚ — Wed, 24 Jun 2020 03:12:34 +0000

so i've been messing around with a few different application layering styles & architectures and ended up with a solution i'm damn near perfectly happy with.

basically it's a pure vertical slice architecture where the service endpoints are isolated in their own slices that don't interact with each-other to avoid cross contamination.

i've also created a dotnet new template to help fast-track stubbing out new projects.

you can install the template and create a new project to play around with using the following commands:

  dotnet new -i MongoWebApiStarter
  dotnet new mongowebapi -n MyAwesomeApp

github repo for the project can be found here

i'd appreciate it if you guys could have a play with it and offer some feedback since i'm pretty sure there's room for improvement.

cheers!

Overcoming The Limitations Of MongoDB C# Driver

Dĵ ΝιΓΞΗΛψΚ — Wed, 26 Feb 2020 13:52:59 +0000

the mongodb driver has it's limits and sometimes you need to compose advanced queries either by hand or using a query editor/composer. to be able to run those queries and inject values from your C# code, you're required to compose BsonDocuments or do string concatenation which leads to an ugly, unreadable, magic string infested abomination.

in order to combat this problem and also to couple your C# entity schema to raw queries, the library MongoDB.Entities offers a templating system based on tag replacement.

take the following find query for example:

db.Book.find(
  {
    Title : 'book_name',
    Price : book_price
  }
)

to couple this text query to your C# models and pass in the values for title and price, simply surround the parts you want replaced with < and > in order to turn them in to replacement tags/markers like this:

db.Book.find(
  {
    <Title> : '<book_name>',
    <Price> : <book_price>
  }
)

the templating system is based on a special class called Template. you simply instantiate a 'Template' object supplying the tagged/marked text query to the constructor. then you chain method calls on the Template object to replace each tag you've marked on the query like so:

var query = new Template<Book>(@"
{
  <Title> : '<book_name>',
  <Price> : <book_price>
}")
.Path(b => b.Title)    
.Path(b => b.Price)
.Tag("book_name","The Power Of Now")
.Tag("book_price","10.95");

var result = await DB.Find<Book>()
                     .Match(query)
                     .ExecuteAsync();

the resulting query sent to mongodb is this:

db.Book.find(
  {
    Title : 'The Power Of Now',
    Price : 10.95
  }
)

the .Tag() method simply replaces matching tags on the text query with the supplied value. you don't have to use the < and > characters while using the .Tag() method. infact, avoid it as the tags won't match if you use them.

the .Path() method is one of many offered by the Prop class you can use to get the full 'dotted' path of a property by supplying a lambda/member expression. please see the documentation of the 'Prop' class here for the other methods available.

notice, that most of these 'Prop' methods only require a single parameter. whatever member expression you supply to them gets converted to a property/field path like this:

expression: x => x.Authors[0].Books[0].Title

resulting path: Authors.Books.Title

if your text query has a tag <Authors.Books.Title> it will get replaced by the resulting path from the 'Prop' class method.

the template system will throw an exception in the event of the following 3 scenarios.

the input query/text has no tags marked using < and > characters.
the input query has tags that you forget to specify replacements for.
you have specified replacements that doesn't have a matching tag in the query.

this kind of runtime errors are preferable than your code failing silently because the queries didn't produce any results or produced the wrong results.

Some Examples:

Aggregation Pipeline:

var pipeline = new Template<Book>(@"
[
    {
      $match: { <Title>: '<book_name>' }
    },
    {
      $sort: { <Price>: 1 }
    },
    {
      $group: {
        _id: '$<AuthorId>',
        product: { $first: '$$ROOT' }
      }
    },
    {
      $replaceWith: '$product'
    }
]")
.Path(b => b.Title)
.Path(b => b.Price)
.Path(b => b.AuthorId)
.Tag("book_name", "MongoDB Templates");

var book = await DB.PipelineSingleAsync(pipeline);

Find With Match Expression:

var query = new Template<Author>(@"
{
  $and: [
    { $gt: [ '$<Age>', <author_age> ] },
    { $eq: [ '$<Surname>', '<author_surname>' ] }
  ]
}")
.Path(a => a.Age)
.Path(a => a.Surname)
.Tag("author_age", "54")
.Tag("author_surname", "Tolle");

var authors = await DB.Find<Author>()
                      .MatchExpression(query)
                      .ExecuteAsync();

Update With Aggregation Pipeline Stages:

var pipeline = new Template<Author>(@"
[
  { $set: { <FullName>: { $concat: ['$<Name>',' ','$<Surname>'] } } },
  { $unset: '<Age>'}
]")             
.Path(a => a.FullName)
.Path(a => a.Name)
.Path(a => a.Surname)
.Path(a => a.Age);

await DB.Update<Author>()
        .Match(a => a.ID == "xxxxx")
        .WithPipeline(pipeline)
        .ExecutePipelineAsync();

Update With Array Filters:

var filters = new Template<Author>(@"
[
  { '<a.Age>': { $gte: <age> } },
  { '<b.Name>': 'Echkart Tolle' }
]")
.Elements(0, author => author.Age)
.Elements(1, author => author.Name);
.Tag("age", "55")        

var update = new Template<Book>(@"
{ $set: { 
    '<Authors.$[a].Age>': <age>,
    '<Authors.$[b].Name>': '<name>'
  } 
}")
.PosFiltered(book => book.Authors[0].Age)
.PosFiltered(book => book.Authors[1].Name)
.Tag("age", "55")
.Tag("name", "Updated Name");

await DB.Update<Book>()
        .Match(book => book.ID == "xxxxxxxx")
        .WithArrayFilters(filters)
        .Modify(update)
        .ExecuteAsync();

Next Steps...

hope the above text query template system has piqued your interest enough to go deeper into learning how to use mongodb with C#. the package MongoDB.Entities makes it extremely easy to communicate with mongodb server. every aspect of it's api has been documented on the official website. you can also checkout the source code on github:

dj-nitehawk / MongoDB.Entities

A data access library for MongoDB with an elegant api, LINQ support and built-in entity relationship management

MongoDB.Entities

A light-weight .net standard library with barely any overhead that aims to simplify access to mongodb by abstracting the official driver while adding useful features on top of it resulting in an elegant API surface which produces beautiful, human friendly data access code.

More Info:

please visit the official website for detailed documentation:

https://mongodb-entities.com

View on GitHub

MongoDB Web-Api Starter Template For `dotnet new`

Dĵ ΝιΓΞΗΛψΚ — Fri, 24 Jan 2020 17:27:05 +0000

I've developed a dotnet new starter template for scaffolding a web-api project with mongodb. It was designed with ease of development and maintenance in mind. The level of complexity of the architecture is extremely low compared to what you'd typically see with N-tier architecture. The code should be self explanatory. Some features include:

Vertical slice architecture
JWT token based authentication
Claims & permission based authorization
Input validation
Password hashing
Email sending
Image uploading
Strongly-typed app settings
Integration tests

You can see the source code from the github repository below or simply install and scaffold a new project to play with using the following code:

    dotnet new -i MongoWebApiStarter
    dotnet new mongowebapi -n MyAwesomeApp

dj-nitehawk / MongoWebApiStarter

A full-featured starter template for `dotnet new` to quickly scaffold an Asp.Net 6 Web-Api project with MongoDB as the data store.

MongoWebApiStarter

A full-featured starter template for dotnet new to quickly scaffold an Asp.Net 6 Web-Api project using pure vertical slice architecture with MongoDB as the data store.

Install & Scaffold

  dotnet new -i MongoWebApiStarter
  dotnet new mongowebapi -n MyAwesomeApp

Features

Platform

base framework: .net 6
api/web-service framework: FastEndpoints
language: c#
database: mongodb

Vertical Slice Architecture

each use case/action/feature is isolated in it's own namespace (vertical slice).
there is no cross contamination between feature slices.
domain entities are contained in a seperate namespace as they are cross contaminating by nature.
does not use the mediator pattern like most other templates.

Misc. Features

strongly typed app settings which binds to appsettings.json
JWT token authentication with embedded claims & permissions
permission & claim based authorization
custom middleware for putting site offline (maintenance mode)

Api Features

input validation with fluentvalidation rules
account creation, email validation, login
salted hash password storage and verification…

View on GitHub

Tutorial: GeoSpatial Search In MongoDB The Easy Way!

Dĵ ΝιΓΞΗΛψΚ — Thu, 16 Jan 2020 10:50:32 +0000

let's say we have a bunch of art galleries stored in mongodb located in paris and we want to retrieve only those that are within 20 kilometers of the eiffel tower.

mongodb makes it extremely easy if you store the entities properly tagged with their longitudes and latitudes.

Getting Started

if you haven't already, please see the introductory article mentioned below in order to get a new project setup before continuing with the rest of this article.

Tutorial: MongoDB With C# The Easy Way!

Dĵ ΝιΓΞΗΛψΚ ・ Jan 1 '20

#mongodb #dotnet #csharp #tutorial

Define The Gallery Entity

public class ArtGallery : Entity
{
    public string Name { get; set; }
    public Coordinates2D Location { get; set; }
}

the Coordinates2D type is a special class supplied by the library to streamline the storage & retrieval of geographical data.

Create Some Entities

await new[]
{
    new ArtGallery {
        Name = "Galleria Le-Pari",
        Location = new Coordinates2D(48.8539241, 2.2913515)
    },
    new ArtGallery {
        Name = "Versailles House Of Art",
        Location = new Coordinates2D(48.796964, 2.137456)
    },
    new ArtGallery {
        Name = "Poissy Arts & Crafts",
        Location = new Coordinates2D(48.928860, 2.046889)
    }
}.SaveAsync();

we are setting the locations of these galleries by creating new instances of Coordinates2D class supplying the longitude and latitude to the constructor. finally the whole array is persisted to mongodb by calling the .SaveAsync() extension method which issues a bulk write command.

Create An Index

mongodb geospatial queries require an index to be created which can be easily done as follows:

await DB.Index<ArtGallery>()
        .Key(g => g.Location, KeyType.Geo2DSphere)
        .Option(o => o.Background = false)
        .CreateAsync();

we specify the index key as the Location property of the ArtGallery class and type of key as Geo2DSphere. also we are telling mongodb to build the index in the foreground with the .Option() method.

Do The Search

var locEiffelTower = new Coordinates2D(48.857908, 2.295243);

var results = await DB.Find<ArtGallery>()
                      .Match(g => g.Location, locEiffelTower, 20000)
                      .ExecuteAsync();

foreach (var gallery in results)
{
    Console.WriteLine(gallery.Name);
}

Console.Read();

first we define the search point, which in this case is the location/coordinates of the eiffel tower in paris.

then we issue a find command that has the following matching criteria/arguments:

the property where coordinates are stored on the ArtGallery entity.
the search point to base the matching on.
how far away from the search point (in meters) - at maximum should matches be located in.

The End Result

after running the find command you will see the following output in the console window:

Galleria Le-Pari
Versailles House Of Art

notice that Poissy Arts & Crafts has been excluded. that is because it is located further than 20KMs from the eiffel tower.

Getting Distances Back

if you need to also retrieve how far away each gallery is from the eiffel tower, simply do the following:

add the following import:

using MongoDB.Driver;

add another property to the ArtGallery entity like so:

public double DistanceInMeters { get; set; }

query mongodb with the IAggregateFluent interface like so:

var results = await DB.FluentGeoNear<ArtGallery>(
                          NearCoordinates: locEiffelTower,
                          DistanceField: g => g.DistanceInMeters,
                          MaxDistance: 20000)
                      .ToListAsync();

write to the console like so:

foreach (var gallery in results)
{
    Console.WriteLine(
    $"{gallery.Name} - {(gallery.DistanceInMeters / 1000).ToString("00.00")} KM");
}

Next Steps...

if the above exercise has piqued your interest enough to discover how to easily get things done with mongodb using c#, please visit the official website of MongoDB.Entities. you can also check out the source code on github:

dj-nitehawk / MongoDB.Entities

A data access library for MongoDB with an elegant api, LINQ support and built-in entity relationship management

MongoDB.Entities

More Info:

please visit the official website for detailed documentation:

https://mongodb-entities.com

View on GitHub

Tutorial: Fuzzy Text Search In MongoDB The Easy Way!

Dĵ ΝιΓΞΗΛψΚ — Tue, 14 Jan 2020 15:26:02 +0000

if you've ever worked with mongodb, you may already know that mongodb server does not have a built-in mechanism to search for documents based on fuzzy matching. say for example you have a couple of people saved in your database with the following names:



- Katheryne Markus
- Catherine Marcus
- Marcus Katerin Thompson
- Jack Jonas

and the requirement is to retrieve all records that sounds similar to Catheryn Marcus.

we want the resulting record set to only include the first 3 people and the most relevant person to be on top.

let's see how we can achieve this goal step-by-step...

Getting Started

if you haven't already, please see the introductory article mentioned below in order to get a new project scafolded and setup before continuing with the rest of this article.

Tutorial: MongoDB With C# The Easy Way!

Dĵ ΝιΓΞΗΛψΚ ・ Jan 1 '20

#mongodb #dotnet #csharp #tutorial

Define The Entity Class

add a new class file called Person.cs and add the following code to it:



public class Person : Entity
{
    public FuzzyString Name { get; set; }
}

in order to make fuzzy matching work with mongodb we need to store text data in a special FuzzyString type property. that class/type is provided by the MongoDB.Entities library we are using.

Create A Text Index

fuzzy text searching requires the use of a mongodb text index which can be easily created like this:



await DB.Index<Person>()
        .Key(p => p.Name, KeyType.Text)
        .CreateAsync();

the above code should be self explanatory, if not please see the documentation here.

Store The Entities



await new[]
{   new Person { Name = "Jack Jonas" },
    new Person { Name = "Marcus Katerin Thompson" },
    new Person { Name = "Catherine Marcus" },
    new Person { Name = "Katheryne Markus" }
}.SaveAsync();

nothing fancy here. just doing a bulk save of multiple records MongoDB.Entities style ;-)

Do The Fuzzy Search



var people = DB.Find<Person>()
               .Match(Search.Fuzzy, "Catheryn Marcus")
               .ExecuteAsync();

here we're saying find Person entities that fuzzily matches the words Catheryn Marcus from the text index. you can read more about how this works under the hood in the documentation here.

Sort By Relevance

now that we have the results from the database, the following utility method can be used to get a sorted list that uses the levenshtein distance method.



var list = people.SortByRelevance("Catheryn Marcus", p => p.Name);

foreach (var person in list)
{
    Console.WriteLine(person.Name);
}

Console.Read();

you will now see the following result displayed in the console window:



    Catherine Marcus
    Katheryne Markus
    Marcus Katerin Thompson

which is exactly the end result we expected.

Next Steps...

i've purposefully tried to keep this tutorial as brief as possible to get your feet wet on the concepts of the library. if the above code seems easy and interesting please refer to the official website of MongoDB.Entities. you can also check out the source code on github:

dj-nitehawk / MongoDB.Entities

A data access library for MongoDB with an elegant api, LINQ support and built-in entity relationship management

MongoDB.Entities

More Info:

please visit the official website for detailed documentation:

https://mongodb-entities.com

View on GitHub

Tutorial: MongoDB With C# The Easy Way!

Dĵ ΝιΓΞΗΛψΚ — Wed, 01 Jan 2020 11:31:03 +0000

the goal of this article is to familiarize you with an alternative, less verbose & convenient way to store and retrieve data in MongoDB server compared to what you'd typically see with such tutorials. hopefully by the end of this article you'll see the light and decide to ditch SQL Server & Entity Framework and get onboard the mongo train.

Install MongoDB server

if you don't already have mongodb server running on your machine, please follow the tutorial below before moving forward.

How To Install MongoDB Server On Windows & Linux

Dĵ ΝιΓΞΗΛψΚ ・ Dec 30 '19

#nosql #mongodb #database #tutorial

Scaffold a console application project

create a new console application project using visual studio targetting .net core or enter the following in a powershell/cmd window:

dotnet new console -n LearnMongo
start .\LearnMongo\LearnMongo.csproj

Install Dependencies

open the package manager console and enter the following:
tip: tools > nuget package manager > package manager console

Install-Package MongoDB.Entities

Initialize Database Connection

open Program.cs file and make it look like the following:

using MongoDB.Entities;
using System.Threading.Tasks;

namespace LearnMongo
{
    static class Program
    {
        private async static Task Main()
        {
            await DB.InitAsync("MyDatabase", "localhost", 27017);
        }
    }
}

we're specifying that this application should store our data in a database called MyDatabase in the mongodb server running on localhost listening on the default port.

Saving Entities

add a new class file called Person.cs to the project and make it look like the following:

using MongoDB.Entities;
using System;

namespace LearnMongo
{
    public class Person : Entity
    {
        public string Name { get; set; }
        public DateTime DateOfBirth { get; set; }
        public int SiblingCount { get; set; }
    }
}

main/root entities you want persisted to mongodb must inherit from the class Entity which is supplied by the package we installed earlier.

then go back to the Program.cs file and add the following below the db initialization line:

var lisa = new Person
{
    Name = "Lisa Malfrey",
    DateOfBirth = new DateTime(1983, 10, 11),
    SiblingCount = 1
};

await lisa.SaveAsync();

Console.WriteLine($"Lisa's ID: {lisa.ID}");
Console.Read();

now run the program by hitting ctrl+f5. you will see that the entity was saved and automatically assigned an ID.

note: the ID property comes from the base Entity class so that we don't have to keep adding it manually to each entity we create.

if you look inside the database using a db manager or mongo shell, you'll see that a collection called Person was created and a new record was added which looks like this:

{
    "_id": ObjectId("5e0c682ddd3765736cb8ca56"),
    "Name": "Lisa Malfrey",
    "DateOfBirth": ISODate("1983-10-10T18:30:00Z"),
    "SiblingCount": 1
}

Retrieving Entities

data can be retrieved in a couple of different ways. here are a few examples:

find by ID

var result = await DB.Find<Person>().OneAsync(lisa.ID);

Console.WriteLine($"Found Person: {result.Name}");
Console.Read();

find by sibling count

var result = (await DB.Find<Person>()
                      .ManyAsync(p => p.SiblingCount >= 1))
                      .First();

Console.WriteLine($"Count: {result.SiblingCount}");
Console.Read();

here we're saying find many Person entities who has at least 1 sibling. the .First() linq method simply picks the first person from the found list.

find by date range

var result = await DB.Queryable<Person>()
                     .Where(p => p.DateOfBirth > new DateTime(1983, 10, 10) &&
                                 p.DateOfBirth < new DateTime(1983, 10, 12))
                     .FirstOrDefaultAsync();

Console.WriteLine($"Birthday: {result.DateOfBirth.ToLocalTime()}");
Console.Read();

here we're using the IQueryable interface to retrieve the first person who has a date of birth that falls within the range of two dates.

Updating Entities

you can either retrieve the complete entity, update it's properties and save it back to the database or update certain properties of entities without retrieving them first.

update by retrieving complete entity

var person = await DB.Find<Person>().OneAsync(lisa.ID);

person.Name = "Lisa Kudrow";
person.SiblingCount = 2;

await person.SaveAsync();

update properties without retrieving

await DB.Update<Person>()
        .Match(p => p.ID == lisa.ID)
        .Modify(p => p.Name, "Lisa Kudrow")
        .Modify(p => p.SiblingCount, 2)
        .ExecuteAsync();

Next Steps...

hope the above code has piqued your interest enough to go deeper into learning how to use mongodb with c# the easy way. the package MongoDB.Entities makes it extremely easy to communicate with mongodb server. every aspect of it's api has been documented on the official website. you can also check out the source code on github:

dj-nitehawk / MongoDB.Entities

A data access library for MongoDB with an elegant api, LINQ support and built-in entity relationship management

MongoDB.Entities

More Info:

please visit the official website for detailed documentation:

https://mongodb-entities.com

View on GitHub

How To Install MongoDB Server On Windows & Linux

Dĵ ΝιΓΞΗΛψΚ — Mon, 30 Dec 2019 12:27:33 +0000

Installation of MongoDB takes less than 5 minutes on both Windows and Linux. Here are the steps you need to take in order to be up and running as fast as possible.

Note: MongoDB is at version 5.0.0 as of writing this article. Please post a comment below if you'd like me to update the tutorial for the latest version.

On Linux

open up a terminal and issue the following commands to install the server. these commands are for a 64-bit ubuntu system. if you're linux flavor is different, please click here for instructions.

wget -qO - https://www.mongodb.org/static/pgp/server-5.0.asc | sudo apt-key add -
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/5.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-5.0.list
sudo apt-get update
sudo apt-get install -y mongodb-org
mkdir /mongodb
mkdir /mongodb/log
sudo chown -R mongodb:mongodb /mongodb
echo "" > /etc/mongod.conf
nano /etc/mongod.conf

then copy & paste the following into nano, save & exit.

storage:
  dbPath: /mongodb
  directoryPerDB: true
  journal:
    enabled: true

systemLog:
  destination: file
  logAppend: true
  path:  /mongodb/log/mongod.log

net:
  port: 27017
  bindIp: 127.0.0.1

then enter the following in the terminal, which will show that mongodb server is active and running.

systemctl enable mongod.service
sudo service mongod start
sudo service mongod status

On Windows

first download the installer msi from this direct link and run it. do the following during installation:

choose the complete installation option
check the install mongodb as a service box
select run service as network service user
change data directory to: C:\MongoDB\Data
change log directory to: C:\MongoDB\Log
uncheck the install mongodb compass box

note: the installer will try to start the mongodb service and fail sometimes. if that happens simply choose to ignore and finish the installation.

if starting the service did not fail, enter the following command in an administrator cmd window to stop the service before proceeding to the next step:

net stop mongodb

next, create a text file called mongod.cfg somewhere and paste the following in to it. save & close the file afterwards.

storage:
  dbPath: C:\MongoDB\Data
  directoryPerDB: true
  journal:
    enabled: true

systemLog:
  destination: file
  logAppend: true
  path:  C:\MongoDB\Log\mongod.log

net:
  port: 27017
  bindIp: 127.0.0.1

now, copy mongod.cfg file over to the following location replacing the existing file there: C:\Program Files\MongoDB\Server\5.0\bin

then open up an administrator cmd window and enter the following to start the mongodb service:

net start mongodb

next, add the above folder to the system path environment variable by running the following command in an administrator cmd window:

setx path /M "%path%";"%ProgramFiles%\MongoDB\Server\5.0\bin"
exit

Test Your Installation

open up a terminal/ cmd window and enter the following command:

mongo

enter the following at the mongo shell prompt that comes up:

show dbs

it should give you an output similar to this:

admin   0.000GB
config  0.000GB
local   0.000GB

that's it for the installation and configuration of mongodb server. if you don't like dealing with the mongo shell, you can use a gui database manager. below is a list of such managers in order of personal preference: