-->![Mongodb Mongodb](/uploads/1/2/5/2/125213917/264621480.png)
![Mongodb Mongodb](https://raw.githubusercontent.com/mrvautin/mrvautin.github.io/master/images/adminMongo/adminMongo_manageindexes.png)
Database Toolbox Interface for MongoDB Installation. To use the Database Toolbox™ interface for MongoDB ®, you must first install it. Ensure that the interface supports your MongoDB version and that you have administrator privileges on your machine. MongoDB Drivers Specs; Driver Compatibility; MongoDB Integration and Tools. MongoDB Connector for Business Intelligence; MongoDB ODBC Driver for BI Connector; HTTP Interface; Platforms. Amazon EC2; EC2 Backup and Restore; Microsoft Azure; Windows Quick Links and Reference Center; Use Cases. Storing Log Data; Hierarchical Aggregation; Product.
By Pratik Khandelwal and Scott Addie
This tutorial creates a web API that performs Create, Read, Update, and Delete (CRUD) operations on a MongoDB NoSQL database.
In this tutorial, you learn how to:
![Mongodb Mongodb](/uploads/1/2/5/2/125213917/264621480.png)
- 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)
Prerequisites
- Visual Studio 2019 with the ASP.NET and web development workload
Configure MongoDB
If using Windows, MongoDB is installed at C:Program FilesMongoDB by default. Add C:Program FilesMongoDBServer<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. - Open another command shell instance. Connect to the default test database by running the following command:
- Run the following in a command shell:If it doesn't already exist, a database named BookstoreDb is created. If the database does exist, its connection is opened for transactions.
- Create a
Books
collection using following command:The following result is displayed: - Define a schema for the
Books
collection and insert two documents using the following command:The following result is displayed: - View the documents in the database using the following command:The following result is displayed:The schema adds an autogenerated
_id
property of typeObjectId
for each document.
The database is ready. You can start creating the ASP.NET Core web API.
Create the ASP.NET Core web API project
- 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 2.2. 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:
- Run the following commands in a command shell: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:
- Go to File > New Solution > .NET Core > App.
- Select the ASP.NET Core Web API C# project template, and select Next.
- Select .NET Core 2.2 from the Target Framework drop-down list, and select Next.
- Enter BooksApi for the Project Name, and select Create.
- In the Solution pad, right-click the project's Dependencies node and select Add Packages.
- Enter MongoDB.Driver in the search box, select the MongoDB.Driver package, and select Add Package.
- Select the Accept button in the License Acceptance dialog.
Add an entity model
- Add a Models directory to the project root.
- Add a
Book
class to the Models directory with the following code:In the preceding class, theId
property:- Is required for mapping the Common Language Runtime (CLR) object to the MongoDB collection.
- Is annotated with [BsonId] to designate this property as the document's primary key.
- Is annotated with [BsonRepresentation(BsonType.ObjectId)] to allow passing the parameter as type
string
instead of an ObjectId structure. Mongo handles the conversion fromstring
toObjectId
.
TheBookName
property is annotated with the [BsonElement] attribute. The attribute's value ofName
represents the property name in the MongoDB collection.
Add a configuration model
- Add the following database configuration values to appsettings.json:
- Add a BookstoreDatabaseSettings.cs file to the Models directory with the following code:The preceding
BookstoreDatabaseSettings
class is used to store the appsettings.json file'sBookstoreDatabaseSettings
property values. The JSON and C# property names are named identically to ease the mapping process. - Add the following highlighted code to
Startup.ConfigureServices
:In the preceding code:- The configuration instance to which the appsettings.json file's
BookstoreDatabaseSettings
section binds is registered in the Dependency Injection (DI) container. For example, aBookstoreDatabaseSettings
object'sConnectionString
property is populated with theBookstoreDatabaseSettings:ConnectionString
property in appsettings.json. - The
IBookstoreDatabaseSettings
interface is registered in DI with a singleton service lifetime. When injected, the interface instance resolves to aBookstoreDatabaseSettings
object.
- The configuration instance to which the appsettings.json file's
- Add the following code to the top of Startup.cs to resolve the
BookstoreDatabaseSettings
andIBookstoreDatabaseSettings
references:
Add a CRUD operations service
- Add a Services directory to the project root.
- Add a
BookService
class to the Services directory with the following code:In the preceding code, anIBookstoreDatabaseSettings
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
:In the preceding code, theBookService
class is registered with DI to support constructor injection in consuming classes. The singleton service lifetime is most appropriate becauseBookService
takes a direct dependency onMongoClient
. 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:
The
BookService
class uses the following MongoDB.Driver
members to perform CRUD operations against the database:- MongoClient – Reads the server instance for performing database operations. The constructor of this class is provided the MongoDB connection string:
- IMongoDatabase – Represents the Mongo database for performing operations. This tutorial uses the generic GetCollection<TDocument>(collection) method on the interface to gain access to data in a specific collection. Perform 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:- DeleteOne – Deletes a single document matching the provided search criteria.
- Find<TDocument> – Returns all documents in the collection matching the provided search criteria.
- InsertOne – Inserts the provided object as a new document in the collection.
- ReplaceOne – Replaces the single document matching the provided search criteria with the provided object.
Add a controller
Add a
BooksController
class to the Controllers directory with the following code:The preceding web API controller:
- Uses the
BookService
class to perform CRUD operations. - Contains action methods to support GET, POST, PUT, and DELETE HTTP requests.
- Calls CreatedAtRoute in the
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 aLocation
header to the response. TheLocation
header specifies the URI of the newly created book.
Test the web API
- Build and run the app.
- Navigate to
http://localhost:<port>/api/books
to test the controller's parameterlessGet
action method. The following JSON response is displayed: - Navigate to
http://localhost:<port>/api/books/5bfd996f7b8e48dc15ff215e
to test the controller's overloadedGet
action method. The following JSON response is displayed:
Configure JSON serialization options
There are two details to change about the JSON responses returned in the Test the web API section:
- The property names' default camel casing should be changed to match the Pascal casing of the CLR object's property names.
- The
bookName
property should be returned asName
.
To satisfy the preceding requirements, make the following changes:
- In
Startup.ConfigureServices
, chain the following highlighted code on to theAddMvc
method call: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, theBook
class'sAuthor
property serializes asAuthor
. - In Models/Book.cs, annotate the
BookName
property with the following [JsonProperty] attribute:The[JsonProperty]
attribute's value ofName
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: - Repeat the steps defined in the Test the web API section. Notice the difference in JSON property names.
Next steps
For more information on building ASP.NET Core web APIs, see the following resources:
-->By Pratik Khandelwal and Scott Addie
This tutorial creates a web API that performs Create, Read, Update, and Delete (CRUD) operations on a MongoDB NoSQL database.
In this tutorial, you learn how to:
- 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)
Prerequisites
- Visual Studio 2019 with the ASP.NET and web development workload
Configure MongoDB
If using Windows, MongoDB is installed at C:Program FilesMongoDB by default. Add C:Program FilesMongoDBServer<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. - Open another command shell instance. Connect to the default test database by running the following command:
- Run the following in a command shell:If it doesn't already exist, a database named BookstoreDb is created. If the database does exist, its connection is opened for transactions.
- Create a
Books
collection using following command:The following result is displayed: - Define a schema for the
Books
collection and insert two documents using the following command:The following result is displayed: - View the documents in the database using the following command:The following result is displayed:The schema adds an autogenerated
_id
property of typeObjectId
for each document.
The database is ready. You can start creating the ASP.NET Core web API.
Create the ASP.NET Core web API project
- 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 2.2. 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:
- Run the following commands in a command shell: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:
- Go to File > New Solution > .NET Core > App.
- Select the ASP.NET Core Web API C# project template, and select Next.
- Select .NET Core 2.2 from the Target Framework drop-down list, and select Next.
- Enter BooksApi for the Project Name, and select Create.
- In the Solution pad, right-click the project's Dependencies node and select Add Packages.
- Enter MongoDB.Driver in the search box, select the MongoDB.Driver package, and select Add Package.
- Select the Accept button in the License Acceptance dialog.
Add an entity model
- Add a Models directory to the project root.
- Add a
Book
class to the Models directory with the following code:In the preceding class, theId
property:- Is required for mapping the Common Language Runtime (CLR) object to the MongoDB collection.
- Is annotated with [BsonId] to designate this property as the document's primary key.
- Is annotated with [BsonRepresentation(BsonType.ObjectId)] to allow passing the parameter as type
string
instead of an ObjectId structure. Mongo handles the conversion fromstring
toObjectId
.
TheBookName
property is annotated with the [BsonElement] attribute. The attribute's value ofName
represents the property name in the MongoDB collection.
Add a configuration model
- Add the following database configuration values to appsettings.json:
- Add a BookstoreDatabaseSettings.cs file to the Models directory with the following code:The preceding
BookstoreDatabaseSettings
class is used to store the appsettings.json file'sBookstoreDatabaseSettings
property values. The JSON and C# property names are named identically to ease the mapping process. - Add the following highlighted code to
Startup.ConfigureServices
:In the preceding code:- The configuration instance to which the appsettings.json file's
BookstoreDatabaseSettings
section binds is registered in the Dependency Injection (DI) container. For example, aBookstoreDatabaseSettings
object'sConnectionString
property is populated with theBookstoreDatabaseSettings:ConnectionString
property in appsettings.json. - The
IBookstoreDatabaseSettings
interface is registered in DI with a singleton service lifetime. When injected, the interface instance resolves to aBookstoreDatabaseSettings
object.
- The configuration instance to which the appsettings.json file's
- Add the following code to the top of Startup.cs to resolve the
BookstoreDatabaseSettings
andIBookstoreDatabaseSettings
references:
Add a CRUD operations service
- Add a Services directory to the project root.
- Add a
BookService
class to the Services directory with the following code:In the preceding code, anIBookstoreDatabaseSettings
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
:In the preceding code, theBookService
class is registered with DI to support constructor injection in consuming classes. The singleton service lifetime is most appropriate becauseBookService
takes a direct dependency onMongoClient
. 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:
The
BookService
class uses the following MongoDB.Driver
members to perform CRUD operations against the database:- MongoClient – Reads the server instance for performing database operations. The constructor of this class is provided the MongoDB connection string:
- IMongoDatabase – Represents the Mongo database for performing operations. This tutorial uses the generic GetCollection<TDocument>(collection) method on the interface to gain access to data in a specific collection. Perform 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:- DeleteOne – Deletes a single document matching the provided search criteria.
- Find<TDocument> – Returns all documents in the collection matching the provided search criteria.
- InsertOne – Inserts the provided object as a new document in the collection.
- ReplaceOne – Replaces the single document matching the provided search criteria with the provided object.
Add a controller
Add a
BooksController
class to the Controllers directory with the following code:The preceding web API controller:
- Uses the
BookService
class to perform CRUD operations. - Contains action methods to support GET, POST, PUT, and DELETE HTTP requests.
- Calls CreatedAtRoute in the
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 aLocation
header to the response. TheLocation
header specifies the URI of the newly created book.
Test the web API
- Build and run the app.
- Navigate to
http://localhost:<port>/api/books
to test the controller's parameterlessGet
action method. The following JSON response is displayed: - Navigate to
http://localhost:<port>/api/books/5bfd996f7b8e48dc15ff215e
to test the controller's overloadedGet
action method. The following JSON response is displayed:
Configure JSON serialization options
![Mongodb Mongodb](https://raw.githubusercontent.com/mrvautin/mrvautin.github.io/master/images/adminMongo/adminMongo_manageindexes.png)
There are two details to change about the JSON responses returned in the Test the web API section:
- The property names' default camel casing should be changed to match the Pascal casing of the CLR object's property names.
- The
bookName
property should be returned asName
.
To satisfy the preceding requirements, make the following changes:
- In
Startup.ConfigureServices
, chain the following highlighted code on to theAddMvc
method call: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, theBook
class'sAuthor
property serializes asAuthor
. - In Models/Book.cs, annotate the
BookName
property with the following [JsonProperty] attribute:The[JsonProperty]
attribute's value ofName
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: - Repeat the steps defined in the Test the web API section. Notice the difference in JSON property names.
Next steps
For more information on building ASP.NET Core web APIs, see the following resources: