Document AutoInclude

Resolves #3193

entity-framework/core/querying/related-data/eager.md

@@ -2,7 +2,7 @@
 title: Eager Loading of Related Data - EF Core
 description: Eager loading of related data with Entity Framework Core
 author: roji
-ms.date: 9/8/2020
+ms.date: 11/11/2021
 uid: core/querying/related-data/eager
 ---
 # Eager Loading of Related Data
@@ -120,22 +120,44 @@ public class School
 }
 ```
 
-Contents of `School` navigation of all People who are Students can be eagerly loaded using a number of patterns:
+Contents of `School` navigation of all People who are Students can be eagerly loaded using many patterns:
 
-* using cast
+* Using cast
 
   ```csharp
   context.People.Include(person => ((Student)person).School).ToList()
   ```
 
-* using `as` operator
+* Using `as` operator
 
   ```csharp
   context.People.Include(person => (person as Student).School).ToList()
   ```
 
-* using overload of `Include` that takes parameter of type `string`
+* Using overload of `Include` that takes parameter of type `string`
 
   ```csharp
   context.People.Include("School").ToList()
   ```
+
+## Model configuration for auto-including navigations
+
+> [!NOTE]
+> This feature was introduced in EF Core 6.0.
+
+You can configure a navigation in the model to be included every time the entity is loaded from the database using `AutoInclude` method. It has same effect as specifying `Include` with the navigation in every query where the entity type is returned in the results. Following example shows how to configure a navigation to be automatically included.
+
+[!code-csharp[Main](../../../../samples/core/Querying/RelatedData/BloggingContext.cs#AutoInclude)]
+
+After above configuration, running a query like below will load `ColorScheme` navigation for all the themes in the results.
+
+[!code-csharp[Main](../../../../samples/core/Querying/RelatedData/Program.cs#AutoIncludes)]
+
+This configuration is applied on every entity returned in the result no matter how it appeared in the results. That means if an entity is in the result because of use of a navigation, using `Include` over another entity type or auto-include configuration, it will load all the auto-included navigations for it. The same rule extends to the navigations configured as auto-included on derived type of the entity.
+
+If for a particular query you don't want to load the related data through a navigation, which is configured at model level to be auto-included, you can use `IgnoreAutoIncludes` method in your query. Using this method will stop loading all the navigations configured as auto-include by the user. Running a query like below will bring back all themes from database but won't load `ColorScheme` even though it's configured as auto-included navigation.
+
+[!code-csharp[Main](../../../../samples/core/Querying/RelatedData/Program.cs#IgnoreAutoIncludes)]
+
+> [!NOTE]
+> Navigations to owned types are also configured as auto-included by convention and using `IgnoreAutoIncludes` API doesn't stop them from being included. They will still be included in query results.

entity-framework/core/querying/related-data/explicit.md

@@ -11,15 +11,15 @@ uid: core/querying/related-data/explicit
 
 You can explicitly load a navigation property via the `DbContext.Entry(...)` API.
 
-[!code-csharp[Main](../../../../samples/core/Querying/RelatedData/Program.cs#Eager)]
+[!code-csharp[Main](../../../../samples/core/Querying/RelatedData/Program.cs#Explicit)]
 
 You can also explicitly load a navigation property by executing a separate query that returns the related entities. If change tracking is enabled, then when query materializes an entity, EF Core will automatically set the navigation properties of the newly loaded entity to refer to any entities already loaded, and set the navigation properties of the already-loaded entities to refer to the newly loaded entity.
 
 ## Querying related entities
 
 You can also get a LINQ query that represents the contents of a navigation property.
 
-It allows you to apply additional operators over the query. For example applying an aggregate operator over the related entities without loading them into memory.
+It allows you to apply other operators over the query. For example, applying an aggregate operator over the related entities without loading them into memory.
 
 [!code-csharp[Main](../../../../samples/core/Querying/RelatedData/Program.cs#NavQueryAggregate)]
 

samples/core/Querying/RelatedData/Blog.cs

@@ -12,5 +12,8 @@ public class Blog
 
         public int OwnerId { get; set; }
         public Person Owner { get; set; }
+
+        public int ThemeId { get; set; }
+        public Theme Theme { get; set; }
     }
 }

samples/core/Querying/RelatedData/BloggingContext.cs

@@ -6,6 +6,7 @@ public class BloggingContext : DbContext
     {
         public DbSet<Blog> Blogs { get; set; }
         public DbSet<Post> Posts { get; set; }
+        public DbSet<Theme> Themes { get; set; }
 
         protected override void OnModelCreating(ModelBuilder modelBuilder)
         {
@@ -24,13 +25,21 @@ protected override void OnModelCreating(ModelBuilder modelBuilder)
                 .WithMany(t => t.Posts)
                 .HasForeignKey(pt => pt.TagId);
 
+            #region AutoInclude
+            modelBuilder.Entity<Theme>().Navigation(e => e.ColorScheme).AutoInclude();
+            #endregion
+
             modelBuilder.Entity<Blog>()
                 .HasData(
                     new Blog
                     {
-                        BlogId = 1, Url = @"https://devblogs.microsoft.com/dotnet", Rating = 5, OwnerId = 1,
+                        BlogId = 1,
+                        Url = @"https://devblogs.microsoft.com/dotnet",
+                        Rating = 5,
+                        OwnerId = 1,
+                        ThemeId = 1
                     },
-                    new Blog { BlogId = 2, Url = @"https://mytravelblog.com/", Rating = 4, OwnerId = 3 });
+                    new Blog { BlogId = 2, Url = @"https://mytravelblog.com/", Rating = 4, OwnerId = 3, ThemeId = 1 });
 
             modelBuilder.Entity<Post>()
                 .HasData(
@@ -98,6 +107,16 @@ protected override void OnModelCreating(ModelBuilder modelBuilder)
                     new PostTag { PostTagId = 4, PostId = 3, TagId = "opinion" },
                     new PostTag { PostTagId = 5, PostId = 4, TagId = "opinion" },
                     new PostTag { PostTagId = 6, PostId = 4, TagId = "informative" });
+
+            modelBuilder.Entity<ColorScheme>()
+                .HasData(
+                    new ColorScheme { Id = 1, Background = "FFFFFF", HighlightColor = "00FF00" }
+                );
+
+            modelBuilder.Entity<Theme>()
+                .HasData(
+                    new Theme { Id = 1, ColorSchemeId = 1 }
+                );
         }
 
         protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)

samples/core/Querying/RelatedData/ColorScheme.cs

@@ -0,0 +1,9 @@
+namespace EFQuerying.RelatedData
+{
+    public class ColorScheme
+    {
+        public int Id { get; set; }
+        public string Background { get; set; }
+        public string HighlightColor { get; set; }
+    }
+}

samples/core/Querying/RelatedData/Program.cs

@@ -134,7 +134,7 @@ private static void Main(string[] args)
             }
             #endregion
 
-            #region Eager
+            #region Explicit
             using (var context = new BloggingContext())
             {
                 var blog = context.Blogs
@@ -213,6 +213,22 @@ private static void Main(string[] args)
                     .ToList();
             }
             #endregion
+
+            #region AutoIncludes
+            using (var context = new BloggingContext())
+            {
+                var themes = context.Themes.ToList();
+            }
+
+            #endregion
+
+            #region IgnoreAutoIncludes
+            using (var context = new BloggingContext())
+            {
+                var themes = context.Themes.IgnoreAutoIncludes().ToList();
+            }
+
+            #endregion
         }
     }
 }

samples/core/Querying/RelatedData/Theme.cs

@@ -0,0 +1,10 @@
+namespace EFQuerying.RelatedData
+{
+    public class Theme
+    {
+        public int Id { get; set; }
+
+        public int ColorSchemeId { get; set; }
+        public ColorScheme ColorScheme { get; set; }
+    }
+}