DOCSP-32166 - Write Basics (#16)

Author: jordan-smith721

source/fundamentals.txt

@@ -13,5 +13,6 @@ Fundamentals
 
    /fundamentals/configure
    /fundamentals/query-data
+   /fundamentals/write-data
 
 - :ref:`entity-framework-configure`

source/fundamentals/query-data.txt

@@ -58,9 +58,6 @@ the planet name to the console:
    :language: csharp
    :dedent:
 
-To learn more about the ``FirstOrDefault()`` method, see the `.NET API documentation
-<https://learn.microsoft.com/en-us/dotnet/api/system.linq.queryable.firstordefault?view=net-8.0>`__.
-
 Find Multiple Entities
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -77,9 +74,6 @@ The following code uses the ``Where()`` method to find all planets that have the
    :language: csharp
    :dedent:
 
-To learn more about the ``Where()`` method, see the `.NET API documentation
-<https://learn.microsoft.com/en-us/dotnet/api/microsoft.entityframeworkcore.query.queryablemethods.where>`__.
-
 Sort Entities
 -------------
 
@@ -117,17 +111,11 @@ prints the results to the console.
       Uranus
       Neptune
 
-To learn more about the ``OrderBy()`` method, see the `.NET API documentation
-<https://learn.microsoft.com/en-us/dotnet/api/system.linq.queryable.orderby>`__.
-
 .. tip:: Sort in Descending Order
 
    You can sort the results of a query in descending order by using the
    ``OrderByDescending()`` method.
 
-   To learn more about the ``OrderByDescending()`` method, see the `.NET API documentation
-   <https://learn.microsoft.com/en-us/dotnet/api/system.linq.queryable.orderbydescending>`__.
-
 You can perform a secondary sort on your query by using the ``ThenBy()`` method. The
 ``ThenBy()`` method sorts the results of the ``OrderBy()`` method in ascending
 order based on a specified sort criteria. The ``ThenBy()`` method should be
@@ -138,9 +126,6 @@ chained to the ``OrderBy()`` method.
    You can perform a secondary sort in descending order by using the
    ``ThenByDescending()`` method.
 
-   To learn more about the ``ThenByDescending()`` method, see the `.NET API documentation
-   <https://learn.microsoft.com/en-us/dotnet/api/system.linq.queryable.thenbydescending>`__.
-
 The following code uses the ``OrderBy()`` and ``ThenBy()`` methods to find all
 planets and sort them by the ``hasRings()`` field, with a secondary sort
 on the ``name`` field.
@@ -176,5 +161,15 @@ on the ``name`` field.
    When sorting on fields with a boolean value, entities with a field value of
    ``false`` show before those with a value of ``true``.
 
-To learn more about the ``ThenBy()`` method, see the `.NET API documentation
-<https://learn.microsoft.com/en-us/dotnet/api/system.linq.queryable.thenby>`__.
+Additional Information
+----------------------
+
+To learn more about the methods discussed in this guide, see the following .NET API
+documentation links:
+
+- `FirstOrDefault() <https://learn.microsoft.com/en-us/dotnet/api/system.linq.queryable.firstordefault>`__
+- `Where() <https://learn.microsoft.com/en-us/dotnet/api/microsoft.entityframeworkcore.query.queryablemethods.where>`__
+- `OrderBy() <https://learn.microsoft.com/en-us/dotnet/api/system.linq.queryable.orderby>`__
+- `OrderByDescending() <https://learn.microsoft.com/en-us/dotnet/api/system.linq.queryable.orderbydescending>`__
+- `ThenBy() <https://learn.microsoft.com/en-us/dotnet/api/system.linq.queryable.thenby>`__
+- `ThenByDescending() <https://learn.microsoft.com/en-us/dotnet/api/system.linq.queryable.thenbydescending>`__

source/fundamentals/write-data.txt

@@ -0,0 +1,147 @@
+.. _entity-framework-write-data:
+
+=====================
+Write Data to MongoDB
+=====================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: EF, EF Core, code example, write
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+{+framework-core+} allows you to work with data in your application without
+explicitly running database commands. You can insert, update, or delete data
+within your application and persist those changes to MongoDB by using the
+``SaveChanges()`` method.
+
+When you call the ``SaveChanges()`` method, the {+provider-short+} automatically detects
+any changes made to your data and runs the necessary commands to update the
+database by using the MongoDB Query API.
+
+In this guide, you can see examples of how to perform common write operations on
+an application configured to use the {+provider-long+}.
+
+.. tip::
+
+   To learn how to configure an application to use the {+provider-short+}, see
+   :ref:`entity-framework-configure`.
+
+Insert
+------
+
+You can use the ``Add()`` method to insert a single entity into your collection, 
+or you can use the ``AddRange()`` method to insert multiple entities at once. 
+
+Insert One Entity
+~~~~~~~~~~~~~~~~~
+
+The ``Add()`` method accepts a single entity of the same type that you
+specified on the ``DbSet`` instance that you are modifying.
+
+The following code uses the ``Add()`` method to add a new ``Planet`` object to
+the ``DbSet`` called ``Planets``. It then calls the ``SaveChanges()`` method to
+insert that entity into the MongoDB collection.
+
+.. literalinclude:: /includes/code-examples/quick-reference.cs
+   :start-after: // start-insert-one
+   :end-before: // end-insert-one
+   :language: csharp
+   :dedent:
+
+Insert Multiple Entities
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``AddRange()`` method accepts an array of entities that you want to add to the ``DbSet``. 
+
+The following code uses the ``AddRange()`` method to add an array of ``Planet``
+objects to the ``DbSet`` called ``Planets``. It then calls the ``SaveChanges()``
+method to insert those entities into the MongoDB collection.
+
+.. literalinclude:: /includes/code-examples/quick-reference.cs
+   :start-after: // start-insert-many
+   :end-before: // end-insert-many
+   :language: csharp
+   :dedent:
+
+Update
+------
+
+To update an entity, first retrieve the entity that you want to update. Then
+make the changes to that entity. The provider tracks any changes made to the entity, such as setting
+properties or adding and removing items from fields with list values. To save the update to
+MongoDB, call the ``SaveChanges()`` method. The {+provider-short+} compares the updated entity with a
+snapshot of the entity before the change and automatically updates the collection
+by using the MongoDB Query API.
+
+The following code retrieves an entity in which the ``name`` value is
+``"Mercury"``, then updates the ``name`` field. The code then calls the ``SaveChanges()``
+method to persist that change to the collection.
+
+.. literalinclude:: /includes/code-examples/quick-reference.cs
+   :start-after: // start-update-one
+   :end-before: // end-update-one
+   :language: csharp
+   :dedent:
+
+Delete
+------
+
+You can use the ``Remove()`` method to delete a single entity from your
+collection, or the ``RemoveRange()`` method to delete multiple entities at
+once.
+
+Delete One Entity
+~~~~~~~~~~~~~~~~~
+
+The ``Remove()`` method accepts a single entity of the same type that you
+specified on the ``DbSet`` instance that you are modifying.
+
+The following code removes a ``Planet`` entity in which the ``name`` value is
+``"Pluto"``. It then calls the ``SaveChanges()`` method to delete that entity from
+the MongoDB collection.
+
+.. literalinclude:: /includes/code-examples/quick-reference.cs
+   :start-after: // start-delete-one
+   :end-before: // end-delete-one
+   :language: csharp
+   :dedent:
+
+Delete Multiple Entities
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``RemoveRange()`` method accepts an array of entities to remove from the
+``DbSet``. 
+
+The following code finds two ``Planet`` entities and adds them to an array. It
+then uses the ``RemoveRange()`` method to remove both entities from the
+``DbSet``. Finally, it uses the ``SaveChanges()`` method to remove those
+entities from the MongoDB collection.
+
+.. literalinclude:: /includes/code-examples/quick-reference.cs
+   :start-after: // start-delete-many
+   :end-before: // end-delete-many
+   :language: csharp
+   :dedent:
+
+Additional Information
+----------------------
+
+To learn more about the methods discussed in this guide, see the following {+language-dotnet+} API
+documentation links:
+
+- `SaveChanges() <https://learn.microsoft.com/en-us/dotnet/api/microsoft.entityframeworkcore.dbcontext.saveChanges>`__
+- `Add() <https://learn.microsoft.com/en-us/dotnet/api/microsoft.entityframeworkcore.dbcontext.add>`__
+- `AddRange() <https://learn.microsoft.com/en-us/dotnet/api/microsoft.entityframeworkcore.dbcontext.addRange>`__
+- `Remove() <https://learn.microsoft.com/en-us/dotnet/api/microsoft.entityframeworkcore.dbcontext.remove>`__
+- `RemoveRange() <https://learn.microsoft.com/en-us/dotnet/api/microsoft.entityframeworkcore.dbcontext.removeRange>`__

source/includes/code-examples/quick-reference.cs

@@ -32,7 +32,13 @@ void FindMultiple()
 void InsertOne()
 {
     // start-insert-one
-    db.Planets.Add(new Planet() { name = "Pluto", hasRings = false, orderFromSun = 9 });
+    db.Planets.Add(new Planet()
+    {
+        name = "Pluto",
+        hasRings = false,
+        orderFromSun = 9
+    });
+
     db.SaveChanges();
     // end-insert-one
 }
@@ -42,8 +48,20 @@ void InsertMany()
     // start-insert-many
     var planets = new[]
     {
-        new Planet() { _id = ObjectId.GenerateNewId(), name = "Pluto", hasRings = false, orderFromSun = 9 },
-        new Planet() { _id = ObjectId.GenerateNewId(), name = "Scadrial", hasRings = false, orderFromSun = 10 }
+        new Planet()
+        {
+            _id = ObjectId.GenerateNewId(),
+            name = "Pluto",
+            hasRings = false,
+            orderFromSun = 9
+        },
+        new Planet()
+        {
+            _id = ObjectId.GenerateNewId(),
+            name = "Scadrial",
+            hasRings = false,
+            orderFromSun = 10
+        }
     };
 
     db.Planets.AddRange(planets);