Add reference for null conditional assignment (#45637)

* Add reference for null conditional assignment

Fixes #45610

Add language reference material for the null conditional assignment.

* Add links from Whats New in C#

Also, fix warnings.

* typo

* Apply suggestions from code review

Co-authored-by: Genevieve Warren <[email protected]>

---------

Co-authored-by: Genevieve Warren <[email protected]>

Author: BillWagner

docfx.json

@@ -58,7 +58,8 @@
                     "unbound-generic-types-in-nameof.md",
                     "first-class-span-types.md",
                     "simple-lambda-parameters-with-modifiers.md",
-                    "partial-events-and-constructors.md"
+                    "partial-events-and-constructors.md",
+                    "null-conditional-assignment.md"
                 ],
                 "src": "_csharplang/proposals",
                 "dest": "csharp/language-reference/proposals",
@@ -509,7 +510,7 @@
                 "_csharplang/proposals/csharp-11.0/*.md": "09/30/2022",
                 "_csharplang/proposals/csharp-12.0/*.md": "08/15/2023",
                 "_csharplang/proposals/csharp-13.0/*.md": "10/31/2024",
-                "_csharplang/proposals/*.md": "03/11/2025",
+                "_csharplang/proposals/*.md": "04/04/2025",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 7.md": "11/08/2022",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 8.md": "11/08/2023",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 9.md": "11/09/2024",
@@ -689,6 +690,7 @@
                 "_csharplang/proposals/first-class-span-types.md": "First-class span types",
                 "_csharplang/proposals/simple-lambda-parameters-with-modifiers.md": "Simple lambda parameters with modifiers",
                 "_csharplang/proposals/partial-events-and-constructors.md": "Partial events and constructors",
+                "_csharplang/proposals/null-conditional-assignment.md": "Null conditional assignment",
                 "_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",
@@ -812,8 +814,9 @@
                 "_csharplang/proposals/field-keyword.md": "This proposal introduces a new keyword, `field`, that accesses the compiler generated backing field in a property accessor.",
                 "_csharplang/proposals/unbound-generic-types-in-nameof.md": "This proposal introduces the ability to use unbound generic types such as `List<>` in `nameof` expressions. The type argument isn't required.",
                 "_csharplang/proposals/first-class-span-types.md": "This proposal provides several implicit conversions to `Span<T>` and `ReadOnlySpan<T>` that enable library authors to have fewer overloads and developers to write code that resolves to faster Span based APIs",
-                "_csharplang/proposals/simple-lambda-parameters-with-modifiers.md": "This proposal provides allows lambda parmaeters to be declared with modifiers without requiring their type names. You can add modifiers like `ref` and `out` to lambda parameters without specifying their type.",
-                "_csharplang/proposals/partial-events-and-constructors.md": "This proposal provides allows partial events and constructors to be declared in partial classes. This allows the event and constructor to be split across class declarations.",
+                "_csharplang/proposals/simple-lambda-parameters-with-modifiers.md": "This proposal allows lambda parameters to be declared with modifiers without requiring their type names. You can add modifiers like `ref` and `out` to lambda parameters without specifying their type.",
+                "_csharplang/proposals/partial-events-and-constructors.md": "This proposal allows partial events and constructors to be declared in partial classes. The event and constructor can be split across class declarations.",
+                "_csharplang/proposals/null-conditional-assignment.md": "This proposal allows the null conditional operator to be used for the destination of assignment expressions. This allows you to assign a value to a property or field only if the left side is not null.",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 7.md": "Learn about any breaking changes since the initial release of C# 10 and included in C# 11",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 8.md": "Learn about any breaking changes since the initial release of C# 11 and included in C# 12",
                 "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 9.md": "Learn about any breaking changes since the initial release of C# 12 and included in C# 13",

docs/csharp/language-reference/operators/assignment-operator.md

@@ -1,12 +1,11 @@
 ---
 title: "Assignment operators - assign an expression to a variable"
 description: "C# Assignment sets the value of the expression. Alternatively, `ref` assignment sets the reference of a reference variable."
-ms.date: 11/21/2024
+ms.date: 04/04/2025
 f1_keywords:
   - "=_CSharpKeyword"
 helpviewer_keywords:
   - "= operator [C#]"
-ms.assetid: d802a6d5-32f0-42b8-b180-12f5a081bfc1
 ---
 # Assignment operators (C# reference)
 
