majiayu000 C# Nullable Types
Master nullable reference types, null safety patterns, and migration strategies in C# 8+. This skill covers nullable value types, nullable reference types, null-safety annotations, operators, and best practices for writing null-safe code.
Nullable Reference Types (C# 8+)
Nullable reference types provide compile-time null safety by distinguishing between nullable and non-nullable reference types.
Enabling Nullable Context
// Project-wide in .csproj
<PropertyGroup>
<Nullable>enable</Nullable>
</PropertyGroup>
// File-level directive
#nullable enable
public class User
{
// Non-nullable - must be initialized
public string Name { get; set; } = string.Empty;
// Nullable - can be null
public string? MiddleName { get; set; }
// Non-nullable - must be set in constructor
public string Email { get; set; }
public User(string email)
{
Email = email;
}
}
// Disable for legacy code
#nullable disable
public class LegacyClass
{
public string Name { get; set; } // Warning suppressed
}
#nullable restore // Return to project default
Non-nullable and Nullable References
#nullable enable
public class PersonService
{
// ✅ Non-nullable parameter and return type
public string FormatName(string firstName, string lastName)
{
return $"{firstName} {lastName}";
}
// ✅ Nullable parameter
public string FormatNameWithMiddle(string firstName, string? middleName, string lastName)
{
if (middleName != null)
{
return $"{firstName} {middleName} {lastName}";
}
return $"{firstName} {lastName}";
}
// ✅ Nullable return type
public string? FindUserEmail(int userId)
{
var user = _repository.Find(userId);
return user?.Email; // May return null
}
// ⚠️ Warning - possible null reference
public string GetUpperName(string? name)
{
// CS8602: Possible null reference
return name.ToUpper();
}
// ✅ Fixed with null check
public string GetUpperNameSafe(string? name)
{
if (name == null)
{
throw new ArgumentNullException(nameof(name));
}
return name.ToUpper();
}
}
Nullable Value Types
Value types can be made nullable using Nullable<T> or the ? syntax.
Nullable<T> and T?
public class NullableValueTypes
{
// Nullable value types
public int? Age { get; set; }
public DateTime? BirthDate { get; set; }
public decimal? Salary { get; set; }
public bool? IsActive { get; set; }
// Equivalent to:
public Nullable<int> AgeVerbose { get; set; }
public void WorkWithNullables()
{
int? value = null;
// HasValue and Value properties
if (value.HasValue)
{
int actualValue = value.Value;
Console.WriteLine(actualValue);
}
// GetValueOrDefault
int result1 = value.GetValueOrDefault(); // 0
int result2 = value.GetValueOrDefault(42); // 42
// Null coalescing
int result3 = value ?? 100; // 100
}
public int CalculateAge(DateTime? birthDate)
{
// ⚠️ Warning - possible null reference
// return DateTime.Now.Year - birthDate.Value.Year;
// ✅ Correct with null check
if (!birthDate.HasValue)
{
throw new ArgumentException("Birth date is required", nameof(birthDate));
}
return DateTime.Now.Year - birthDate.Value.Year;
}
}
Nullable Value Type Operations
public class NullableOperations
{
public void ArithmeticOperations()
{
int? a = 5;
int? b = 10;
int? c = null;
// Arithmetic with nullables
int? sum = a + b; // 15
int? nullSum = a + c; // null
// Comparison
bool? equal = a == b; // false
bool? nullEqual = a == c; // null (neither true nor false)
// Lifted operators
int? result = (a > 0) ? a * 2 : null;
}
public decimal? CalculateDiscount(decimal? price, decimal? discountPercent)
{
// If either is null, result is null
return price * (1 - discountPercent / 100);
}
public void BooleanLogic()
{
bool? a = true;
bool? b = false;
bool? c = null;
// Three-valued logic
bool? and1 = a & b; // false
bool? and2 = a & c; // null
bool? and3 = b & c; // false (false & anything = false)
bool? or1 = a | b; // true
bool? or2 = a | c; // true (true | anything = true)
bool? or3 = b | c; // null
}
}
Null Safety Annotations
Attributes that provide additional null-safety information to the compiler.
Common Annotations
using System.Diagnostics.CodeAnalysis;
public class AnnotationExamples
{
// [NotNull] - Parameter won't be null when method returns normally
public void ProcessUser([NotNull] User? user)
{
if (user == null)
{
throw new ArgumentNullException(nameof(user));
}
// Compiler knows user is not null here
Console.WriteLine(user.Name);
}
// [MaybeNull] - Return value may be null even if type is non-nullable
[return: MaybeNull]
public T GetValueOrDefault<T>(string key)
{
if (_dictionary.TryGetValue(key, out var value))
{
return value;
}
return default; // May be null for reference types
}
// [NotNullWhen] - Parameter is not null when method returns specified bool
public bool TryGetUser(int id, [NotNullWhen(true)] out User? user)
{
user = _repository.Find(id);
return user != null;
}
public void UseUser(int id)
{
if (TryGetUser(id, out var user))
{
// Compiler knows user is not null here
Console.WriteLine(user.Name);
}
}
// [NotNullIfNotNull] - Return value is not null if parameter
// is not null
[return: NotNullIfNotNull(nameof(value))]
public string? ProcessString(string? value)
{
return value?.Trim().ToUpperInvariant();
}
// [DoesNotReturn] - Method never returns normally
[DoesNotReturn]
public void ThrowError(string message)
{
throw new InvalidOperationException(message);
}
public void ValidateUser(User? user)
{
if (user == null)
{
ThrowError("User is required");
}
// Compiler knows this is unreachable if user is null
Console.WriteLine(user.Name);
}
}
MemberNotNull Annotation
public class InitializationExample
{
private string _name;
private string _email;
public InitializationExample()
{
Initialize("Default", "default@example.com");
}
// Tells compiler these members are initialized
[MemberNotNull(nameof(_name), nameof(_email))]
private void Initialize(string name, string email)
{
_name = name;
_email = email;
}
[MemberNotNull(nameof(_name), nameof(_email))]
public void Reset()
{
_name = string.Empty;
_email = string.Empty;
}
}
Null-Forgiving Operator
The null-forgiving operator (!) suppresses nullable warnings when you know better than the compiler.
Using the ! Operator
public class NullForgivingExamples
{
private User? _currentUser;
public void Initialize()
{
_currentUser = LoadUser();
}
public void ProcessCurrentUser()
{
// ⚠️ Warning: Possible null reference
// Console.WriteLine(_currentUser.Name);
// ✅ Use ! when you know it's not null
Console.WriteLine(_currentUser!.Name);
}
// ⚠️ Use sparingly and carefully
public string GetUserName()
{
// Only use ! if you're absolutely sure
return _currentUser!.Name;
}
// ✅ Better: check explicitly
public string GetUserNameSafe()
{
if (_currentUser == null)
{
throw new InvalidOperationException("User not initialized");
}
return _currentUser.Name;
}
// Common pattern with dictionary
public void DictionaryPattern()
{
var dict = new Dictionary<string, User>();
dict["key"] = new User("test@example.com");
// You know key exists
var user = dict["key"];
Console.WriteLine(user.Email); // No warning needed
// But with TryGetValue
if (dict.TryGetValue("key", out var foundUser))
{
// foundUser is User?, but you know it's not null here
Console.WriteLine(foundUser!.Email); // Or better: check in if
}
}
}
When NOT to Use the Null-Forgiving Operator
public class BadNullForgiving
{
// ❌ BAD - Hiding real problems
public void ProcessData(string? input)
{
var result = input!.ToUpper(); // Will crash if input is null
}
// ✅ GOOD - Proper null handling
public void ProcessDataSafe(string? input)
{
if (input == null)
{
throw new ArgumentNullException(nameof(input));
}
var result = input.ToUpper();
}
// ❌ BAD - False confidence
public User GetUser(int id)
{
return _repository.Find(id)!; // May actually be null!
}
// ✅ GOOD - Handle null case
public User GetUserSafe(int id)
{
return _repository.Find(id)
?? throw new KeyNotFoundException($"User {id} not found");
}
}
Null-Conditional Operators
Safe navigation operators for accessing members that might be null.
?. and ?[] Operators
public class NullConditionalExamples
{
public void SafeNavigation()
{
User? user = GetUser();
// ✅ Null-conditional member access
string? name = user?.Name; // null if user is null
// ✅ Chaining null-conditional operators
string? city = user?.Address?.City;
// ✅ Null-conditional indexing
char? firstChar = user?.Name?[0];
// ✅ Combining with method calls
int? nameLength = user?.Name?.Length;
// ✅ With null coalescing
string displayName = user?.Name ?? "Guest";
// ✅ Null-conditional with invocation
int? result = user?.CalculateAge();
}
public void ArrayAndCollectionAccess()
{
int[]? numbers = GetNumbers();
// ✅ Null-conditional array access
int? first = numbers?[0];
// ✅ Null-conditional with LINQ
int? max = numbers?.Max();
// ✅ Dictionary access
Dictionary<string, User>? users = GetUsers();
User? user = users?["key"];
}
public void InvocationExamples()
{
Action? callback = GetCallback();
// ✅ Null-conditional invocation
callback?.Invoke();
// Equivalent to:
if (callback != null)
{
callback.Invoke();
}
// ✅ With events
EventHandler? handler = SomeEvent;
handler?.Invoke(this, EventArgs.Empty);
}
}
Null-Coalescing Operators
The ?? and ??= operators provide default values for null expressions.
?? Operator
public class NullCoalescingExamples
{
public void BasicCoalescing()
{
string? name = GetName();
// ✅ Provide default if null
string displayName = name ?? "Unknown";
// ✅ Chain multiple coalescing
string result = GetPrimaryName()
?? GetSecondaryName()
?? GetDefaultName()
?? "Fallback";
// ✅ With value types
int? nullableValue = GetValue();
int value = nullableValue ?? 0;
// ✅ Combine with null-conditional
int length = user?.Name?.Length ?? 0;
}
public User GetUserOrDefault(int id)
{
// ✅ Return default if null
return _repository.Find(id) ?? new User("guest@example.com");
}
public string GetConfigValue(string key, string defaultValue)
{
// ✅ Configuration pattern
return _config[key] ?? defaultValue;
}
}
??= Operator (Null-Coalescing Assignment)
public class NullCoalescingAssignment
{
private User? _cachedUser;
private List<string>? _items;
public User GetUser(int id)
{
// ✅ Lazy initialization pattern
_cachedUser ??= LoadUser(id);
return _cachedUser;
}
public void EnsureListInitialized()
{
// ✅ Ensure collection is initialized
_items ??= new List<string>();
_items.Add("item");
}
public void UpdateNameIfNull(User user)
{
// ✅ Set only if currently null
user.MiddleName ??= "N/A";
}
// Before C# 8, you would write:
public void OldWay()
{
if (_items == null)
{
_items = new List<string>();
}
// Or:
_items = _items ?? new List<string>();
}
}
Pattern Matching with Null
C# 9+ pattern matching enhancements for null checking.
Null Pattern Matching
public class PatternMatchingExamples
{
public void IsPatterns()
{
object? obj = GetObject();
// ✅ Check for null
if (obj is null)
{
Console.WriteLine("Object is null");
}
// ✅ Check for not null
if (obj is not null)
{
Console.WriteLine("Object is not null");
}
// ✅ Type pattern with null check
if (obj is string s)
{
// s is not null here
Console.WriteLine(s.ToUpper());
}
// ✅ Property pattern
if (obj is User { Name: not null } user)
{
Console.WriteLine(user.Name);
}
}
public string GetDescription(User? user) => user switch
{
null => "No user",
{ Name: null } => "User without name",
{ Name: var name } => $"User: {name}"
};
public void RecursivePatterns()
{
Order? order = GetOrder();
// ✅ Complex pattern matching
var status = order switch
{
null => "No order",
{ Customer: null } => "Order without customer",
{ Customer.Address: null } => "Customer without address",
{ Customer.Address.City: var city } => $"Shipping to {city}",
};
}
}
Migration Strategies
Gradually migrate existing code to nullable reference types.
Incremental Migration
// Step 1: Enable nullable in .csproj with warnings as errors
<PropertyGroup>
<Nullable>enable</Nullable>
<WarningsAsErrors>nullable</WarningsAsErrors>
</PropertyGroup>
// Step 2: Migrate file by file
#nullable enable
public class MigratedClass
{
// Fix all warnings in this file
public string Name { get; set; } = string.Empty;
public string? Description { get; set; }
}
// Step 3: Use #nullable disable for legacy code
#nullable disable
public class LegacyClass
{
// No nullable warnings here
public string Name { get; set; }
}
#nullable restore
Migration Patterns
public class MigrationPatterns
{
// Before: Everything nullable by default
#nullable disable
public string GetUserName(User user)
{
return user.Name;
}
#nullable restore
// After: Explicit nullability
#nullable enable
public string GetUserNameNullable(User? user)
{
if (user == null)
{
throw new ArgumentNullException(nameof(user));
}
return user.Name ?? throw new InvalidOperationException("Name is required");
}
// Pattern: Make optional parameters explicit
// Before
#nullable disable
public void ProcessData(string data, string format)
{
format = format ?? "json";
}
#nullable restore
// After
#nullable enable
public void ProcessDataNullable(string data, string? format = null)
{
format ??= "json";
}
// Pattern: Use nullable return types
// Before
#nullable disable
public User FindUser(int id)
{
return _repository.Find(id); // May return null
}
#nullable restore
// After
#nullable enable
public User? FindUserNullable(int id)
{
return _repository.Find(id);
}
}
Compiler Warnings and Strictness
Understanding and configuring nullable warning levels.
Warning Levels
// In .csproj
<PropertyGroup>
<Nullable>enable</Nullable>
<!-- Treat nullable warnings as errors -->
<WarningsAsErrors>CS8600;CS8601;CS8602;CS8603;CS8604</WarningsAsErrors>
<!-- Or treat all nullable warnings as errors -->
<WarningsAsErrors>nullable</WarningsAsErrors>
</PropertyGroup>
// Common warnings:
// CS8600: Converting null literal or possible null value to 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
#nullable enable
public class WarningExamples
{
// CS8618: Non-nullable property must contain non-null value when exiting constructor
public string Name { get; set; } = string.Empty;
// CS8603: Possible null reference return
public string GetName(User? user)
{
return user?.Name ?? string.Empty; // Fix
}
// CS8602: Dereference of possibly null reference
public int GetLength(string? value)
{
return value?.Length ?? 0; // Fix
}
// Suppress specific warning
#pragma warning disable CS8602
public void LegacyCode(string? value)
{
Console.WriteLine(value.Length); // Warning suppressed
}
#pragma warning restore CS8602
}
Nullable in Generic Constraints
Handling nullability in generic type parameters.
Generic Nullable Constraints
#nullable enable
public class GenericNullability
{
// T? is nullable for both reference and value types
public T? FindOrDefault<T>(int id)
{
var result = _repository.Find<T>(id);
return result; // May be null
}
// where T : class - T is a reference type
public T Create<T>(string name) where T : class, new()
{
var instance = new T();
return instance; // Never null
}
// where T : class? - T is a nullable reference type
public void Process<T>(T? value) where T : class
{
if (value == null)
{
return;
}
// value is not null here
Console.WriteLine(value.ToString());
}
// where T : struct - T is a non-nullable value type
public T GetValue<T>() where T : struct
{
return default; // Returns default value, never null
}
// where T : notnull - T cannot be nullable
public void RequireNonNull<T>(T value) where T : notnull
{
// value is guaranteed not to be null
Console.WriteLine(value.ToString());
}
}
Nullable Generic Patterns
public class Repository<T> where T : class
{
private readonly Dictionary<int, T> _cache = new();
// Return nullable when not found
public T? Find(int id)
{
_cache.TryGetValue(id, out var result);
return result;
}
// Throw when not found
public T Get(int id)
{
return _cache[id]; // Throws if not found
}
// Try pattern
public bool TryGet(int id, [NotNullWhen(true)] out T? result)
{
return _cache.TryGetValue(id, out result);
}
}
public class NullableGenericList<T>
{
private readonly List<T> _items = new();
// First or null
public T? FirstOrDefault()
{
return _items.Count > 0 ? _items[0] : default;
}
// Find with predicate
public T? Find(Predicate<T> predicate)
{
foreach (var item in _items)
{
if (predicate(item))
{
return item;
}
}
return default;
}
}
Best Practices
- Enable Nullable Globally: Use
<Nullable>enable</Nullable>in .csproj - Explicit Nullability: Make nullability intentions clear in APIs
- Validate at Boundaries: Check for null at public API boundaries
- Use Null-Conditional Operators: Prefer ?. over explicit null checks
- Avoid Null-Forgiving: Use ! sparingly and only when truly necessary
- Return Non-Nullable: Prefer non-nullable return types when possible
- Use Annotations: Apply [NotNull], [MaybeNull] etc. appropriately
- Constructor Initialization: Initialize non-nullable properties in constructors
- Throw on Invalid State: Throw exceptions for unexpected nulls
- Gradual Migration: Migrate file-by-file with #nullable directives
Common Pitfalls
- Overusing !: Suppressing warnings instead of fixing root cause
- Not Initializing: Forgetting to initialize non-nullable properties
- Silent Failures: Not handling null cases in public APIs
- Mixing Contexts: Inconsistent nullable/disable throughout codebase
- Ignoring Warnings: Treating warnings as noise instead of issues
- Null Return Types: Returning null without nullable return type
- Unchecked Parameters: Not validating nullable parameters
- Generic Confusion: Misunderstanding T? in generic methods
- Legacy Assumptions: Assuming all references can be null
- False Confidence: Trusting ! operator without verification
When to Use
Use this skill when:
- Writing null-safe C# code
- Migrating to nullable reference types
- Preventing NullReferenceExceptions
- Designing clear APIs with explicit nullability
- Working with optional values
- Implementing defensive programming
- Refactoring legacy code
- Setting up new C# projects
- Enforcing null safety at compile time
- Working with generic nullable types