csharp-nullable-types

name	csharp-nullable-types
user-invocable	false
description	Use when C# nullable reference types and value types for null safety, nullable annotations, and patterns for handling null values.
allowed-tools	["Read","Write","Edit","Grep","Glob","Bash"]

C# Nullable Types

Nullable types in C# help prevent null reference exceptions, one of the most common programming errors. C# 8.0 introduced nullable reference types, providing compile-time null-safety checking. This skill covers nullable value types, nullable reference types, null-coalescing operators, and patterns for safe null handling.

Nullable Value Types

Value types (int, double, bool, struct) normally cannot be null. Nullable value types enable representing "no value" state.

using System;

public class NullableValueTypes
{
    // Declaration
    public void Declaration()
    {
        int? nullableInt = null;
        int? anotherInt = 42;

        double? nullableDouble = null;
        bool? nullableBool = true;

        // Generic syntax (equivalent)
        Nullable<int> genericNullable = null;
    }

    // Checking for null
    public void NullChecking()
    {
        int? value = GetNullableValue();

        // HasValue property
        if (value.HasValue)
        {
            int actualValue = value.Value;
            Console.WriteLine(actualValue);
        }

        // Comparison with null
        if (value != null)
        {
            Console.WriteLine(value.Value);
        }

        // Null-conditional operator
        int? doubled = value?.GetHashCode();
    }

    // Getting values
    public void GettingValues()
    {
        int? value = 42;

        // Value property (throws if null)
        int val1 = value.Value;

        // GetValueOrDefault
        int val2 = value.GetValueOrDefault();  // Returns 0 if null
        int val3 = value.GetValueOrDefault(10); // Returns 10 if null

        // Null-coalescing operator
        int val4 = value ?? 0;  // Returns 0 if null
    }

    // Nullable in expressions
    public void NullableExpressions()
    {
        int? a = 10;
        int? b = 20;
        int? c = null;

        // Arithmetic (null if any operand is null)
        int? sum1 = a + b;  // 30
        int? sum2 = a + c;  // null

        // Comparison
        bool? equal = a == b;  // false
        bool? greater = a > c;  // null

        // Logical operators
        bool? and = (a > 5) & (c > 5);  // null
    }

    // Nullable structs
    public struct Point
    {
        public int X { get; set; }
        public int Y { get; set; }
    }

    public void NullableStructs()
    {
        Point? point = null;

        if (point.HasValue)
        {
            int x = point.Value.X;
            int y = point.Value.Y;
        }

        // Null-conditional with structs
        int? x = point?.X;
    }

    private int? GetNullableValue() => null;
}

Nullable Reference Types

C# 8.0+ provides nullable reference types, enabling compile-time null-safety for reference types.

#nullable enable

using System;
using System.Collections.Generic;

public class NullableReferenceTypes
{
    // Non-nullable by default
    public string Name { get; set; } = string.Empty;

    // Explicitly nullable
    public string? MiddleName { get; set; }

    // Constructor
    public NullableReferenceTypes(string name, string? middleName = null)
    {
        Name = name;  // Must be non-null
        MiddleName = middleName;  // Can be null
    }

    // Method with nullable parameters
    public string FormatName(string firstName, string? middleName,
                            string lastName)
    {
        // Compiler warns if middleName used without null check
        if (middleName != null)
        {
            return $"{firstName} {middleName} {lastName}";
        }

        return $"{firstName} {lastName}";
    }

    // Nullable return type
     ? FindPerson( id)
    {
        
         id >  ?  : ;
    }

    
    
    {
        
        List<> names =  List<> { ,  };

        
        List<?> nullableNames =  List<?>
        {
            , , 
        };

        
        Dictionary<, ?> dict =
             Dictionary<, ?>
            {
                { ,  },
                { ,  }
            };
    }

    
     T? FindById<T>( id)  T : 
    {
        
         (T);
    }

    
    
    {
        ? maybeName = GetName();

        
         name = maybeName!;
    }

     ? GetName() => ;
}

Null-Coalescing Operators

Null-coalescing operators provide concise null handling.

#nullable enable

using System;
using System.Collections.Generic;

