Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

C# Nullable Value Type: Syntax and Usage

Learn how to declare and use C# nullable value types with Nullable<T>, including HasValue, Value, GetValueOrDefault, and pattern matching.

~4 min readC#
#nullable value type#C# syntax#Nullable<T>#null handling
Diagram showing a nullable value type box with a value and a flag indicating whether a value is present.

A nullable value type is a C# feature that lets a value type such as int, bool, or DateTime represent a missing or unknown value. A nullable value type is an instance of System.Nullable<T> and is declared by appending ? to the underlying type, for example int? or DateTime?. The variable can hold either a valid value of T or null.

Declaring Nullable Value Types

The ? modifier is syntactic sugar for Nullable<T>. The following declarations are equivalent:

csharp
int? maybeNumber = null; Nullable<int> alsoMaybeNumber = null;

Both create a value type that wraps an int and a Boolean flag indicating whether a value is present. Because Nullable<T> is itself a struct, a nullable value type is still a value type. It does not introduce heap allocation when stored in a local variable or field, although boxing can occur in certain situations.

You can assign a normal value directly:

csharp
int? count = 42;

You can also assign a nullable variable from another nullable variable, and the null state is preserved.

Checking for a Value with HasValue and Value

The Nullable<T> structure exposes two important members: HasValue and Value. HasValue returns true when the variable contains a real value; otherwise it returns false. Accessing Value when HasValue is false throws an InvalidOperationException.

csharp
int? maybe = GetNullableInt(); if (maybe.HasValue) { Console.WriteLine($"Value is {maybe.Value}"); } else { Console.WriteLine("No value present"); }

Always check HasValue before reading Value, or use one of the safer access patterns described below.

Using GetValueOrDefault and Null-Coalescing

GetValueOrDefault() returns the underlying value if present, or the default value of T otherwise. You can also supply a custom default:

csharp
int? maybe = null; int result = maybe.GetValueOrDefault(-1); // returns -1

The null-coalescing operator ?? provides a more concise alternative:

csharp
int result = maybe ?? -1;

Both approaches avoid the exception risk and are common in real-world code. The ?? operator also works with nullable value types in expressions and assignments.

Pattern Matching with Nullable Value Types

C# pattern matching lets you test the underlying value of a nullable without explicitly checking HasValue. You can use is to check for a value and extract it:

csharp
if (maybe is int value) { Console.WriteLine(value); }

This is equivalent to checking HasValue and then reading Value, but the syntax is more readable. You can also combine it with other patterns:

csharp
string description = maybe switch { int v when v > 100 => "Large", int v => "Small", null => "None" };

The null pattern matches the case where HasValue is false. Pattern matching treats the nullable value type as having either its underlying value or null, so no explicit HasValue check is needed here.

Boxing and Performance Considerations

When a nullable value type is converted to object or an interface, the CLR boxes it. If HasValue is false, the boxed result is a null reference. If a value is present, the boxed object contains the underlying value, not the Nullable<T> wrapper. This behavior matters when you pass a nullable value type to a method that expects object, or when you store it in a non-generic collection such as ArrayList.

Boxing has a runtime cost. In hot paths, avoid unnecessary conversions. For example, prefer generic collections like List<int?> over non-generic collections, and use ?. and ?? to avoid repeated HasValue checks when possible. Calling GetValueOrDefault() on a nullable variable does not box it; boxing occurs when you convert the nullable to object or an interface.

Nullable Value Types vs Nullable Reference Types

C# 8 introduced nullable reference types, which are a compile-time annotation feature. They do not change the runtime behavior of reference types; they only enable static analysis warnings. Nullable value types, on the other hand, are a runtime feature that actually changes the type of the variable. The two features solve different problems:

FeatureNullable Value TypesNullable Reference Types
Runtime representationNullable<T> structSame as reference type
Null handlingRuntime check via HasValueCompile-time warnings
Introduced inC# 2C# 8
Applies toValue types onlyReference types only

Use nullable value types when a value type must represent an absent value, such as a database column that allows NULL. Use nullable reference types to document null intent and get compile-time warnings when a reference that should not be null is assigned null.

Common Pitfalls and Edge Cases

One common mistake is comparing a nullable value type directly to null without understanding the underlying behavior. The == operator works, but it is implemented by Nullable<T> and returns true when HasValue is false. This is fine, but be aware that null is not the same as the default value of T. For example, int? with no value is not the same as 0.

Another edge case is lifting operators. When you use arithmetic operators on nullable value types, the result is null if either operand is null. For example:

csharp
int? a = 5; int? b = null; int? sum = a + b; // sum is null

This behavior is called lifted operators and applies to most built-in operators. It can be surprising if you expect null to be treated as zero.

Finally, the is pattern example requires C# 7 or later, and the switch expression requires C# 8 or later. If you are using an older compiler, use HasValue and Value instead.

Try matching browser tools

All tools

Small utilities that fit C# work — they run entirely in this browser tab, so nothing you paste leaves your device.

All C# guides

More in C#

All C# guides

The guides filed next to this one in C#, in library order.