dotnet · BillWagner · Nov 22, 2024 · Jun 16, 2025
diff --git a/standard/attributes.md b/standard/attributes.md
@@ -877,6 +877,8 @@
 `MaybeNullWhen` ([§22.5.7.7](attributes.md#22577-the-maybenullwhen-attribute))  | A non-nullable argument may be null when the method returns the specified `bool` value.
 `NotNullWhen` ([§22.5.7.10](attributes.md#225710-the-notnullwhen-attribute))  | A nullable argument won’t be null when the method returns the specified `bool` value.
 `NotNullIfNotNull` ([§22.5.7.9](attributes.md#22579-the-notnullifnotnull-attribute))  | A return value isn’t null if the argument for the specified parameter isn’t null.
+`MemberNotNull` (§membernotnull-attribute)  | The listed member won’t be null when the method returns.
+`MemberNotNullWhen` (§membernotnullwhen-attribute)  | The listed member won’t be null when the method returns the specified `bool` value.
 `DoesNotReturn` ([§22.5.7.4](attributes.md#22574-the-doesnotreturn-attribute))  | This method never returns.
 `DoesNotReturnIf` ([§22.5.7.5](attributes.md#22575-the-doesnotreturnif-attribute))  | This method never returns if the associated `bool` parameter has the specified value.
 
@@ -981,11 +983,11 @@
 > #nullable enable
 > public class X
 > {
 >     private void ThrowIfNull([DoesNotReturnIf(true)] bool isNull, string argumentName)
 >     {
 >         if (!isNull)
 >         {
 >             throw new ArgumentException(argumentName, $"argument {argumentName} can't be null");
 >         }
 >     }
 >
@@ -1030,6 +1032,47 @@
 
 Specifies that a non-nullable argument may be `null` when the method returns the specified `bool` value. This is similar to the `MaybeNull` attribute ([§22.5.7.6](attributes.md#22576-the-maybenull-attribute)), but includes a parameter for the specified return value.
 
+#### §membernotnull-attribute The MemberNotNull attribute
+
+Specifies that the given member won’t be `null` when the method returns.
+
+> *Example*: A helper method may include the `MemberNotNull` attribute to list any fields that are assigned to a non-null value in that method. A compiler that analyzes constructors to determine whether all non-nullable reference fields have been initialized may then use this attribute to discover which fields have been set by those helper methods. Consider the following example:
+>
+> <!-- Example: {template:"standalone-lib", name:"MemberNotNullAttribute"} -->
+> ```csharp
+> #nullable enable
+> public class Container
+> {
+>     private string _uniqueIdentifier; // must be initialized.
+>     private string? _optionalMessage;
+>
+>     public Container()
+>     {
+>         Helper();
+>     }
+>
+>     public Container(string message)
+>     {
+>         Helper();
+>         _optionalMessage = message;
+>     }
+>
+>     [MemberNotNull(nameof(_uniqueIdentifier))]
+>     private void Helper()
+>     {
+>         _uniqueIdentifier = DateTime.Now.Ticks.ToString();
+>     }
+> }
+> ```
+>
+> Multiple field names may be given as arguments to the attribute’s constructor. *end example*
+
+#### §membernotnullwhen-attribute The MemberNotNullWhen attribute
+
+Specifies that the listed member won’t be `null` when the method returns the specified `bool` value.
+
+> *Example*: This attribute is like `MemberNotNull` (§membernotnull-attribute) except that `MemberNotNullWhen` takes a `bool` argument. `MemberNotNullWhen` is intended for use in situations in which a helper method returns a `bool` indicating whether it initialized fields. *end example*
+
 #### 22.5.7.8 The NotNull attribute
 
 Specifies that a nullable value will never be `null` if the method returns (rather than throwing).
@@ -1039,7 +1082,7 @@
 > <!-- Example: {template:"code-in-class-lib", name:"NotNullAttribute"} -->
 > ```csharp
 > #nullable enable
 > public static void ThrowWhenNull([NotNull] object? value, string valueExpression = "") =>
 >     _ = value ?? throw new ArgumentNullException(valueExpression);
 >
 > public static void LogMessage(string? message)

diff --git a/standard/standard-library.md b/standard/standard-library.md
@@ -177,7 +177,7 @@
    public class NullReferenceException : Exception
    {
        public NullReferenceException();
        public NullReferenceException(string message);
        public NullReferenceException(string message, Exception innerException);
    }

@@ -225,7 +225,7 @@
    public sealed class StackOverflowException : Exception
    {
        public StackOverflowException();
        public StackOverflowException(string message);
        public StackOverflowException(string message, Exception innerException);
    }

@@ -387,7 +387,7 @@
    public readonly ref struct ReadOnlySpan<T>
    {
        public int Length { get; }
        public ref readonly T this[int index] { get; }
    }

    public readonly ref struct Span<T>
@@ -553,7 +553,7 @@

    public readonly struct TaskAwaiter<TResult> : ICriticalNotifyCompletion,
        INotifyCompletion
    {
        public bool IsCompleted { get; }
        public TResult GetResult();
    }
@@ -614,6 +614,22 @@
         public MaybeNullWhenAttribute(bool returnValue) {}
     }
 
+    [System.AttributeUsage(System.AttributeTargets.Method | 
+    System.AttributeTargets.Property, AllowMultiple=true, Inherited=false)]
+    public sealed class MemberNotNullAttribute : Attribute
+    {
+        public MemberNotNullAttribute(string member) {}
+        public MemberNotNullAttribute(params string[] members) {}
+    }
+
+    [System.AttributeUsage(System.AttributeTargets.Method | 
+      System.AttributeTargets.Property, AllowMultiple=true, Inherited=false)]
+    public sealed class MemberNotNullWhenAttribute : Attribute
+    {
+        public MemberNotNullWhenAttribute(bool returnValue, string member) {}
+        public MemberNotNullWhenAttribute(bool returnValue, params string[] members) {}
+    }
+
     [System.AttributeUsage(System.AttributeTargets.Field |
       System.AttributeTargets.Parameter | System.AttributeTargets.Property | 
       System.AttributeTargets.ReturnValue, Inherited=false)]