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?
answer
- two independent flags
- annotation context versus warning context
- CS8632 outside an annotations context
- restore means back to the project
basics
~20 sThe 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 sThe `<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#: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 nullgo deeper
Recall the four values of the Nullable property and that enable turns on both the question-mark annotations and the warnings.
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.
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.
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.