Attributes for null-state static analysis interpreted by the C# compiler
In a nullable enabled context, the compiler performs static analysis of code to determine the null-state of all reference type variables:
- not-null: Static analysis determines that a variable has a non-null value.
- maybe-null: Static analysis can't determine that a variable is assigned a non-null value.
These states enable the compiler to provide warnings when you may dereference a null value, throwing a System.NullReferenceException. These attributes provide the compiler with semantic information about the null-state of arguments, return values, and object members based on the state of arguments and return values. The compiler provides more accurate warnings when your APIs have been properly annotated with this semantic information.
This article provides a brief description of each of the nullable reference type attributes and how to use them.
Let's start with an example. Imagine your library has the following API to retrieve a resource string. This method was originally compiled in a nullable oblivious context:
bool TryGetMessage(string key, out string message)
{
if (_messageMap.ContainsKey(key))
message = _messageMap[key];
else
message = null;
return message != null;
}
The preceding example follows the familiar Try*
pattern in .NET. There are two reference parameters for this API: the key
and the message
. This API has the following rules relating to the null-state of these parameters:
- Callers shouldn't pass
null
as the argument forkey
. - Callers can pass a variable whose value is
null
as the argument formessage
. - If the
TryGetMessage
method returnstrue
, the value ofmessage
isn't null. If the return value isfalse
, the value ofmessage
is null.
The rule for key
can be expressed succinctly: key
should be a non-nullable reference type. The message
parameter is more complex. It allows a variable that is null
as the argument, but guarantees, on success, that the out
argument isn't null
. For these scenarios, you need a richer vocabulary to describe the expectations. The NotNullWhen
attribute, described below describes the null-state for the argument used for the message
parameter.
Note
Adding these attributes gives the compiler more information about the rules for your API. When calling code is compiled in a nullable enabled context, the compiler will warn callers when they violate those rules. These attributes don't enable more checks on your implementation.
Attribute | Category | Meaning |
---|---|---|
AllowNull | Precondition | A non-nullable parameter, field, or property may be null. |
DisallowNull | Precondition | A nullable parameter, field, or property should never be null. |
MaybeNull | Postcondition | A non-nullable parameter, field, property, or return value may be null. |
NotNull | Postcondition | A nullable parameter, field, property, or return value will never be null. |
MaybeNullWhen | Conditional postcondition | A non-nullable argument may be null when the method returns the specified bool value. |
NotNullWhen | Conditional postcondition | A nullable argument won't be null when the method returns the specified bool value. |
NotNullIfNotNull | Conditional postcondition | A return value, property, or argument isn't null if the argument for the specified parameter isn't null. |
MemberNotNull | Method and property helper methods | The listed member won't be null when the method returns. |
MemberNotNullWhen | Method and property helper methods | The listed member won't be null when the method returns the specified bool value. |
DoesNotReturn | Unreachable code | A method or property never returns. In other words, it always throws an exception. |
DoesNotReturnIf | Unreachable code | This method or property never returns if the associated bool parameter has the specified value. |
The preceding descriptions are a quick reference to what each attribute does. The following sections describe the behavior and meaning of these attributes more thoroughly.
Consider a read/write property that never returns null
because it has a reasonable default value. Callers pass null
to the set accessor when setting it to that default value. For example, consider a messaging system that asks for a screen name in a chat room. If none is provided, the system generates a random name:
public string ScreenName
{
get => _screenName;
set => _screenName = value ?? GenerateRandomScreenName();
}
private string _screenName;
When you compile the preceding code in a nullable oblivious context, everything is fine. Once you enable nullable reference types, the ScreenName
property becomes a non-nullable reference. That's correct for the get
accessor: it never returns null
. Callers don't need to check the returned property for null
. But now setting the property to null
generates a warning. To support this type of code, you add the System.Diagnostics.CodeAnalysis.AllowNullAttribute attribute to the property, as shown in the following code:
[AllowNull]
public string ScreenName
{
get => _screenName;
set => _screenName = value ?? GenerateRandomScreenName();
}
private string _screenName = GenerateRandomScreenName();
You may need to add a using
directive for System.Diagnostics.CodeAnalysis to use this and other attributes discussed in this article. The attribute is applied to the property, not the set
accessor. The AllowNull
attribute specifies pre-conditions, and only applies to arguments. The get
accessor has a return value, but no parameters. Therefore, the AllowNull
attribute only applies to the set
accessor.
The preceding example demonstrates what to look for when adding the AllowNull
attribute on an argument:
- The general contract for that variable is that it shouldn't be
null
, so you want a non-nullable reference type. - There are scenarios for a caller to pass
null
as the argument, though they aren't the most common usage.
Most often you'll need this attribute for properties, or in
, out
, and ref
arguments. The AllowNull
attribute is the best choice when a variable is typically non-null, but you need to allow null
as a precondition.
Contrast that with scenarios for using DisallowNull
: You use this attribute to specify that an argument of a nullable reference type shouldn't be null
. Consider a property where null
is the default value, but clients can only set it to a non-null value. Consider the following code:
public string ReviewComment
{
get => _comment;
set => _comment = value ?? throw new ArgumentNullException(nameof(value), "Cannot set to null");
}
string _comment;
The preceding code is the best way to express your design that the ReviewComment
could be null
, but can't be set to null
. Once this code is nullable aware, you can express this concept more clearly to callers using the System.Diagnostics.CodeAnalysis.DisallowNullAttribute:
[DisallowNull]
public string? ReviewComment
{
get => _comment;
set => _comment = value ?? throw new ArgumentNullException(nameof(value), "Cannot set to null");
}
string? _comment;
In a nullable context, the ReviewComment
get
accessor could return the default value of null
. The compiler warns that it must be checked before access. Furthermore, it warns callers that, even though it could be null
, callers shouldn't explicitly set it to null
. The DisallowNull
attribute also specifies a pre-condition, it doesn't affect the get
accessor. You use the DisallowNull
attribute when you observe these characteristics about:
- The variable could be
null
in core scenarios, often when first instantiated. - The variable shouldn't be explicitly set to
null
.
These situations are common in code that was originally null oblivious. It may be that object properties are set in two distinct initialization operations. It may be that some properties are set only after some asynchronous work has completed.
The AllowNull
and DisallowNull
attributes enable you to specify that preconditions on variables may not match the nullable annotations on those variables. These provide more detail about the characteristics of your API. This additional information helps callers use your API correctly. Remember you specify preconditions using the following attributes:
- AllowNull: A non-nullable argument may be null.
- DisallowNull: A nullable argument should never be null.
Suppose you have a method with the following signature:
public Customer FindCustomer(string lastName, string firstName)
You've likely written a method like this to return null
when the name sought wasn't found. The null
clearly indicates that the record wasn't found. In this example, you'd likely change the return type from Customer
to Customer?
. Declaring the return value as a nullable reference type specifies the intent of this API clearly:
public Customer? FindCustomer(string lastName, string firstName)
For reasons covered under Generics nullability that technique may not produce the static analysis that matches your API. You may have a generic method that follows a similar pattern:
public T Find<T>(IEnumerable<T> sequence, Func<T, bool> predicate)
The method returns null
when the sought item isn't found. You can clarify that the method returns null
when an item isn't found by adding the MaybeNull
annotation to the method return:
[return: MaybeNull]
public T Find<T>(IEnumerable<T> sequence, Func<T, bool> predicate)
The preceding code informs callers that the return value may actually be null. It also informs the compiler that the method may return a null
expression even though the type is non-nullable. When you have a generic method that returns an instance of its type parameter, T
, you can express that it never returns null
by using the NotNull
attribute.
You can also specify that a return value or an argument isn't null even though the type is a nullable reference type. The following method is a helper method that throws if its first argument is null
:
public static void ThrowWhenNull(object value, string valueExpression = "")
{
if (value is null) throw new ArgumentNullException(nameof(value), valueExpression);
}
You could call this routine as follows:
public static void LogMessage(string? message)
{
ThrowWhenNull(message, $"{nameof(message)} must not be null");
Console.WriteLine(message.Length);
}
After enabling null reference types, you want to ensure that the preceding code compiles without warnings. When the method returns, the value
parameter is guaranteed to be not null. However, it's acceptable to call ThrowWhenNull
with a null reference. You can make value
a nullable reference type, and add the NotNull
post-condition to the parameter declaration:
public static void ThrowWhenNull([NotNull] object? value, string valueExpression = "")
{
_ = value ?? throw new ArgumentNullException(nameof(value), valueExpression);
// other logic elided
The preceding code expresses the existing contract clearly: Callers can pass a variable with the null
value, but the argument is guaranteed to never be null if the method returns without throwing an exception.
You specify unconditional postconditions using the following attributes:
- MaybeNull: A non-nullable return value may be null.
- NotNull: A nullable return value will never be null.
You're likely familiar with the string
method String.IsNullOrEmpty(String). This method returns true
when the argument is null or an empty string. It's a form of null-check: Callers don't need to null-check the argument if the method returns false
. To make a method like this nullable aware, you'd set the argument to a nullable reference type, and add the NotNullWhen
attribute:
bool IsNullOrEmpty([NotNullWhen(false)] string? value)
That informs the compiler that any code where the return value is false
doesn't need null checks. The addition of the attribute informs the compiler's static analysis that IsNullOrEmpty
performs the necessary null check: when it returns false
, the argument isn't null
.
string? userInput = GetUserInput();
if (!string.IsNullOrEmpty(userInput))
{
int messageLength = userInput.Length; // no null check needed.
}
// null check needed on userInput here.
The String.IsNullOrEmpty(String) method will be annotated as shown above for .NET Core 3.0. You may have similar methods in your codebase that check the state of objects for null values. The compiler won't recognize custom null check methods, and you'll need to add the annotations yourself. When you add the attribute, the compiler's static analysis knows when the tested variable has been null checked.
Another use for these attributes is the Try*
pattern. The postconditions for ref
and out
arguments are communicated through the return value. Consider this method shown earlier (in a nullable disabled context):
bool TryGetMessage(string key, out string message)
{
if (_messageMap.ContainsKey(key))
message = _messageMap[key];
else
message = null;
return message != null;
}
The preceding method follows a typical .NET idiom: the return value indicates if message
was set to the found value or, if no message is found, to the default value. If the method returns true
, the value of message
isn't null; otherwise, the method sets message
to null.
In a nullable enabled context, you can communicate that idiom using the NotNullWhen
attribute. When you annotate parameters for nullable reference types, make message
a string?
and add an attribute:
bool TryGetMessage(string key, [NotNullWhen(true)] out string? message)
{
if (_messageMap.ContainsKey(key))
message = _messageMap[key];
else
message = null;
return message is not null;
}
In the preceding example, the value of message
is known to be not null when TryGetMessage
returns true
. You should annotate similar methods in your codebase in the same way: the arguments could equal null
, and are known to be not null when the method returns true
.
There's one final attribute you may also need. Sometimes the null state of a return value depends on the null state of one or more arguments. These methods will return a non-null value whenever certain arguments aren't null
. To correctly annotate these methods, you use the NotNullIfNotNull
attribute. Consider the following method:
string GetTopLevelDomainFromFullUrl(string url)
If the url
argument isn't null, the output isn't null
. Once nullable references are enabled, you need to add more annotations if your API may accept a null argument. You could annotate the return type as shown in the following code:
string? GetTopLevelDomainFromFullUrl(string? url)
That also works, but will often force callers to implement extra null
checks. The contract is that the return value would be null
only when the argument url
is null
. To express that contract, you would annotate this method as shown in the following code:
[return: NotNullIfNotNull(nameof(url))]
string? GetTopLevelDomainFromFullUrl(string? url)
The previous example uses the nameof
operator for the parameter url
. That feature is available in C# 11. Before C# 11, you'll need to type the name of the parameter as a string. The return value and the argument have both been annotated with the ?
indicating that either could be null
. The attribute further clarifies that the return value won't be null when the url
argument isn't null
.
You specify conditional postconditions using these attributes:
- MaybeNullWhen: A non-nullable argument may be null when the method returns the specified
bool
value. - NotNullWhen: A nullable argument won't be null when the method returns the specified
bool
value. - NotNullIfNotNull: A return value isn't null if the argument for the specified parameter isn't null.
These attributes specify your intent when you've refactored common code from constructors into helper methods. The C# compiler analyzes constructors and field initializers to make sure that all non-nullable reference fields have been initialized before each constructor returns. However, the C# compiler doesn't track field assignments through all helper methods. The compiler issues warning CS8618
when fields aren't initialized directly in the constructor, but rather in a helper method. You add the MemberNotNullAttribute to a method declaration and specify the fields that are initialized to a non-null value in the method. For example, consider the following example:
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();
}
}
You can specify multiple field names as arguments to the MemberNotNull
attribute constructor.
The MemberNotNullWhenAttribute has a bool
argument. You use MemberNotNullWhen
in situations where your helper method returns a bool
indicating whether your helper method initialized fields.
Some methods, typically exception helpers or other utility methods, always exit by throwing an exception. Or, a helper may throw an exception based on the value of a Boolean argument.
In the first case, you can add the DoesNotReturnAttribute attribute to the method declaration. The compiler's null-state analysis doesn't check any code in a method that follows a call to a method annotated with DoesNotReturn
. Consider this method:
[DoesNotReturn]
private void FailFast()
{
throw new InvalidOperationException();
}
public void SetState(object containedField)
{
if (containedField is null)
{
FailFast();
}
// containedField can't be null:
_field = containedField;
}
The compiler doesn't issue any warnings after the call to FailFast
.
In the second case, you add the System.Diagnostics.CodeAnalysis.DoesNotReturnIfAttribute attribute to a Boolean parameter of the method. You can modify the previous example as follows:
private void FailFastIf([DoesNotReturnIf(true)] bool isNull)
{
if (isNull)
{
throw new InvalidOperationException();
}
}
public void SetFieldState(object? containedField)
{
FailFastIf(containedField == null);
// No warning: containedField can't be null here:
_field = containedField;
}
When the value of the argument matches the value of the DoesNotReturnIf
constructor, the compiler doesn't perform any null-state analysis after that method.
Adding nullable reference types provides an initial vocabulary to describe your APIs expectations for variables that could be null
. The attributes provide a richer vocabulary to describe the null state of variables as preconditions and postconditions. These attributes more clearly describe your expectations and provide a better experience for the developers using your APIs.
As you update libraries for a nullable context, add these attributes to guide users of your APIs to the correct usage. These attributes help you fully describe the null-state of arguments and return values.
- AllowNull: A non-nullable field, parameter, or property may be null.
- DisallowNull: A nullable field, parameter, or property should never be null.
- MaybeNull: A non-nullable field, parameter, property, or return value may be null.
- NotNull: A nullable field, parameter, property, or return value will never be null.
- MaybeNullWhen: A non-nullable argument may be null when the method returns the specified
bool
value. - NotNullWhen: A nullable argument won't be null when the method returns the specified
bool
value. - NotNullIfNotNull: A parameter, property, or return value isn't null if the argument for the specified parameter isn't null.
- DoesNotReturn: A method or property never returns. In other words, it always throws an exception.
- DoesNotReturnIf: This method or property never returns if the associated
bool
parameter has the specified value.
.NET feedback
.NET is an open source project. Select a link to provide feedback: