# Csharp Nullable Reference Types

Guidelines for introducing and using nullable reference types (NRT) and...

- Repository: https://github.com/Aaronontheweb/dotnet-skills (1244 stars)
- Category: Design
- License: MIT
- Last updated: 2026-10-28
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add Aaronontheweb/dotnet-skills --skill csharp-nullable-reference-types -g -a claude-code -y`
Codex: `npx skills add Aaronontheweb/dotnet-skills --skill csharp-nullable-reference-types -g -a codex -y`
Cursor: `npx skills add Aaronontheweb/dotnet-skills --skill csharp-nullable-reference-types -g -a cursor -y`
Gemini CLI: `npx skills add Aaronontheweb/dotnet-skills --skill csharp-nullable-reference-types -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add Aaronontheweb/dotnet-skills`

## Description

Guidelines for introducing and using nullable reference types (NRT) and System.Diagnostics.CodeAnalysis nullable attributes in C# / .NET codebases. Covers the nullability model, flow analysis, the null-forgiving operator, API design rules, the full attribute catalog (AllowNull, DisallowNull, MaybeNull, NotNull, NotNullWhen, MaybeNullWhen, NotNullIfNotNull, MemberNotNull, MemberNotNullWhen, DoesNotReturn, DoesNotReturnIf), the C# 14 field keyword, incremental migration of legacy codebases, and a code-generation checklist.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# C# Nullable Reference Types

## When to Use

- Introducing nullable reference types (NRT) into a codebase that has not yet adopted them
- Writing or refactoring C# code that uses `T?` / nullable annotations
- Annotating APIs with `System.Diagnostics.CodeAnalysis` nullable attributes
- Designing public/internal APIs where nullability contracts matter
- Wrapping unannotated or legacy APIs so downstream callers still benefit from NRT
- Reviewing code for correct null-state analysis, guard helpers, and the `field` keyword

## Core Goals

- Prevent `NullReferenceException` at runtime by making null intent explicit in signatures.
- Express contracts the type system cannot represent directly using the official nullable attributes.
- Adopt NRT incrementally in legacy codebases without a big-bang rewrite.

## Core Nullability Model

### Non-nullable vs nullable

- `string`, non-nullable reference. The compiler assumes instances are never `null`; assigning `null` or a maybe-null value produces a warning.
- `string?`, nullable reference. The variable may be `null`; the compiler requires a null check before dereference.

```csharp
string name = "Alice";
name = null;          // Warning: assigning null to non-nullable.

string? nickname = null;
Console.WriteLine(nickname.Length); // Warning: possible null dereference.
```

### Null-state analysis (flow)

The compiler tracks whether a reference is *definitely non-null* or *maybe null*. Null checks and assignments update this state.

```csharp
string? message = GetMessageOrNull();

if (message != null)
{
    // message is definitely non-null in this block.
    Console.WriteLine(message.Length);
}

// Outside the if, message is maybe null again.
```

The rest: https://github.com/Aaronontheweb/dotnet-skills/blob/HEAD/skills/csharp-nullable-reference-types/SKILL.md