Finish conceptual docs

BillWagner · BillWagner · commit 9b541c97ab0c · 2024-10-31T16:54:13.000-04:00
diff --git a/docfx.json b/docfx.json
@@ -492,7 +492,7 @@
                 "_csharplang/proposals/csharp-10.0/*.md": "08/07/2021",
                 "_csharplang/proposals/csharp-11.0/*.md": "09/30/2022",
                 "_csharplang/proposals/csharp-12.0/*.md": "08/15/2023",
-                "_csharplang/proposals/*.md": "08/30/2024",
+                "_csharplang/proposals/*.md": "10/31/2024",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 7.md": "11/08/2022",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 8.md": "09/26/2023",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 9.md": "06/26/2024",
@@ -669,6 +669,7 @@
                 "_csharplang/proposals/csharp-13.0/ref-struct-interfaces.md": "Allow ref struct types to implement some interfaces",
                 "_csharplang/proposals/csharp-13.0/partial-properties.md": "All partial properties and indexers",
                 "_csharplang/proposals/csharp-13.0/overload-resolution-priority.md": "Overload resolution priority tiebreaker attribute",
+                "_csharplang/proposals/field-keyword.md": "The `field` contextual keyword",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 7.md": "C# compiler breaking changes since C# 10",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 8.md": "C# compiler breaking changes since C# 11",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 9.md": "C# compiler breaking changes since C# 12",
@@ -791,6 +792,7 @@
                 "_csharplang/proposals/csharp-13.0/ref-struct-interfaces.md": "This proposal provides features that enable interface authors to allow `ref struct` types to implement a particular interface",
                 "_csharplang/proposals/csharp-13.0/partial-properties.md": "This proposal provides for partial properties and indexers, allowing the definition of a property or indexer to be split across multiple parts.",
                 "_csharplang/proposals/csharp-13.0/overload-resolution-priority.md": "This proposal introduces a new attribute, `OverloadResolutionPriorityAttribute`, that can be applied to methods to influence overload resolution.",
+                "_csharplang/proposals/field-keyword.md": "This proposal introduces a new keyword, `field`, that accesses the compiler generated backing field in a property accessor.",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 7.md": "Learn about any breaking changes since the initial release of C# 10",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 8.md": "Learn about any breaking changes since the initial release of C# 11",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 9.md": "Learn about any breaking changes since the initial release of C# 12",
@@ -816,6 +818,7 @@
                 "_csharplang/proposals/csharp-10.0/*.md": "C# feature specifications",
                 "_csharplang/proposals/csharp-11.0/*.md": "C# feature specifications",
                 "_csharplang/proposals/csharp-12.0/*.md": "C# feature specifications",
+                "_csharplang/proposals/csharp-13.0/*.md": "C# feature specifications",
                 "_csharplang/proposals/*.md": "C# feature specifications (preview)",
                 "docs/framework/**/*.md": ".NET Framework",
                 "docs/framework/data/adonet/**/*.md": "ADO.NET",
diff --git a/docs/csharp/includes/field-preview.md b/docs/csharp/includes/field-preview.md
@@ -8,3 +8,5 @@ ms.date: 10/30/2024
 > [!IMPORTANT]
 >
 > The `field` keyword is a preview feature in C# 13. You must be using .NET 9 and set your `<LangVersion>` element to `preview` in your project file in order to use the `field` contextual keyword.
+>
+> You should be careful using the `field` keyword feature in a class that has a field named `field`. The new `field` keyword shadows a field named `field` in the scope of a property accessor. You can either change the name of the `field` variable, or use the `@` token to reference the `field` identifier as `@field`. You can learn more by reading the feature specification for [the `field` keyword](~/_csharplang/proposals/field-keyword.md).
diff --git a/docs/csharp/programming-guide/classes-and-structs/auto-implemented-properties.md b/docs/csharp/programming-guide/classes-and-structs/auto-implemented-properties.md
@@ -12,13 +12,11 @@ helpviewer_keywords:
 
 Automatically implemented properties make property-declaration more concise when no other logic is required in the property accessors. They also enable client code to create objects. When you declare a property as shown in the following example, the compiler creates a private, anonymous backing field that can only be accessed through the property's `get` and `set` accessors. `init` accessors can also be declared as automatically implemented properties.
 
-## Example
-
 The following example shows a simple class that has some automatically implemented properties:
 
 :::code language="csharp" source="./snippets/properties/AutoImplemented.cs" id="Snippet28":::
 
