# Nullable Reference Types in C# Nullable reference types is a C# 8 (proposed, specified in C# 9) feature that aims to reduce the likelihood of null reference exceptions by guiding the user to explicitly declare nullability. It consists of three parts: - Improved static analysis ([[#Static Analysis]]) - New attributes for annotating APIs ([[#API Attributes]]) - Nullable variables ([[#Nullable Variables]]) ## Enabling New Features Nullable reference features must be explicitly enabled using the `Nullable` MSBuild property, or using the `#nullable` compiler directive. The following values are possible: - `disabled` (and `#nullable enable/disable/restore`, where restore restores project defaults) (C# 7.3 compatibility mode and default) - Nullable warnings are not emitted - All reference types are considered to be nullable reference types - You can't declare a reference as a nullable reference (`string?`). - You can use the bang (`!`) but it will be ignored - `enabled` all new features are enabled. Complete opposite of `disabled` - `warnings` and `annotations` are used to port older projects. See [Nullable References](https://docs.microsoft.com/en-us/dotnet/csharp/nullable-references) on for details. ## Static Analysis Compiler classifies all references as either *not-null* or *maybe-null*, and emits warnings whenever you try to dereference a *maybe-null* value. References are classified as *not-null* if: - It has been assigned to a value that is known to be *not-null* and - The reference has been checked against null and hasn't been modified since ## API Attributes - Preconditions - `AllowNull` indicates that null values for a parameter (or a property) are accepted - `DisallowNull` indicates that null values for a parameter (or a property) are not accepted - Postconditions - `return: MaybeNull` indicates that a return value may be null - `return: NotNull` indicates that a return is never null - `return: MaybeNullWhen` indicates that a parameter may be null when the function returns the given bool (used for instance on methods like `string.IsNullOrEmpty`) - `return: NotNullWhen` indicates that a parameter is never null when the function returns the given bool (used for instance on methods like `string.IsNullOrEmpty`) - `return: NotNullIfNotNull` indicates that an out parameter (or the function's return value) is never null if the specified input parameter is not null (takes the name of the parameter as string) - Other attributes - `MemberNotNull` is applied to a method or a property, and will indicate that the member or property will ensure that the specified field or property is not null (setter methods) ## Nullable Variables The type of any reference variable can be declared as *maybe-null* by appending a question mark to the type (`string?`). You can override compiler warnings with a bang (`someVariable!.Length`). ## Use With Auto-Generated Files The compiler disables nullable references for all auto-generated files, which are defined as files that: - have a comment `//<auto-generated>` in the first line) - files that have the `generated_code = true` property set in `.editorconfig` - whose names start with `TemporaryGeneratedFile_` - whose names end with `.designer.cs`, `.generated.cs`, `.g.cs`, or `.g.i.cs` ## Sources - .NET Docs. [Nullable Reference Types](https://docs.microsoft.com/en-us/dotnet/csharp/nullable-references). - .NET Docs. [Attributes for Null-State Static Analysis](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/attributes/nullable-analysis). - .NET Docs. [Nullable Reference Types Specification](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/proposals/csharp-9.0/nullable-reference-types-specification).