Skip to content
Tutorials Center
My learning

Topics

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.

XML
<PropertyGroup>
  <Nullable>enable</Nullable>
</PropertyGroup>
C#
#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.

C# Working with string and string?

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.

C# Warnings and the #nullable directive

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.

C# A warning that predicts a crash

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 about x. It does nothing at run time.
  • ?., ??, ??= and is not null work 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.
  • required members 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 enable file 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, unlike int?, which is the distinct struct Nullable<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 them required, or return string? honestly. Use ! only when you know something the compiler cannot.
  • Generics: T is neither nullable nor not-nullable without a constraint. Use T? with where T : class, where T : struct or [MaybeNull]; where T : notnull forbids nullable type arguments.
  • ArgumentNullException.ThrowIfNull(x) both checks at run time and tells the compiler x is not null afterwards.