📝 Backing fields

docs/modeling/backing-field.rst

@@ -0,0 +1,45 @@
+.. include:: /_shared/rc1-notice.txt
+
+Backing Fields
+==============
+
+When a backing field is configured, EF will write directly to that field when materializing entity instances from the database (rather than using the property setter). This is useful when there is no property setter, or the setter contains logic that should not be executed when setting initial property values for existing entities being loaded from the database.
+
+.. caution::
+  The ``ChangeTracker`` has not yet been enabled to use backing fields when it needs to set the value of a property. This is only an issue for foreign key properties and generated properties - as the change tracker needs to propagate values into these properties. For these properties, a property setter must still be exposed.
+
+  `Issue #4461 <https://github.com/aspnet/EntityFramework/issues/4461>`_ is tracking enabling the ``ChangeTracker`` to write to backing fields for properties with no setter.
+
+.. contents:: In this article:
+  :depth: 2
+  :local:
+
+Conventions
+-----------
+
+By convention, the following fields will be discovered as backing fields for a given property (listed in precedence order):
+  * <propertyName> differing only by case
+  * _<propertyName>
+  * m_<propertyName>
+
+.. literalinclude:: configuring/sample/EFModeling.Conventions/Samples/BackingField.cs
+        :language: c#
+        :lines: 18-29
+        :emphasize-lines: 3,7-11
+        :linenos:
+
+Data Annotations
+----------------
+
+Backing fields cannot be configured with data annotations.
+
+Fluent API
+----------
+
+There is no top level API for configuring backing fields, but you can use the Fluent API to set annotations that are used to store backing field information.
+
+.. literalinclude:: configuring/sample/EFModeling.Configuring.FluentAPI/Samples/BackingField.cs
+        :language: c#
+        :lines: 5-23
+        :emphasize-lines: 7-9,15,18
+        :linenos:

docs/modeling/configuring/sample/EFModeling.Configuring.FluentAPI/EFModeling.Configuring.FluentAPI.csproj

@@ -118,6 +118,7 @@
     <Reference Include="System.Xml" />
   </ItemGroup>
   <ItemGroup>
+    <Compile Include="Samples\BackingField.cs" />
     <Compile Include="Samples\Timestamp.cs" />
     <Compile Include="Samples\InheritanceTphDiscriminator.cs" />
     <Compile Include="Samples\Relational\ComputedColumn.cs" />

docs/modeling/configuring/sample/EFModeling.Configuring.FluentAPI/Samples/BackingField.cs

@@ -0,0 +1,24 @@
+using Microsoft.Data.Entity;
+
+namespace EFModeling.Configuring.FluentAPI.Samples.BackingField
+{
+    class MyContext : DbContext
+    {
+        public DbSet<Blog> Blogs { get; set; }
+
+        protected override void OnModelCreating(ModelBuilder modelBuilder)
+        {
+            modelBuilder.Entity<Blog>()
+                .Property(b => b.Url)
+                .HasAnnotation("BackingField", "_blogUrl");
+        }
+    }
+
+    public class Blog
+    {
+        private string _blogUrl;
+
+        public int BlogId { get; set; }
+        public string Url => _blogUrl;
+    }
+}

docs/modeling/configuring/sample/EFModeling.Conventions/EFModeling.Conventions.csproj

@@ -120,6 +120,7 @@
   <ItemGroup>
     <Compile Include="Program.cs" />
     <Compile Include="Properties\AssemblyInfo.cs" />
+    <Compile Include="Samples\BackingField.cs" />
     <Compile Include="Samples\InheritanceModelBuilder.cs" />
     <Compile Include="Samples\InheritanceDbSets.cs" />
     <Compile Include="Samples\Relationships\NoForeignKey.cs" />

docs/modeling/configuring/sample/EFModeling.Conventions/Samples/BackingField.cs

@@ -0,0 +1,30 @@
+using Microsoft.Data.Entity;
+using System.Collections.Generic;
+
+namespace EFModeling.Conventions.Samples.BackingField
+{
+    class MyContext : DbContext
+    {
+        public DbSet<Blog> Blogs { get; set; }
+
+        protected override void OnModelCreating(ModelBuilder modelBuilder)
+        {
+            modelBuilder.Entity<Blog>()
+                .Property(b => b.Url)
+                .HasAnnotation("BackingField", "_blogUrl");
+        }
+    }
+
+    public class Blog
+    {
+        private string _url;
+
+        public int BlogId { get; set; }
+
+        public string Url
+        {
+            get { return _url; }
+            set { _url = value; }
+        }
+    }
+}

docs/modeling/index.rst

@@ -22,6 +22,7 @@ In this section you can find information about conventions and configuration for
    indexes
    alternate-keys
    inheritance
+   backing-field
    relational/index
 
 .. include:: /_shared/sample.txt