diff --git a/standard/attributes.md b/standard/attributes.md index 21d681e30..436f09022 100644 --- a/standard/attributes.md +++ b/standard/attributes.md @@ -877,6 +877,8 @@ The code-analysis attributes are declared in namespace `System.Diagnostics.CodeA `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. @@ -1030,6 +1032,47 @@ Specifies that a non-nullable return value may be null. 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: +> +> +> ```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` ([§22.5.7.8](attributes.md#22578-the-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). diff --git a/standard/standard-library.md b/standard/standard-library.md index 29d0279cf..fbc808b37 100644 --- a/standard/standard-library.md +++ b/standard/standard-library.md @@ -614,6 +614,22 @@ namespace System.Runtime.CompilerServices 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)]