C# Reference ยท .NET, Tools and Concepts
The nullable context
Reference for the C# nullable context: the Nullable project property, #nullable directives, annotation and warning contexts, common warning codes and the ! operator.
The nullable context decides what a reference type name such as string means in a region of code and whether the compiler warns about possible null values. It has two independent switches. The annotation context controls the meaning of string versus string?. The warning context controls whether the compiler reports nullability problems at all.
With nullable enabled, string means "never null" and string? means "may be null". The compiler tracks which variables might be null at each point (flow analysis) and warns if you dereference one that might be. These are warnings, not errors, and they have no effect at run time: a string can still hold null if you ignore or suppress the warning.
<PropertyGroup> <Nullable>enable</Nullable> </PropertyGroup>
#nullable enable string name = "Ada"; // never null string? nickname = null; // may be null
Try it
This site compiles with Nullable enabled, so the compiler analyses your code. A warning never stops a build, so the third example compiles and runs; the warning is only a prediction of the failure.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
Project property
<Nullable> value |
Annotations | Warnings | Meaning |
|---|---|---|---|
enable |
on | on | Full nullable reference types. The default in new project templates. |
disable |
off | off | The pre-C# 8 world: all references are "oblivious". |
warnings |
off | on | Warnings, but ? on reference types is not allowed. Useful while migrating. |
annotations |
on | off | You can write ?, but no warnings. Good for annotating a library first. |
Directives
| Directive | Effect |
|---|---|
#nullable enable |
Turn on annotations and warnings from here |
#nullable disable |
Turn both off |
#nullable restore |
Return to the project setting |
#nullable enable annotations / warnings |
Switch only one of the two |
#nullable disable annotations / warnings |
Switch only one off |
A directive applies from its line to the next directive or the end of the file.
Common warning codes
| Code | Meaning |
|---|---|
| CS8600 | Converting a null literal or possible null value to a non-nullable type |
| CS8601 | Possible null reference assignment |
| CS8602 | Dereference of a possibly null reference |
| CS8603 | Possible null reference return |
| CS8604 | Possible null reference argument for a parameter |
| CS8618 | A non-nullable field or property is not initialized when the constructor ends |
| CS8625 | Cannot convert a null literal to a non-nullable reference type |
Operators and attributes
x!(null-forgiving) suppresses warnings aboutx. It does nothing at run time.?.,??,??=andis not nullwork with nullable flow analysis.- The attributes in
System.Diagnostics.CodeAnalysis, such as[NotNullWhen(true)],[MaybeNull]and[MemberNotNull], describe contracts that the compiler cannot infer. See Nullable analysis attributes. requiredmembers and constructors that set all non-nullable fields solve CS8618.
Usage notes
- Enable it for all new code. Nullable reference types find real bugs, and new projects created from the templates already enable it.
- Migrate in steps. Set
<Nullable>disable</Nullable>, then use#nullable enablefile by file, or set<Nullable>enable</Nullable>and fix warnings project by project. - Treat warnings as errors in CI with
<WarningsAsErrors>nullable</WarningsAsErrors>once the project is clean. string?does not create a new type. For reference types it is only an annotation, unlikeint?, which is the distinct structNullable<int>. See Nullable reference types and Nullable value types.- External input is still unchecked. Deserialized JSON, reflection, and unannotated libraries can produce null in a variable typed
string. Validate at boundaries. - Avoid the
!operator as a habit. Prefer fixing the design: initialize fields, mark themrequired, or returnstring?honestly. Use!only when you know something the compiler cannot. - Generics:
Tis neither nullable nor not-nullable without a constraint. UseT?withwhere T : class,where T : structor[MaybeNull];where T : notnullforbids nullable type arguments. ArgumentNullException.ThrowIfNull(x)both checks at run time and tells the compilerxis not null afterwards.