@@ -32,6 +31,8 @@ The left-hand operand of an assignment receives the *value* of the right-hand op
 
 This operation is called *value assignment*: the value is assigned.
 
+Beginning with C# 14, the left hand side of a value assignment can include a [null conditional member expression](./member-access-operators.md#null-conditional-operators--and-), such as `?.` or `?[]`. If the left hand side is null, the right hand side expression isn't evaluated.
+
 ## ref assignment
 
 *Ref assignment* `= ref` makes its left-hand operand an alias to the right-hand operand, as the following example demonstrates:
@@ -66,11 +67,11 @@ x = x op y
 
 Except that `x` is only evaluated once.
 
-The [arithmetic](arithmetic-operators.md#compound-assignment), [Boolean logical](boolean-logical-operators.md#compound-assignment), and [bitwise logical and shift](bitwise-and-shift-operators.md#compound-assignment) operators all support compount assignment.
+The [arithmetic](arithmetic-operators.md#compound-assignment), [Boolean logical](boolean-logical-operators.md#compound-assignment), and [bitwise logical and shift](bitwise-and-shift-operators.md#compound-assignment) operators all support compound assignment.
 
 ## Null-coalescing assignment
 
-You can use the null-coalescing assignment operator `??=` to assign the value of its right-hand operand to its left-hand operand only if the left-hand operand evaluates to `null`. For more information, see the [?? and ??= operators](null-coalescing-operator.md) article.
+You can use the null-coalescing assignment operator `??=` to assign the value of its right-hand operand to its left-hand operand only if the left-hand operand evaluates to `null`. For more information, see the [`??` and `??=` operators](null-coalescing-operator.md) article.
 
 ## Operator overloadability
 

docs/csharp/language-reference/operators/member-access-operators.md

@@ -1,7 +1,7 @@
 ---
 title: "Member access and null-conditional operators and expressions:"
 description: "C# operators that you use to access type members or null-conditionally access type members. These operators include the dot operator - `.`, indexers - `[`, `]`, `^` and `..`, and invocation - `(`, `)`."
-ms.date: 07/31/2024
+ms.date: 04/04/2025
 author: pkulikov
 f1_keywords:
   - "._CSharpKeyword"
@@ -35,7 +35,7 @@ helpviewer_keywords:
 ---
 # Member access operators and expressions - the dot, indexer, and invocation operators.
 
-You use several operators and expressions to access a type member. These operators include member access (`.`), array element or indexer access (`[]`), index-from-end (`^`), range (`..`), null-conditional operators (`?.` and `?[]`), and method invocation (`()`). These include the *null-conditional* member access (`?.`), and indexer access (`?[]`) operators.
+You use several operators and expressions to access a type member. Member access operators include member access (`.`), array element, or indexer access (`[]`), index-from-end (`^`), range (`..`), null-conditional operators (`?.` and `?[]`), and method invocation (`()`). These include the *null-conditional* member access (`?.`), and indexer access (`?[]`) operators.
 
 - [`.` (member access)](#member-access-expression-): to access a member of a namespace or a type
 - [`[]` (array element or indexer access)](#indexer-operator-): to access an array element or a type indexer
@@ -138,7 +138,7 @@ The following examples demonstrate the usage of the `?.` and `?[]` operators:
 :::code language="csharp" source="snippets/shared/MemberAccessOperators.cs" id="SnippetNullConditional" interactive="try-dotnet-method":::
 :::code language="csharp" source="snippets/shared/MemberAccessOperators2.cs" interactive="try-dotnet":::
 
-The first of the preceding two examples also uses the [null-coalescing operator `??`](null-coalescing-operator.md) to specify an alternative expression to evaluate in case the result of a null-conditional operation is `null`.
+The first preceding example also uses the [null-coalescing operator `??`](null-coalescing-operator.md) to specify an alternative expression to evaluate in case the result of a null-conditional operation is `null`.
 
 If `a.x` or `a[x]` is of a non-nullable value type `T`, `a?.x` or `a?[x]` is of the corresponding [nullable value type](../builtin-types/nullable-value-types.md) `T?`. If you need an expression of type `T`, apply the null-coalescing operator `??` to a null-conditional expression, as the following example shows:
 
@@ -147,9 +147,23 @@ If `a.x` or `a[x]` is of a non-nullable value type `T`, `a?.x` or `a?[x]` is of
 In the preceding example, if you don't use the `??` operator, `numbers?.Length < 2` evaluates to `false` when `numbers` is `null`.
 
 > [!NOTE]
-> The `?.` operator evaluates its left-hand operand no more than once, guaranteeing that it cannot be changed to `null` after being verified as non-null.
+> The `?.` operator evaluates its left-hand operand no more than once, guaranteeing that it can't be changed to `null` after being verified as non-null.
 
-The null-conditional member access operator `?.` is also known as the Elvis operator.
+Beginning in C# 14, assignment is permissible with a null conditional access expression (`?.` and `?[]`) on reference types. For example, see the following method:
+
+:::code language="csharp" source="snippets/shared/NullCoalescingOperator.cs" id="NullForgivingAssignment":::
+
+The preceding example shows assignment to a property and an indexed element on a reference type that might be null. An important behavior for this assignment is that the expression on the right-hand side of the `=` is evaluated only when the left-hand side is known to be non-null. For example, in the following code, the function `GenerateNextIndex` is called only when the `values` array isn't null. If the `values` array is null, `GenerateNextIndex` isn't called:
+
+:::code language="csharp" source="snippets/shared/NullCoalescingOperator.cs" id="NullForgivingAssignment":::
+
+In other words, the preceding code is equivalent to the following code using an `if` statement for the null check:
+
+:::code language="csharp" source="snippets/shared/NullCoalescingOperator.cs" id="EquivalentIfStatement":::
+
+In addition to assignment, any form of [compound assignment](./assignment-operator.md#compound-assignment), such as `+=` or `-=`, are allowed. However, increment (`++`) and decrement (`--`) aren't allowed.
+
+This enhancement doesn't classify a null conditional expression as a variable. It can't be `ref` assigned, nor can it be assigned to a `ref` variable or passed to a method as a `ref` or `out` argument.
 
 ### Thread-safe delegate invocation
 
@@ -175,7 +189,7 @@ The preceding example is a thread-safe way to ensure that only a non-null `handl
 
 Use parentheses, `()`, to call a [method](../../programming-guide/classes-and-structs/methods.md) or invoke a [delegate](../../programming-guide/delegates/index.md).
 
-The following example demonstrates how to call a method, with or without arguments, and invoke a delegate:
+The following code demonstrates how to call a method, with or without arguments, and invoke a delegate:
 
 :::code language="csharp" source="snippets/shared/MemberAccessOperators.cs" id="Invocation" interactive="try-dotnet-method":::
 

docs/csharp/language-reference/operators/null-coalescing-operator.md

@@ -1,7 +1,7 @@
 ---
 title: "?? and ??= operators - null-coalescing operators"
 description: "The `??` and `??=` operators are the C# null-coalescing operators. They return the value of the left-hand operand if it isn't null. Otherwise, they return the value of the right-hand operand"
-ms.date: 11/28/2022
+ms.date: 04/04/2025
 f1_keywords:
   - "??_CSharpKeyword"
   - "??=_CSharpKeyword"
@@ -10,7 +10,6 @@ helpviewer_keywords:
   - "?? operator [C#]"
   - "null-coalescing assignment [C#]"
   - "??= operator [C#]"
-ms.assetid: 088b1f0d-c1af-4fe1-b4b8-196fd5ea9132
 ---
 # ?? and ??= operators - the null-coalescing operators
 
@@ -20,13 +19,13 @@ ms.assetid: 088b1f0d-c1af-4fe1-b4b8-196fd5ea9132
 
 The null-coalescing operator `??` returns the value of its left-hand operand if it isn't `null`; otherwise, it evaluates the right-hand operand and returns its result. The `??` operator doesn't evaluate its right-hand operand if the left-hand operand evaluates to non-null. The null-coalescing assignment operator `??=` assigns the value of its right-hand operand to its left-hand operand only if the left-hand operand evaluates to `null`. The `??=` operator doesn't evaluate its right-hand operand if the left-hand operand evaluates to non-null.
 
-[!code-csharp[null-coalescing assignment](snippets/shared/NullCoalescingOperator.cs#Assignment)]
+:::code language="csharp" source="snippets/shared/NullCoalescingOperator.cs" id="Assignment":::
 
 The left-hand operand of the `??=` operator must be a variable, a [property](../../programming-guide/classes-and-structs/properties.md), or an [indexer](../../programming-guide/indexers/index.md) element.
 
 The type of the left-hand operand of the `??` and `??=` operators can't be a non-nullable value type. In particular, you can use the null-coalescing operators with unconstrained type parameters:
 
-[!code-csharp[unconstrained type parameter](snippets/shared/NullCoalescingOperator.cs#UnconstrainedType)]
+:::code language="csharp" source="snippets/shared/NullCoalescingOperator.cs" id="UnconstrainedType":::
 
 The null-coalescing operators are right-associative. That is, expressions of the form
 
@@ -48,17 +47,17 @@ The `??` and `??=` operators can be useful in the following scenarios:
 
 - In expressions with the [null-conditional operators `?.` and `?[]`](member-access-operators.md#null-conditional-operators--and-), you can use the `??` operator to provide an alternative expression to evaluate in case the result of the expression with null-conditional operations is `null`:
 
-  [!code-csharp-interactive[with null-conditional](snippets/shared/NullCoalescingOperator.cs#WithNullConditional)]
+  :::code language="csharp" source="snippets/shared/NullCoalescingOperator.cs" id="WithNullConditional" interactive="try-dotnet-method":::
 
 - When you work with [nullable value types](../builtin-types/nullable-value-types.md) and need to provide a value of an underlying value type, use the `??` operator to specify the value to provide in case a nullable type value is `null`:
 
-  [!code-csharp-interactive[with nullable types](snippets/shared/NullCoalescingOperator.cs#WithNullableTypes)]
+  :::code language="csharp" source="snippets/shared/NullCoalescingOperator.cs" id="WithNullableTypes" interactive="try-dotnet-method":::
 
   Use the <xref:System.Nullable%601.GetValueOrDefault?displayProperty=nameWithType> method if the value to be used when a nullable type value is `null` should be the default value of the underlying value type.
 
 - You can use a [`throw` expression](../statements/exception-handling-statements.md#the-throw-expression) as the right-hand operand of the `??` operator to make the argument-checking code more concise:
 
-  [!code-csharp[with throw expression](snippets/shared/NullCoalescingOperator.cs#WithThrowExpression)]
+  :::code language="csharp" source="snippets/shared/NullCoalescingOperator.cs" id="WithThrowExpression" interactive="try-dotnet-method":::
 
   The preceding example also demonstrates how to use [expression-bodied members](../../programming-guide/statements-expressions-operators/expression-bodied-members.md) to define a property.
 

docs/csharp/language-reference/operators/snippets/shared/NullCoalescingOperator.cs

@@ -1,4 +1,6 @@
-namespace operators;
+using System.Diagnostics.CodeAnalysis;
+
+namespace operators;
 
 public static class NullCoalescingOperator
 {
@@ -9,6 +11,35 @@ public static void Examples()
         NullCoalescingAssignment();
     }
 
+    public record class Human(string FirstName, string LastName)
+    {
+        public string FirstName { get; set; } = FirstName;
+    }
+    public static void AddMessageAtIndex()
+    {
+        List<string> messages = new List<string>(10);
+        Human person = new Human("First", "Last");
+        // <NullForgivingAssignment>
+        person?.FirstName = "Scott";
+        messages?[5] = "five";
+        // </NullForgivingAssignment>
+
+        int index = 0;
+        int[] values = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+
+        // <ConditionalRHS>
+        values?[2] = GenerateNextIndex();
+        int GenerateNextIndex() => index++;
+        // </ConditionalRHS>
+
+        // <EquivalentIfStatement>
+        if (values is not null)
+        {
+            values[2] = GenerateNextIndex();
+        }
+        // </EquivalentIfStatement>
+    }
+
     private static void WithNullConditional()
     {
         // <SnippetWithNullConditional>

docs/csharp/language-reference/operators/snippets/shared/operators.csproj

@@ -6,7 +6,6 @@
     <Nullable>enable</Nullable>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <ImplicitUsings>true</ImplicitUsings>
-    <NoWarn>7022</NoWarn>
     <LangVersion>preview</LangVersion>
   </PropertyGroup>
 

docs/csharp/specification/toc.yml

@@ -175,6 +175,8 @@ items:
       href: ../../../_csharplang/proposals/unbound-generic-types-in-nameof.md
     - name: Overload resolution priority
       href: ../../../_csharplang/proposals/csharp-13.0/overload-resolution-priority.md
+    - name: Null conditional assignment
+      href: ../../../_csharplang/proposals/null-conditional-assignment.md
   - name: Statements
     items:
     - name: Global using directive