From 2534573e0081ba69b579572b41a31de6dab8a001 Mon Sep 17 00:00:00 2001
From: Stephanie <52582720+stephmarie17@users.noreply.github.com>
Date: Wed, 22 Jan 2025 13:35:43 -0800
Subject: [PATCH] DOCSP-46303 Update replace documents (#406)

(cherry picked from commit a9ad799631a39700a0fc29b539f8016c8d9cfd11)
---
 .../crud/write-operations/replace.txt         | 22 +++++++++++++++++--
 .../code-examples/replace-one/ReplaceOne.cs   | 10 +++++++++
 .../replace-one/ReplaceOneAsync.cs            | 12 +++++++++-
 3 files changed, 41 insertions(+), 3 deletions(-)

diff --git a/source/fundamentals/crud/write-operations/replace.txt b/source/fundamentals/crud/write-operations/replace.txt
index e64af0d9..34ef27e0 100644
--- a/source/fundamentals/crud/write-operations/replace.txt
+++ b/source/fundamentals/crud/write-operations/replace.txt
@@ -109,8 +109,26 @@ corresponding code.
 
 .. important::
 
-   The values of ``_id`` fields are immutable. If your replacement document specifies 
-   a value for the ``_id`` field, it must match the ``_id`` value of the existing document.
+   The values of ``_id`` fields are immutable. If your replacement document
+   specifies a value for the ``_id`` field, it must match the ``_id`` value of
+   the existing document. 
+   
+   If your replacement document does not specify a value for the ``_id`` field,
+   you can add the ``[BsonIgnoreIfDefault]`` attribute to the ``_id`` field in
+   your Plain Old CLR/Class Object (POCO). Use ``[BsonIgnoreIfDefault]`` if the
+   ``_id`` field in your POCO is of the ``ObjectId`` type.
+   
+   The following example shows how to add this attribute:
+
+   .. code-block:: csharp
+
+      public class Restaurant
+      {
+          [BsonIgnoreIfDefault]
+          public ObjectId Id { get; set; }
+
+          // Other properties
+      }
 
 Customize the Replace Operation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/source/includes/code-examples/replace-one/ReplaceOne.cs b/source/includes/code-examples/replace-one/ReplaceOne.cs
index 4f37ae43..7cd7efa9 100644
--- a/source/includes/code-examples/replace-one/ReplaceOne.cs
+++ b/source/includes/code-examples/replace-one/ReplaceOne.cs
@@ -52,9 +52,14 @@ private static ReplaceOneResult ReplaceOneRestaurant()
         var filter = Builders<Restaurant>.Filter
             .Eq(r => r.Cuisine, "Pizza");
 
+        // Finds the ID of the first restaurant document that matches the filter
+        var oldPizzaRestaurant = _restaurantsCollection.Find(filter).First();
+        var oldId = oldPizzaRestaurant.Id;
+
         // Generates a new restaurant document
         Restaurant newPizzaRestaurant = new()
         {
+            Id = oldId
             Name = "Mongo's Pizza",
             Cuisine = "Pizza",
             Address = new Address()
@@ -77,9 +82,14 @@ private static ReplaceOneResult ReplaceOneRestaurantWithOptions()
         var filter = Builders<Restaurant>.Filter
             .Eq(r => r.Cuisine, "Pizza");
 
+        // Finds the ID of the first restaurant document that matches the filter
+        var oldPizzaRestaurant = _restaurantsCollection.Find(filter).First();
+        var oldId = oldPizzaRestaurant.Id;
+
         // Generates a new restaurant document
         Restaurant newPizzaRestaurant = new()
         {
+            Id = oldId
             Name = "Mongo's Pizza",
             Cuisine = "Pizza",
             Address = new Address()
diff --git a/source/includes/code-examples/replace-one/ReplaceOneAsync.cs b/source/includes/code-examples/replace-one/ReplaceOneAsync.cs
index e3e79743..f8bc1a00 100644
--- a/source/includes/code-examples/replace-one/ReplaceOneAsync.cs
+++ b/source/includes/code-examples/replace-one/ReplaceOneAsync.cs
@@ -51,10 +51,15 @@ private static async Task<ReplaceOneResult> ReplaceOneRestaurantAsync()
         // Creates a filter for all restaurant documents that have a "cuisine" value of "Pizza"
         var filter = Builders<Restaurant>.Filter
             .Eq(r => r.Cuisine, "Pizza");
+        
+        // Finds the ID of the first restaurant document that matches the filter
+        var oldPizzaRestaurant = _restaurantsCollection.Find(filter).First();
+        var oldId = oldPizzaRestaurant.Id;
 
         // Generates a new restaurant document
         Restaurant newPizzaRestaurant = new()
-        {
+        {   
+            Id = oldId
             Name = "Mongo's Pizza",
             Cuisine = "Pizza",
             Address = new Address()
@@ -76,9 +81,14 @@ private static async Task<ReplaceOneResult> ReplaceOneRestaurantAsyncWithOptions
         var filter = Builders<Restaurant>.Filter
             .Eq(r => r.Cuisine, "Pizza");
 
+        // Finds the ID of the first restaurant document that matches the filter
+        var oldPizzaRestaurant = _restaurantsCollection.Find(filter).First();
+        var oldId = oldPizzaRestaurant.Id;
+
         // Generates a new restaurant document
         Restaurant newPizzaRestaurant = new()
         {
+            Id = oldId
             Name = "Mongo's Pizza",
             Cuisine = "Pizza",
             Address = new Address()