-You can't declare automatically implemented properties in interfaces. Automatically implemented properties declare a private instance backing field, and interfaces can't declare instance fields. Declaring a property in an interface without defining a body declares a property with accessors that must be implemented by each type that implements that interface.
+You can't declare automatically implemented properties in interfaces. Automatically implemented and field backed properties declare a private instance backing field, and interfaces can't declare instance fields. Declaring a property in an interface without defining a body declares a property with accessors. Each type that implements that interface must implement that property.
 
 You can initialize automatically implemented properties similarly to fields:
 
@@ -34,7 +32,24 @@ The class that is shown in the previous example is mutable. Client code can chan
 
 For more information, see [How to implement a lightweight class with automatically implemented properties](./how-to-implement-a-lightweight-class-with-auto-implemented-properties.md).
 
-TODO: Add `field` backed properties to make the slope smooth.
+You might need to add validation to an automatically implemented property. C# 13 adds [field backed properties](../../language-reference/keywords/field.md) as a preview feature. You use the `field` keyword to access the compiler generated backing field of an automatically implemented property. For example, you could ensure that the `FirstName` property in the preceding example can't be set to `null` or the empty string:
+
+```csharp
+public string FirstName 
+{ 
+    get; 
+    set 
+    { 
+        field = ((string.IsNullOrWhiteSpace(value) == false) 
+            ? value
+            : throw new ArgumentException(nameof(value), "First name can't be whitespace or null"));
+    }
+} = "Jane";
+```
+
+This feature enables you to add logic to accessors without requiring you to explicitly declare the backing field. You use the `field` keyword to access the backing field generated by the compiler.
+
+[!INCLUDE[field-preview](../../includes/field-preview.md)]
 
 ## See also
 
diff --git a/docs/csharp/programming-guide/classes-and-structs/partial-classes-and-methods.md b/docs/csharp/programming-guide/classes-and-structs/partial-classes-and-methods.md
@@ -1,7 +1,7 @@
 ---
 title: "Partial Classes and Methods"
 description: Partial classes and methods in C# split the definition of a class, a struct, an interface, or a method over two or more source files.
-ms.date: 08/20/2024
+ms.date: 10/31/2024
 helpviewer_keywords:
   - "partial methods [C#]"
   - "partial classes [C#]"
@@ -116,6 +116,14 @@ The method and all calls to the method are removed at compile time when there's
 
 Any method that doesn't conform to all those restrictions, including properties and indexers, must provide an implementation. That implementation might be supplied by a *source generator*. [Partial properties](../../language-reference/keywords/partial-member.md) can't be implemented using automatically implemented properties. The compiler can't distinguish between an automatically implemented property, and the declaring declaration of a partial property.
 
+Beginning with C# 13, the implementing declaration for a partial property can use [field backed properties](../../language-reference/keywords/field.md) to define the implementing declaration. A field backed property provides a concise syntax where the `field` keyword accesses the compiler generated backing field for the property. For example, you could write the following:
+
+:::code language="csharp" source="snippets/partial-classes-and-methods/Program.cs" id="FieldProperty":::
+
+You can use `field` in either the `get` or `set` accessor, or both.
+
+[!INCLUDE[field-preview](../../includes/field-preview.md)]
+
 Partial methods enable the implementer of one part of a class to declare a member. The implementer of another part of the class can define that member. There are two scenarios where this separation is useful: templates that generate boilerplate code, and source generators.
 
 - **Template code**: The template reserves a method name and signature so that generated code can call the method. These methods follow the restrictions that enable a developer to decide whether to implement the method. If the method isn't implemented, then the compiler removes the method signature and all calls to the method. The calls to the method, including any results that would occur from evaluation of arguments in the calls, have no effect at run time. Therefore, any code in the partial class can freely use a partial method, even if the implementation isn't supplied. No compile-time or run-time errors result if the method is called but not implemented.
@@ -140,7 +148,7 @@ partial void OnNameChanged()
 
 ## C# Language Specification
 
