aspnetcore/tutorials/first-mongo-app/includes/first-mongo-app3-5.md
:::moniker range="< aspnetcore-6.0"
This tutorial creates a web API that runs Create, Read, Update, and Delete (CRUD) operations on a MongoDB NoSQL database.
In this tutorial, you learn how to:
[!div class="checklist"]
- Configure MongoDB
- Create a MongoDB database
- Define a MongoDB collection and schema
- Perform MongoDB CRUD operations from a web API
- Customize JSON serialization
View or download sample code (how to download)
If using Windows, MongoDB is installed at C:\Program Files\MongoDB by default. Add C:\Program Files\MongoDB\Server\<version_number>\bin to the Path environment variable. This change enables MongoDB access from anywhere on your development machine.
Use the mongo Shell in the following steps to create a database, make collections, and store documents. For more information on mongo Shell commands, see Working with the mongo Shell.
Choose a directory on your development machine for storing the data. For example, C:\BooksData on Windows. Create the directory if it doesn't exist. The mongo Shell doesn't create new directories.
Open a command shell. Run the following command to connect to MongoDB on default port 27017. Remember to replace <data_directory_path> with the directory you chose in the previous step.
mongod --dbpath <data_directory_path>
Open another command shell instance. Connect to the default test database by running the following command:
mongo
Run the following command in a command shell:
use BookstoreDb
A database named BookstoreDb is created if it doesn't already exist. If the database does exist, its connection is opened for transactions.
Create a Books collection using following command:
db.createCollection('Books')
The following result is displayed:
{ "ok" : 1 }
Define a schema for the Books collection and insert two documents using the following command:
db.Books.insertMany([{'Name':'Design Patterns','Price':54.93,'Category':'Computers','Author':'Ralph Johnson'}, {'Name':'Clean Code','Price':43.15,'Category':'Computers','Author':'Robert C. Martin'}])
The following result is displayed:
{
"acknowledged" : true,
"insertedIds" : [
ObjectId("5bfd996f7b8e48dc15ff215d"),
ObjectId("5bfd996f7b8e48dc15ff215e")
]
}
[!NOTE] The ID's shown in this article will not match the IDs when you run this sample.
View the documents in the database using the following command:
db.Books.find({}).pretty()
The following result is displayed:
{
"_id" : ObjectId("5bfd996f7b8e48dc15ff215d"),
"Name" : "Design Patterns",
"Price" : 54.93,
"Category" : "Computers",
"Author" : "Ralph Johnson"
}
{
"_id" : ObjectId("5bfd996f7b8e48dc15ff215e"),
"Name" : "Clean Code",
"Price" : 43.15,
"Category" : "Computers",
"Author" : "Robert C. Martin"
}
The schema adds an autogenerated _id property of type ObjectId for each document.
The database is ready. You can start creating the ASP.NET Core web API.
Go to File > New > Project.
Select the ASP.NET Core Web Application project type, and select Next.
Name the project BooksApi, and select Create.
Select the .NET Core target framework and ASP.NET Core 3.0. Select the API project template, and select Create.
Visit the NuGet Gallery: MongoDB.Driver to determine the latest stable version of the .NET driver for MongoDB. In the Package Manager Console window, navigate to the project root. Run the following command to install the .NET driver for MongoDB:
Install-Package MongoDB.Driver -Version {VERSION}
Run the following commands in a command shell:
dotnet new webapi -o BooksApi
code BooksApi
A new ASP.NET Core web API project targeting .NET Core is generated and opened in Visual Studio Code.
After the status bar's OmniSharp flame icon turns green, a dialog asks Required assets to build and debug are missing from 'BooksApi'. Add them?. Select Yes.
Visit the NuGet Gallery: MongoDB.Driver to determine the latest stable version of the .NET driver for MongoDB. Open Integrated Terminal and navigate to the project root. Run the following command to install the .NET driver for MongoDB:
dotnet add BooksApi.csproj package MongoDB.Driver -v {VERSION}
Add a Models directory to the project root.
Add a Book class to the Models directory with the following code:
using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;
namespace BooksApi.Models
{
public class Book
{
[BsonId]
[BsonRepresentation(BsonType.ObjectId)]
public string Id { get; set; }
[BsonElement("Name")]
public string BookName { get; set; }
public decimal Price { get; set; }
public string Category { get; set; }
public string Author { get; set; }
}
}
In the preceding class, the Id property is:
[BsonId] to make this property the document's primary key.[BsonRepresentation(BsonType.ObjectId)] to allow passing the parameter as type string instead of an ObjectId structure. Mongo handles the conversion from string to ObjectId.The BookName property is annotated with the [BsonElement] attribute. The attribute's value of Name represents the property name in the MongoDB collection.
Add the following database configuration values to appsettings.json:
:::code language="json" source="~/tutorials/first-mongo-app/samples/3.x/SampleApp/appsettings.json" highlight="2-6":::
Add a BookstoreDatabaseSettings.cs file to the Models directory with the following code:
:::code language="csharp" source="~/tutorials/first-mongo-app/samples/3.x/SampleApp/Models/BookstoreDatabaseSettings.cs":::
The preceding BookstoreDatabaseSettings class is used to store the appsettings.json file's BookstoreDatabaseSettings property values. The JSON and C# property names are named identically to ease the mapping process.
Add the following highlighted code to Startup.ConfigureServices:
:::code language="csharp" source="~/tutorials/first-mongo-app/samples_snapshot/3.x/SampleApp/Startup.ConfigureServices.AddDbSettings.cs" highlight="3-8":::
In the preceding code:
appsettings.json file's BookstoreDatabaseSettings section binds is registered in the Dependency Injection (DI) container. For example, a BookstoreDatabaseSettings object's ConnectionString property is populated with the BookstoreDatabaseSettings:ConnectionString property in appsettings.json.IBookstoreDatabaseSettings interface is registered in DI with a singleton service lifetime. When injected, the interface instance resolves to a BookstoreDatabaseSettings object.Add the following code to the top of Startup.cs to resolve the BookstoreDatabaseSettings and IBookstoreDatabaseSettings references:
:::code language="csharp" source="~/tutorials/first-mongo-app/samples/3.x/SampleApp/Startup.cs" id="snippet_UsingBooksApiModels":::
Add a Services directory to the project root.
Add a BookService class to the Services directory with the following code:
:::code language="csharp" source="~/tutorials/first-mongo-app/samples/3.x/SampleApp/Services/BookService.cs" id="snippet_BookServiceClass":::
In the preceding code, an IBookstoreDatabaseSettings instance is retrieved from DI via constructor injection. This technique provides access to the appsettings.json configuration values that were added in the Add a configuration model section.
Add the following highlighted code to Startup.ConfigureServices:
:::code language="csharp" source="~/tutorials/first-mongo-app/samples_snapshot/3.x/SampleApp/Startup.ConfigureServices.AddSingletonService.cs" highlight="9":::
In the preceding code, the BookService class is registered with DI to support constructor injection in consuming classes. The singleton service lifetime is most appropriate because BookService takes a direct dependency on MongoClient. Per the official Mongo Client reuse guidelines, MongoClient should be registered in DI with a singleton service lifetime.
Add the following code to the top of Startup.cs to resolve the BookService reference:
:::code language="csharp" source="~/tutorials/first-mongo-app/samples/3.x/SampleApp/Startup.cs" id="snippet_UsingBooksApiServices":::
The BookService class uses the following MongoDB.Driver members to run CRUD operations against the database:
MongoClient: Reads the server instance for running database operations. The constructor of this class is provided the MongoDB connection string:
:::code language="csharp" source="~/tutorials/first-mongo-app/samples/3.x/SampleApp/Services/BookService.cs" id="snippet_BookServiceConstructor" highlight="3":::
IMongoDatabase: Represents the Mongo database for running operations. This tutorial uses the generic GetCollection<TDocument>(collection) method on the interface to gain access to data in a specific collection. Run CRUD operations against the collection after this method is called. In the GetCollection<TDocument>(collection) method call:
collection represents the collection name.TDocument represents the CLR object type stored in the collection.GetCollection<TDocument>(collection) returns a MongoCollection object representing the collection. In this tutorial, the following methods are invoked on the collection:
Add a BooksController class to the Controllers directory with the following code:
:::code language="csharp" source="~/tutorials/first-mongo-app/samples/3.x/SampleApp/Controllers/BooksController.cs":::
The preceding web API controller:
BookService class to run CRUD operations.Create action method to return an HTTP 201 response. Status code 201 is the standard response for an HTTP POST method that creates a new resource on the server. CreatedAtRoute also adds a Location header to the response. The Location header specifies the URI of the newly created book.Build and run the app.
Navigate to https://localhost:<port>/api/books to test the controller's parameterless Get action method. The following JSON response is displayed:
[
{
"id":"5bfd996f7b8e48dc15ff215d",
"bookName":"Design Patterns",
"price":54.93,
"category":"Computers",
"author":"Ralph Johnson"
},
{
"id":"5bfd996f7b8e48dc15ff215e",
"bookName":"Clean Code",
"price":43.15,
"category":"Computers",
"author":"Robert C. Martin"
}
]
Navigate to https://localhost:<port>/api/books/{id here} to test the controller's overloaded Get action method. The following JSON response is displayed:
{
"id":"{ID}",
"bookName":"Clean Code",
"price":43.15,
"category":"Computers",
"author":"Robert C. Martin"
}
There are two details to change about the JSON responses returned in the Test the web API section:
bookName property should be returned as Name.To satisfy the preceding requirements, make the following changes:
Json.NET has been removed from ASP.NET shared framework. Add a package reference to Microsoft.AspNetCore.Mvc.NewtonsoftJson.
In Startup.ConfigureServices, chain the following highlighted code on to the AddControllers method call:
:::code language="csharp" source="~/tutorials/first-mongo-app/samples/3.x/SampleApp/Startup.cs" id="snippet_ConfigureServices" highlight="12":::
With the preceding change, property names in the web API's serialized JSON response match their corresponding property names in the CLR object type. For example, the Book class's Author property serializes as Author.
In Models/Book.cs, annotate the BookName property with the following [JsonProperty] attribute:
:::code language="csharp" source="~/tutorials/first-mongo-app/samples/3.x/SampleApp/Models/Book.cs" id="snippet_BookNameProperty" highlight="2":::
The [JsonProperty] attribute's value of Name represents the property name in the web API's serialized JSON response.
Add the following code to the top of Models/Book.cs to resolve the [JsonProperty] attribute reference:
:::code language="csharp" source="~/tutorials/first-mongo-app/samples/3.x/SampleApp/Models/Book.cs" id="snippet_NewtonsoftJsonImport":::
Repeat the steps defined in the Test the web API section. Notice the difference in JSON property names.
For more information on building ASP.NET Core web APIs, see the following resources:
:::moniker-end