skip to content

In a C# project, what do the Nullable property values enable, warnings, annotations and disable each turn on, and how do #nullable directives override them?

level: middleimportance: should knowfreq 55%

answer

  1. two independent flags
  2. annotation context versus warning context
  3. CS8632 outside an annotations context
  4. restore means back to the project

basics

~20 s

The nullable context has two flags: annotations (whether ? and non-nullable types mean anything) and warnings (whether null-state warnings are reported). enable sets both, disable neither, warnings and annotations one each; #nullable directives change either flag for the rest of a file.

solid answer

~40 s

The `<Nullable>` property sets the project-wide **nullable context**, which is two flags. The **annotation** flag decides whether an unsuffixed reference type is non-nullable and `T?` is nullable; the **warning** flag decides whether null-state analysis reports warnings. `enable` turns both on; `disable`, the compiler default when the property is missing, turns both off and leaves code nullable-oblivious; `warnings` reports dereference warnings while types stay oblivious, so `string? x` warns CS8632; `annotations` makes the `?` meaningful and publishes annotations but reports no warnings. In source, `#nullable enable`, `disable` and `restore`, optionally followed by `warnings` or `annotations`, change one or both flags from that line to the end of the file or the next directive, and `restore` returns to the project setting. Files marked as generated start with nullable disabled.

code

csharp · 5 lines
csharp
#:property Nullable=warnings
string? tag = "vip";            // CS8632: '?' needs an annotations context
string name = null;              // no warning: string is oblivious here
Console.WriteLine(tag);
Console.WriteLine(name.Length);  // CS8602: the warning flag still tracks null

go deeper

for a junior

Recall the four values of the Nullable property and that enable turns on both the question-mark annotations and the warnings.

for a middle

Explain the annotation flag and the warning flag separately, what warnings mode and annotations mode each give you, and how restore returns to the project setting.

for a senior

Know where nulls leak in an enabled project: generated files compiled disabled, and oblivious APIs whose returns are treated as not-null with no warning.

for a principal

Use the two flags as migration levers: which default the project carries, which direction the directives run, and when the last directive must be gone.

## Two flags, not one switch The **nullable context** of any line of C# is made of two independent flags: - The **annotation flag**. When it is on, a reference type written without `?` is non-nullable and `string?` is nullable, and the compiler emits those annotations into metadata. When it is off, every reference type is **nullable-oblivious**: the compiler does not know whether null is intended. - The **warning flag**. When it is on, the compiler runs null-state analysis and reports warnings such as CS8602 (dereference of a possibly null reference). When it is off, no nullable warnings are reported. The split exists for migration: a large codebase can turn on one half of the feature at a time. ## The four project values The `<Nullable>` MSBuild property sets both flags for the whole project. The argument must be one of four values: | `<Nullable>` | Annotation flag | Warning flag | What you see | |---|---|---|---| | `enable` | on | on | `string` is non-nullable, `string?` nullable, all nullable warnings | | `disable` | off | off | Code behaves as before C# 8; `string?` warns CS8632 | | `warnings` | off | on | Types stay oblivious, `string?` warns CS8632, but dereferences of values the analysis knows may be null warn CS8602 | | `annotations` | on | off | `?` is meaningful and published, but no nullable warnings at all | Three details make the table concrete: 1. When the property is absent, the compiler's default is `disable`. Project templates since .NET 6 write `<Nullable>enable</Nullable>`, and a file-based app run with `dotnet run app.cs` in .NET 10 also starts enabled, which is why an old project and a new one behave so differently. 2. Under `warnings`, the analysis still runs on oblivious types. `string name = null;` produces no warning, because `string` carries no intent, but `name.Length` right after it warns CS8602, because the analysis saw the null assignment. A method declared to return `string` can `return null;` without CS8603. 3. Under `annotations`, the `?` means what it says and the metadata is written, so consumers with nullable enabled get accurate warnings, while the project itself sees none. `string name = null; Console.WriteLine(name.Length);` compiles cleanly and throws `NullReferenceException`. ## Directives inside a file The `#nullable` preprocessor directive overrides the project for a region of one file: - `#nullable enable` and `#nullable disable` set both flags. - `#nullable enable warnings`, `#nullable disable warnings`, `#nullable enable annotations` and `#nullable disable annotations` set one flag and leave the other alone. - `#nullable restore`, `#nullable restore warnings` and `#nullable restore annotations` return the named flags to the **project setting**, not to whatever an earlier directive said. A directive applies from its line to the next directive or the end of the file; it never leaks into other files. That makes both migration directions possible: project `disable` with `#nullable enable` at the top of each migrated file, or project `enable` with `#nullable disable` at the top of each file not yet migrated. ## Generated code and oblivious APIs Files marked as generated (a name ending in `.g.cs`, `.generated.cs` or `.designer.cs`, a leading `<auto-generated>` comment, or `generated_code = true` in `.editorconfig`) are compiled with the nullable context disabled whatever the project says. A generator that wants annotations must emit its own `#nullable enable`; writing `?` in generated code without one warns CS8669. Code compiled in a disabled annotation context exposes **oblivious** types to its callers. A call to an oblivious method returning `string` is treated as not-null: assigning it to a non-nullable variable or dereferencing it raises no warning, even if the method returns null. That is a common way a "fully enabled" project still meets null: it calls into code that never stated its intent. ## Choosing a value - `enable` for new projects and for any project that has finished migrating. - `warnings` to harvest likely `NullReferenceException` sites without changing any declared types yet. - `annotations` for a library that wants to publish accurate contracts before cleaning up its own internals. - `disable` only for code that will not be touched again. The flags are compile-time settings for the compiler; none of them adds a run-time null check.

  • Why does a new project see nullable warnings while an old one with the same code sees none?
    The compiler's default for a missing `<Nullable>` property is `disable`, while project templates since .NET 6 write `<Nullable>enable</Nullable>`. The older project file simply never set it, so its code is nullable-oblivious and the analysis reports nothing.
  • A source generator emits string? in a .g.cs file and the build warns; why?
    Files marked as generated, including any name ending in `.g.cs`, are compiled with the nullable context disabled regardless of the project. Using `?` there warns CS8669; the generator should emit `#nullable enable` at the top of its output.
  • What does #nullable restore warnings do in a file that earlier said #nullable disable?
    It returns only the warning flag to the project's `<Nullable>` setting, leaving the annotation flag as the earlier `#nullable disable` set it. Restore always means the project setting, never the previous directive.

  • Nullable is a single on/off switch for the whole feature.
  • The Nullable property defaults to enable when the project file omits it.
  • #nullable restore goes back to the previous #nullable directive.
  • A #nullable directive at the top of one file applies to the whole project.
  • With Nullable set to warnings, string? declares a nullable string cleanly.