-For more information, see [Partial types](~/_csharpstandard/standard/classes.md#1527-partial-declarations) and [Partial methods](~/_csharpstandard/standard/classes.md#1569-partial-methods) in the [C# Language Specification](~/_csharpstandard/standard/README.md). The language specification is the definitive source for C# syntax and usage. The additional features for partial methods are defined in the [feature specification](~/_csharplang/proposals/csharp-9.0/extending-partial-methods.md).
+For more information, see [Partial types](~/_csharpstandard/standard/classes.md#1527-partial-declarations) and [Partial methods](~/_csharpstandard/standard/classes.md#1569-partial-methods) in the [C# Language Specification](~/_csharpstandard/standard/README.md). The language specification is the definitive source for C# syntax and usage. The new features for partial methods are defined in the [feature specification](~/_csharplang/proposals/csharp-9.0/extending-partial-methods.md).
 
 ## See also
 
diff --git a/docs/csharp/programming-guide/classes-and-structs/properties.md b/docs/csharp/programming-guide/classes-and-structs/properties.md
@@ -26,6 +26,14 @@ You can initialize a property to a value other than the default by setting a val
 
 :::code language="csharp" source="./snippets/properties/Person.cs" id="Initializer":::
 
+## Field backed properties
+
+In C# 13, you can add validation or other logic in the accessor for a property using the [`field`](../../language-reference/keywords/field.md) keyword preview feature. The `field` keyword accesses the compiler generated backing field for a property. It enables you to write a property accessor without explicitly declaring a separate backing field.
+
+:::code language="csharp" source="./snippets/properties/Person.cs" id="FieldBackedProperty":::
+
+[!INCLUDE[field-preview](../../includes/field-preview.md)]
+
 ## Required properties
 
 The preceding example allows a caller to create a `Person` using the default constructor, without setting the `FirstName` property. The property changed type to a *nullable* string. Beginning in C# 11, you can *require* callers to set a property:
@@ -39,10 +47,6 @@ The preceding code makes two changes to the `Person` class. First, the `FirstNam
 
 :::code language="csharp" source="./snippets/properties/Program.cs" id="SnippetInitialize":::
 
-## Field backed properties
-
-TODO:  `field` discussion
-
 ## Expression body definitions
 
 Property accessors often consist of single-line statements. The accessors assign or return the result of an expression. You can implement these properties as expression-bodied members. Expression body definitions consist of the `=>` token followed by the expression to assign to or retrieve from the property.
diff --git a/docs/csharp/programming-guide/classes-and-structs/snippets/partial-classes-and-methods/PartialClassesAndMethods.csproj b/docs/csharp/programming-guide/classes-and-structs/snippets/partial-classes-and-methods/PartialClassesAndMethods.csproj
@@ -2,11 +2,12 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net8.0</TargetFramework>
+    <TargetFramework>net9.0</TargetFramework>
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
     <RootNamespace>PartialClassesAndMethods</RootNamespace>
     <StartupObject>WrapCoords2.TestCoords</StartupObject>
+    <LangVersion>preview</LangVersion>
   </PropertyGroup>
 
 </Project>
diff --git a/docs/csharp/programming-guide/classes-and-structs/snippets/partial-classes-and-methods/Program.cs b/docs/csharp/programming-guide/classes-and-structs/snippets/partial-classes-and-methods/Program.cs
@@ -165,3 +165,20 @@ partial struct S1
     void Struct_Test2() { }
 }
 //</Snippet10>
+
+// <FieldProperty>
+// in file1.cs
+public partial class Container
+{
+    // Defining declaration
+    public int MyProperty { get; set; }
+}
+
+// In file2.cs
+public partial class Container
+{
+    // Defining declaration
+    public int MyProperty { get => field; set; }
+}
+
+// </FieldProperty>
diff --git a/docs/csharp/programming-guide/classes-and-structs/snippets/properties/Person.cs b/docs/csharp/programming-guide/classes-and-structs/snippets/properties/Person.cs
@@ -24,6 +24,22 @@ public class Person
     // </AutoImplemented>
 }
 
+namespace VersionTwoPointFive
+{
+    // <FieldBackedProperty>
+    public class Person
+    {
+        public string? FirstName 
+        { 
+            get;
+            set => field = value.Trim(); 
+        }
+
+        // Omitted for brevity.
+    }
+    // </FieldBackedProperty>
+}
+
 namespace VersionThree
 {
     // <Initializer>
diff --git a/docs/csharp/programming-guide/classes-and-structs/snippets/properties/TimePeriod.cs b/docs/csharp/programming-guide/classes-and-structs/snippets/properties/TimePeriod.cs
@@ -18,3 +18,20 @@ public int Month
     }
 }
 //</UsingExample>
+
+//<FieldExample>
+public class DateExample
+{
+    public int Month
+    {
+        get;
+        set
+        {
+            if ((value > 0) && (value < 13))
+            {
+                field = value;
+            }
+        }
+    }
+}
+//</FieldExample>
diff --git a/docs/csharp/programming-guide/classes-and-structs/snippets/properties/properties.csproj b/docs/csharp/programming-guide/classes-and-structs/snippets/properties/properties.csproj
@@ -2,9 +2,10 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net8.0</TargetFramework>
+    <TargetFramework>net9.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
+    <LangVersion>preview</LangVersion>
   </PropertyGroup>
 
 </Project>
diff --git a/docs/csharp/programming-guide/classes-and-structs/using-properties.md b/docs/csharp/programming-guide/classes-and-structs/using-properties.md
@@ -1,7 +1,7 @@
 ---
 title: "Using Properties"
 description: These examples illustrate using properties in C#. See how the get and set accessors implement read and write access and find out about uses for properties.
-ms.date: 10/30/2024
+ms.date: 10/31/2024
 helpviewer_keywords: 
   - "set accessor [C#]"
   - "get accessor [C#]"
@@ -25,6 +25,12 @@ Properties are declared in the class block by specifying the access level of the
 
 In this example, `Month` is declared as a property so that the `set` accessor can make sure that the `Month` value is set between 1 and 12. The `Month` property uses a private field to track the actual value. The real location of a property's data is often referred to as the property's "backing store." It's common for properties to use private fields as a backing store. The field is marked private in order to make sure that it can only be changed by calling the property. For more information about public and private access restrictions, see [Access Modifiers](./access-modifiers.md). Automatically implemented properties provide simplified syntax for simple property declarations. For more information, see [Automatically implemented properties](auto-implemented-properties.md).
 
+Beginning with C# 13, you can use [field backed properties](../../language-reference/keywords/field.md) to add validation to the `set` accessor of an automatically implemented property, as shown in the following example:
+
+:::code language="csharp" source="./snippets/properties/TimePeriod.cs" id="FieldExample":::
+
+[!INCLUDE[field-preview](../../includes/field-preview.md)]
+
 ## The get accessor
 
 The body of the `get` accessor resembles that of a method. It must return a value of the property type. The C# compiler and Just-in-time (JIT) compiler detect common patterns for implementing the `get` accessor, and optimizes those patterns. For example, a `get` accessor that returns a field without performing any computation is likely optimized to a memory read of that field. Automatically mplemented properties follow this pattern and benefit from these optimizations. However, a virtual `get` accessor method can't be inlined because the compiler doesn't know at compile time which method might actually be called at run time. The following example shows a `get` accessor that returns the value of a private field `_name`:
@@ -38,7 +44,8 @@ When you reference the property, except as the target of an assignment, the `get
 The `get` accessor must be an expression-bodied member, or end in a [return](../../language-reference/statements/jump-statements.md#the-return-statement) or [throw](../../language-reference/statements/exception-handling-statements.md#the-throw-statement) statement, and control can't flow off the accessor body.
 
 > [!WARNING]
-> It's a bad programming style to change the state of the object by using the `get` accessor.
+>
+> It's generally a bad programming style to change the state of the object by using the `get` accessor. One exception to this rule is a *lazy evaluated* property, where the value of a property is computed only when it's first accessed.
 
 The `get` accessor can be used to return the field value or to compute it and return it. For example:
 
diff --git a/docs/csharp/specification/toc.yml b/docs/csharp/specification/toc.yml
@@ -201,6 +201,8 @@ items:
       href: ../../../_csharplang/proposals/csharp-9.0/extending-partial-methods.md
     - name: Partial properties
       href: ../../../_csharplang/proposals/csharp-13.0/partial-properties.md
+    - name: Field backed properties (preview)
+      href: ../../../_csharplang/proposals/field-keyword.md
     - name: Covariant return types
       href: ../../../_csharplang/proposals/csharp-9.0/covariant-returns.md
     - name: Primary constructors
diff --git a/docs/csharp/whats-new/csharp-13.md b/docs/csharp/whats-new/csharp-13.md

Original file line number	Diff line number	Diff line change
`@@ -8,3 +8,5 @@ ms.date: 10/30/2024`
`8`	`8`	`> [!IMPORTANT]`
`9`	`9`	`>`
`10`	`10`	> The `field` keyword is a preview feature in C# 13. You must be using .NET 9 and set your `<LangVersion>` element to `preview` in your project file in order to use the `field` contextual keyword.
	`11`	`+>`
	`12`	+> You should be careful using the `field` keyword feature in a class that has a field named `field`. The new `field` keyword shadows a field named `field` in the scope of a property accessor. You can either change the name of the `field` variable, or use the `@` token to reference the `field` identifier as `@field`. You can learn more by reading the feature specification for [the `field` keyword](~/_csharplang/proposals/field-keyword.md).