public class NullCoalescingOperators
{
    // Null-coalescing operator (??)
    public string GetDisplayName(string? name)
    {
        // Returns "Unknown" if name is null
        return name ?? "Unknown";
    }

    // Chaining
    public string GetFirstNonNull(string? a, string? b, string? c)
    {
        return a ?? b ?? c ?? "Default";
    }

    // Null-coalescing assignment (??=)
    public void NullCoalescingAssignment()
    {
        string? name = null;

        // Assign only if null
        name ??= "Default Name";  // name is now "Default Name"

        name ??= "Another Name";  // name stays "Default Name"
    }

    // With collections
    public void CollectionCoalescing()
    {
        List<string>? list = null;

        // Initialize if null
        list ??= new List<string>();

        
        list.Add();
    }

    
     List<>? _items;
     List<> Items => _items ??=  List<>();

    
    
    {
        
         user?.Profile?.DisplayName ??
               user?.Email ??
               ;
    }

      
    {
         Profile? Profile { ; ; }
         ? Email { ; ; }
    }

      
    {
         ? DisplayName { ; ; }
    }
}

Null-Conditional Operator

The null-conditional operator safely accesses members and calls methods on potentially null references.

#nullable enable

using System;
using System.Collections.Generic;

public class NullConditionalOperator
{
    public class Person
    {
        public string Name { get; set; } = string.Empty;
        public Address? Address { get; set; }
        public List<string>? PhoneNumbers { get; set; }
    }

    public class Address
    {
        public string City { get; set; } = string.Empty;
        public string? PostalCode { get; set; }
    }

    // Basic null-conditional
    public string? GetCity(Person? person)
    {
        // Returns null if person or Address is null
        return person?.Address?.City;
    }

    // With indexers
    public string? GetFirstPhone(Person? person)
    {
        // Returns null if person, PhoneNumbers is null, or empty
        return person?.PhoneNumbers?[0];
    }

    // With method calls
    public int? GetNameLength(Person? person)
    {
         person?.Name.Length;
    }

    
    
    {
         person?.Address?.City ?? ;
    }

    
     ? GetFirstItem([]? items)
    {
         items?[];
    }

    
    
    {
        callback?.Invoke();
    }

    
      EventHandler? DataChanged;

    
    {
        DataChanged?.Invoke(, EventArgs.Empty);
    }

    
    
    {
        ? result = person?
            .Address?
            .City
            .ToUpper()
            .Substring(, );
    }
}

Null Handling Patterns

Common patterns for safely handling null values.

#nullable enable

using System;
using System.Collections.Generic;
using System.Diagnostics.CodeAnalysis;

public class NullHandlingPatterns
{
    // Null object pattern
    public interface ILogger
    {
        void Log(string message);
    }

    public class ConsoleLogger : ILogger
    {
        public void Log(string message) =>
            Console.WriteLine(message);
    }

    public class NullLogger : ILogger
    {
        public void Log(string message) { }
    }

    // Guard clauses
    public void ProcessData(string? data)
    {
        if (data == null)
        {
            throw new ArgumentNullException(nameof(data));
        }

        // data is non-null here
        Console.WriteLine(data.Length);
    }

    // Early return
    public  ()
    {
         (data == )  .Empty;

         data.ToUpper();
    }

    
    
    {
        
         (key == )
        {
             = ;
             ;
        }

         = ;
         ;
    }

    
    {
         (TryGetValue(,  ? result))
        {
            
            Console.WriteLine(result.Length);
        }
    }

    
     ? _cachedValue;

    []
    
    {
        _cachedValue ??= LoadValue();
    }

    
    {
        EnsureCacheLoaded();
        
        Console.WriteLine(_cachedValue.Length);
    }

    
    []
     ? Transform(? input)
    {
         input?.ToUpper();
    }

    
      _name = .Empty;

    []
      Name
    {
         => _name;
         => _name =  ?? .Empty;
    }

     => ;
}

Nullable Annotations

Attributes that provide additional null-state information to the compiler.

#nullable enable

using System.Diagnostics.CodeAnalysis;
using System.Collections.Generic;

public class NullableAnnotations
{
    // NotNull - parameter won't be null when method returns
    public void Initialize([NotNull] ref string? value)
    {
        value ??= "default";
    }

