Skip to content

Commit ec51e2a

Browse files
jordan-smith721jordan-smith721
authored
DOCSP-32169 Add configuration page (#11)
1 parent d8f9d9f commit ec51e2a

File tree

8 files changed

+199
-5
lines changed

8 files changed

+199
-5
lines changed

‎snooty.toml

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
name = "entity-framework"
22
title = "Entity Framework"
33
toc_landing_pages = [
4-
#"/fundamentals/connection",
4+
"/fundamentals/configure",
55
#"/fundamentals/crud",
66
#"/usage-examples",
77
#"/fundamentals",
@@ -15,16 +15,18 @@ intersphinx = [
1515
sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
1616

1717
[constants]
18-
provider-long = "MongoDB Entity Framework Provider"
19-
provider-short = "Entity Framework Provider"
18+
provider-long = "MongoDB Entity Framework Core Provider"
19+
provider-short = "Entity Framework Core Provider"
20+
csharp-driver-long = "MongoDB .NET/C# Driver"
21+
csharp-driver-short = ".NET/C# Driver"
2022
framework = "Entity Framework"
2123
framework-core = "{+framework+} Core"
2224
framework-version = "7.0"
2325
language = "C#"
2426
mongo-community = "MongoDB Community Edition"
2527
mongo-enterprise = "MongoDB Enterprise Edition"
26-
docs-branch = "master" # always set this to the docs branch (i.e. master, 1.7, 1.8, etc.)
27-
version-number = "7.0" # always set this to the driver branch (i.e. 1.7.0, 1.8.0, etc.)
28+
docs-branch = "master" # always set this to the docs branch (i.e. master, 1.7, 1.8, etc.)
29+
version-number = "7.0" # always set this to the driver branch (i.e. 1.7.0, 1.8.0, etc.)
2830
version = "v{+version-number+}"
2931
stable-api = "Stable API"
3032
bool-data-type = "``boolean``"

‎source/fundamentals.txt

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. _entity-framework-fundamentals:
2+
3+
============
4+
Fundamentals
5+
============
6+
7+
.. meta::
8+
:description: Learn how to use the {+provider-long+}.
9+
10+
.. toctree::
11+
:titlesonly:
12+
:maxdepth: 1
13+
14+
/fundamentals/configure
15+
16+
- :ref:`entity-framework-configure`

‎source/fundamentals/configure.txt

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
.. _entity-framework-configure:
2+
3+
===========================================
4+
Configure Entity Framework Core for MongoDB
5+
===========================================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: EF, EF Core, code example
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
In this guide, you will learn how to configure an application to use the
21+
{+provider-long+}. To learn how to set up a new project and install the
22+
{+provider-short+}, see the :ref:`entity-framework-quickstart`.
23+
24+
Create a POCO
25+
-------------
26+
27+
Create a `Plain old CLR/Class object
28+
<https://en.wikipedia.org/wiki/Plain_old_CLR_object>`__, or **POCO**, to use as
29+
a model for your entity. A POCO is a simple class object that doesn't inherit
30+
features from any framework-specific base classes or interfaces.
31+
32+
The following code example shows how to create a POCO that represents a customer:
33+
34+
.. literalinclude:: /includes/fundamentals/code-examples/configure/Customer.cs
35+
:language: csharp
36+
:copyable:
37+
38+
.. tip::
39+
40+
To learn more about POCOs, see the :driver:`POCO guide
41+
</csharp/current/fundamentals/serialization/poco/>` in the
42+
{+csharp-driver-short+} documentation.
43+
44+
Create a DB Context Class
45+
-------------------------
46+
47+
To begin using {+framework-core+}, create a context class that derives from
48+
`DBContext <https://learn.microsoft.com/en-us/dotnet/api/system.data.entity.dbcontext>`__.
49+
The ``DbContext`` derived class instance represents a database session and is used to
50+
query and save instances of your entities.
51+
52+
The ``DBContext`` class exposes ``DBSet`` properties that specify the entities you
53+
can interact with while using that context.
54+
55+
The following example creates an instance of a ``DBContext`` derived class and
56+
specifies the ``Customer`` object as a ``DBSet`` property:
57+
58+
.. literalinclude:: /includes/fundamentals/code-examples/configure/MyDBContext.cs
59+
:language: csharp
60+
:copyable:
61+
62+
The previous code example overrides the ``OnModelCreating()`` method. Overriding
63+
the ``OnModelCreating()`` method allows you to specify configuration details for your
64+
model and its properties. This example uses the ``ToCollection()`` method to
65+
specify that the ``Customer`` entities in your application map to the
66+
``customers`` collection in MongoDB.
67+
68+
.. TODO: Link to a page that goes over methods available to use in OnModelCreating
69+
70+
Use MongoDB
71+
-----------
72+
73+
Once you've created a ``DBContext`` class, construct a
74+
``DbContextOptionsBuilder`` object and call its ``UseMongoDB()`` method. This
75+
method takes two parameters: a ``MongoClient`` instance and
76+
the name of the database that stores the collections you are working with.
77+
78+
The ``UseMongoDB()`` method returns a ``DbContextOptions`` object. Pass the
79+
``Options`` property of this object to the constructor for your ``DBContext``
80+
class.
81+
82+
The following example shows how to construct a ``DBContext`` object in
83+
this way:
84+
85+
.. literalinclude:: /includes/fundamentals/code-examples/configure/UseMongoDB.cs
86+
:language: csharp
87+
:copyable:
88+
89+
.. tip:: Creating a MongoClient
90+
91+
You can call methods from the {+csharp-driver-long+} when using
92+
the {+provider-short+}. The previous example uses the
93+
``MongoClient()`` method from the {+csharp-driver-short+} to create a MongoDB
94+
client that connects to a MongoDB instance.
95+
96+
To learn more about using the {+csharp-driver-long+}
97+
to connect to MongoDB, see the
98+
:driver:`Connection guide </csharp/current/fundamentals/connection/connect/>`
99+
in the {+csharp-driver-short+} documentation.
100+
101+
Example
102+
-------
103+
104+
The following code example shows how to configure the
105+
{+provider-short+} and insert a document into the database:
106+
107+
.. literalinclude:: /includes/fundamentals/code-examples/configure/ConfigureEFProvider.cs
108+
:language: csharp
109+
:copyable:

‎source/includes/fundamentals/code-examples/configure/ConfigureEFProvider.cs

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
using Microsoft.EntityFrameworkCore;
2+
using MongoDB.Bson;
3+
using MongoDB.Driver;
4+
using Microsoft.Extensions.Configuration;
5+
using MongoDB.EntityFrameworkCore.Extensions;
6+
7+
var mongoClient = new MongoClient("<Your MongoDB Connection URI>");
8+
9+
var dbContextOptions =
10+
new DbContextOptionsBuilder<MyDbContext>().UseMongoDB(mongoClient, "<Database Name>");
11+
12+
var db = new MyDbContext(dbContextOptions.Options);
13+
14+
// Add a new customer and save it to the database
15+
db.Customers.Add(new Customer() { name = "John Doe", Order = "1 Green Tea" });
16+
db.SaveChanges();
17+
18+
internal class Customer
19+
{
20+
public ObjectId Id { get; set; }
21+
public String Name { get; set; }
22+
public String Order { get; set; }
23+
}
24+
25+
internal class MyDbContext : DbContext
26+
{
27+
public DbSet<Customer> Customers { get; init; }
28+
29+
public MyDbContext(DbContextOptions options)
30+
: base(options)
31+
{
32+
}
33+
34+
protected override void OnModelCreating(ModelBuilder modelBuilder)
35+
{
36+
base.OnModelCreating(modelBuilder);
37+
modelBuilder.Entity<Customer>().ToCollection("customers");
38+
}
39+
}

‎source/includes/fundamentals/code-examples/configure/Customer.cs

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
public class Customer
2+
{
3+
public ObjectId Id { get; set; }
4+
public String Name { get; set; }
5+
public String Order { get; set; }
6+
}

‎source/includes/fundamentals/code-examples/configure/MyDBContext.cs

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
public class MyDbContext : DbContext
2+
{
3+
public DbSet<Customer> Customers { get; init; }
4+
5+
public MyDbContext(DbContextOptions options)
6+
: base(options)
7+
{
8+
}
9+
10+
protected override void OnModelCreating(ModelBuilder modelBuilder)
11+
{
12+
base.OnModelCreating(modelBuilder);
13+
modelBuilder.Entity<Customer>().ToCollection("customers");
14+
}
15+
}

‎source/includes/fundamentals/code-examples/configure/UseMongoDB.cs

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
var mongoClient = new MongoClient("<Your MongoDB Connection URI>");
2+
3+
var dbContextOptions =
4+
new DbContextOptionsBuilder<MyDbContext>().UseMongoDB(mongoClient, "<Database Name");
5+
6+
var db = new MyDbContext(dbContextOptions.Options);

‎source/index.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66

77
/quick-start
88
/quick-reference
9+
/fundamentals
910
/issues-and-help
1011

1112
Introduction

0 commit comments

Comments
 (0)