    // MaybeNull - return may be null despite non-nullable type
    [return: MaybeNull]
    public T GetDefaultValue<T>()
    {
        return default(T);
    }

    // DoesNotReturn - method never returns normally
    [DoesNotReturn]
    public void ThrowError(string message)
    {
        throw new System.InvalidOperationException(message);
    }

    public void UseDoesNotReturn(string? value)
    {
        if (value == null)
        {
            ThrowError("Value is null");
        }

        // Compiler knows value is not null here
        System.Console.WriteLine(value.Length);
    }

    // MemberNotNullWhen
     ? _data;

    []
    
    {
         _data != ;
    }

    
    {
         (IsDataLoaded())
        {
            
            System.Console.WriteLine(_data.Length);
        }
    }

    
    []
     ? ProcessString(? source)
    {
         source?.Trim();
    }
}

Migration Strategies

Strategies for adopting nullable reference types in existing code.

// Gradual migration approach

// File 1: Keep nullability disabled
#nullable disable

public class LegacyClass
{
    public string Name { get; set; }  // Implicitly nullable
}

#nullable restore

// File 2: Enable nullability for new code
#nullable enable

public class ModernClass
{
    public string Name { get; set; } = string.Empty;  // Non-nullable
    public string? MiddleName { get; set; }  // Explicitly nullable
}

#nullable restore

// File 3: Suppress warnings during migration
#nullable enable

public class MigratingClass
{
    // Suppress specific warnings
    #pragma warning disable CS8618
    public string Name { get; set; }
    #pragma warning restore CS8618

    // Or use ! operator temporarily
    public string GetName() => Name!;
}

Working with External Libraries

Handling nullability when working with libraries that don't use nullable annotations.

#nullable enable

using System;

public class ExternalLibraryHandling
{
    // Assume external library method
    // public string GetData() { ... }

    // Defensive programming
    public void UseExternalLibrary()
    {
        // Treat return as potentially null
        string? data = GetExternalData();

        if (data != null)
        {
            ProcessData(data);
        }
    }

    // Create wrappers
    public string? GetExternalDataSafe()
    {
        string result = GetExternalData();
        return string.IsNullOrEmpty(result) ? null : result;
    }

    // Extension methods for safety
    public static class StringExtensions
    {
        public static string OrEmpty(this string? value)
        {
            return value ?? string.Empty;
        }

        public static bool IsNullOrEmpty(
            [NotNullWhen(false)] this string? )
        {
             .IsNullOrEmpty();
        }
    }

     => ;
     { }
}

Best Practices

1. Enable nullable reference types in new projects from the start
2. Use string? for optional string parameters and return values
3. Initialize non-nullable properties in constructors or with default values
4. Prefer null-coalescing operators over explicit null checks
5. Use NotNullWhen attribute for TryGet pattern methods
6. Validate arguments early with guard clauses
7. Use ThrowIfNull helper for parameter validation
8. Avoid using ! operator unless absolutely certain value is non-null
9. Leverage compiler warnings to find potential null reference issues
10. Document nullability expectations in public APIs

Common Pitfalls

1. Using ! operator to silence warnings without ensuring non-null
2. Not initializing non-nullable properties in all constructors
3. Returning null from methods declared with non-nullable return types
4. Forgetting to check for null before dereferencing nullable references
5. Mixing nullable and non-nullable contexts causing confusion
6. Over-using nullable types when default values would suffice
7. Not propagating null checks through method chains
8. Assuming external library methods respect nullability
9. Ignoring nullable warnings during migration
10. Using #pragma warning disable too broadly

When to Use Nullable Types

Use nullable types when you need:

• Representing the absence of a value distinctly from default value
• Database fields that can be NULL mapped to C# properties
• Optional parameters in methods and constructors
• API responses that may or may not contain data
• Preventing null reference exceptions at compile time
• Gradual migration of legacy code to null-safe patterns
• Clear contracts about which values can be null
• Type-safe handling of optional configuration values
• Integration with external APIs that may return null
• Functional programming patterns with Option/Maybe types

Resources

• Nullable Reference Types
• Nullable Attributes
• Migrating to Nullable References
• C# Null Safety