Nullable-аннотации: MaybeNull и NotNullWhen в C#

Привет, Хабр!

Сегодня мы рассмотрим nullable‑аннотации в C#: как с помощью [MaybeNull] и [NotNullWhen] (плюс родственных атрибутов вроде [MaybeNullWhen], [NotNullIfNotNull], [DoesNotReturn]) формально описывать те самые «ну тут иногда null, а тут точно нет».

MaybeNull — когда null возвращается, но не всегда

Атрибут [MaybeNull] из System.Diagnostics.CodeAnalysis говорит статическому анализатору: «на выходе этого члена (return, out, поле, свойство, параметр по ref) может оказаться null — даже если сам тип объявлен как необнуляемый». Это важно для обратной совместимости и для API, где сигнатура по типу остаётся строгой (например, T, User, string), но фактический контракт допускает отсутствие значения. Компилятор учитывает эту подсказку в nullable flow analysis и, увидев [MaybeNull], будет предупреждать о потенциальном null при дальнейшем использовании результата без проверки.

Чем это отличается от T? / User?? Суффикс ? меняет сам тип в системе типов — объявляете значение как nullable reference (или nullable value wrapper, если речь о struct?). [MaybeNull] же не меняет тип, а расширяет контракт анализа: «смотри, даже если тип формально non‑nullable, относись к факту как к потенциально null». Это важно в дженериках и местах, где тип параметра не может (или не должен) быть помечен ?, например при открытых ограничениях T, библиотеках общего назначения, или когда вы хотите сохранить сигнатуру совместимой с до‑nullable кодом, но дать современным компиляторам правильный сигнал.

Простой пример. Допустим, есть метод, который возвращает объект, но null может вернуться, если что‑то пошло не так:

using System.Diagnostics.CodeAnalysis;  public sealed class UserRepository {     [return: MaybeNull]     public User GetUserOrNull(int id)     {         // если не нашли — возвращаем null,         // хотя тип сигнатуры формально User (не User?)         return id > 0 ? new User(id) : null;     } }

Намеренно убрали User? из сигнатуры. Тип остаётся non‑nullable, но атрибут сообщает анализатору о возможности null. Если можно изменить тип — естественно, запишите User? и не усложняйте. [MaybeNull] нужен там, где не можете (совместимость, дженерики, API‑контракты).

Где атрибут спасает

Классика — универсальный метод поиска:

using System.Diagnostics.CodeAnalysis; using System.Collections.Generic; using System.Linq;  public static class SeqExtensions {     [return: MaybeNull]     public static T FindOrDefault<T>(this IEnumerable<T> source, Func<T, bool> predicate)     {         // Возвращает первый подходящий элемент или null / default(T)         // По контракту: может отсутствовать.         foreach (var item in source)         {             if (predicate(item))                 return item;         }         return default;     } }

Почему не T?? Потому что T не ограничен: сюда может прийти и value‑type (int), и reference‑type (string), и nullable типы. Записать T? легально только в тех местах, где это корректно по ограничениям. [MaybeNull] позволит статическому анализу предупредить вызвавший код о том, что возвращаемое может быть пустым значением (default) — что для ссылочных типов значит null.

Сравнение вариантов

Помните, что default для value‑типа не null, а нулевая структура. Поэтому [MaybeNull] на T фактически означает: «вызвавший код обязан обработать значение по умолчанию», а если T — ссылочный тип, то это будет null. Это заметно в generic‑коллекциях и при работе с API уровня сериализации / кэшей, где вы не знаете заранее, что за T придёт.

Быстрая проверка в потребителе

var user = repo.GetUserOrNull(id); if (user is null) {     // handle miss     return NotFound(); } // здесь анализатор знает: user not null (после проверки) return Ok(user);

Если убрать [MaybeNull] (и не использовать User?), компилятор может считать user гарантированно non‑null и подсветить проверку как лишнюю, или — наоборот — пропустить предупреждение там, где оно нужно, в зависимости от контекста и nullable режима, в котором компилировался исходный код библиотеки.

NotNullWhen — про условные гарантии

Атрибут [NotNullWhen(bool)] из System.Diagnostics.CodeAnalysis — это условный постконтракт на параметр (обычно out или ref), объявленный как nullable в сигнатуре. Он сообщает анализатору: «если метод вернул указанное булево значение, то этот параметр гарантированно не null». Тип при этом не меняется: он остаётся, например, User?, но после проверки if (TryX(...)) компилятор переключает null‑state переменной в «not‑null» и перестаёт требовать защитные проверки.

Чем полезен по сравнению с ручными if (x == null)? Во‑первых, информация «параметр точно не null при возврате X» становится частью публичного API, а не рассыпана по комментариям. Во‑вторых, статический анализ начинает правильно вести поток null‑состояний, сокращая ложные предупреждения и подсвечивая реальные нарушения (например, если внутри метода вы когда‑то забудете проинициализировать out при «успехе», анализатор может поймать это).

Try-паттерн

public bool TryGetUser(int id, [NotNullWhen(true)] out User? user) {     if (id > 0)     {         user = new User(id);         return true;     }      user = null;     return false; }

Использование:

if (repo.TryGetUser(id, out var user)) {     // Здесь компилятор знает: user не null     Console.WriteLine(user.Name); } else {     // Здесь user может быть null }

Благодаря [NotNullWhen(true)] после проверки if (TryGetUser(...)) IDE не требует user! или отдельного null‑чека. Это ровно то, что делается внутри платформенных TryParse, TryGetValue и похожих API.

Вариант с отрицательным условием: [NotNullWhen(false)]

Необязательно привязываться к true. Классический пример — методы вида IsNullOrEmpty / IsNullOrWhiteSpace: когда они возвращают false, значит значение не пустое и не null. Сигнатура выглядит так:

public static bool IsNullOrWhiteSpace([NotNullWhen(false)] string? value);

После вызова:

if (!string.IsNullOrWhiteSpace(s)) {     // тут s гарантированно не null и не пустая     Use(s); }

Компилятор корректно подхватывает эту гарантию благодаря атрибуту. Используйте false там, где «успешный» для вас сценарий — отрицательный результат проверки.

NotNullWhen(true) vs MaybeNullWhen(false)?

Иногда кажется, что «не null при true» и «может быть null при false» — одно и то же. На практике разница проявляется в нулл‑аннотации параметра и в исторических ограничениях языка. NotNullWhen применяется к nullable параметру, чтобы сузить состояние до non‑null в ветке. MaybeNullWhen применяется к non‑nullable параметру/типу, чтобы расширить состояние до «может быть null» в ветке. В ранних версиях языка (до возможности T? на универсальных аргументах) [MaybeNullWhen(false)] использовали, чтобы выразить Try‑паттерн для обобщённых API; сейчас выбор — дело читаемости и точности контракта: если параметр в сигнатуре уже nullable, ставьте [NotNullWhen(success)]; если тип строгий, но при ошибке вы вынуждены писать default/null, используйте [MaybeNullWhen(failure)].

Дженерики и подводные камни

В обобщённом Try‑методе:

public static bool TryGet<T>(int id, [NotNullWhen(true)] out T? value) {     // ... }

Работает, но требует C# с поддержкой nullable‑суффикса на T? (а T должен попадать под nullable‑аннотацию контекста). Если вы держите код совместимым со старой сигнатурой out T value или у вас ограничения на T, вместо этого нередко используют:

public static bool TryGet<T>(int id, [MaybeNullWhen(false)] out T value) {     // ... }

Так вы даёте понять: при false вызывающий код не должен рассчитывать на корректность объекта (может быть default). Еще это уместно, когда T может оказаться value‑типом или уже nullable‑типом, и обещать «всегда non‑null при true» было бы слишком смело.

Мини-guard-утилита в стиле IsNotNull

Часто хочется утилиту «верни true, если объект не null, и заодно подскажи анализатору». Без атрибута в месте вызова всё равно придётся писать проверку; с атрибутом — нет:

private static bool IsNotNull<T>([NotNullWhen(true)] T? value) => value is not null;

Использование:

if (IsNotNull(someString)) {     // здесь someString не null     Console.WriteLine(someString.Length); }

В MS Learn прямо написано о том, что такой подход лучше вместо спама оператором подавления !, потому что контракт становится декларативным и повторно используемым.

Несколько out-параметров

Атрибут ставится на каждый параметр отдельно — анализ ведётся независимо:

public bool TryLoadPair(     string key,     [NotNullWhen(true)] out User? user,     [NotNullWhen(true)] out Profile? profile) {     if (_store.TryGet(key, out user, out profile)) return true;     user = null;     profile = null;     return false; }

В успешной ветке оба считаются not‑null; в неуспешной — оба nullable. Дальше можно разнести логику по месту использования без дополнительного if (user != null && profile != null) после проверки результата. (Разумеется, если внутри метода вы нарушите обещание и оставите что‑то null при возврате true, статический анализатор это не остановит на рантайме — контракт на вашей совести.)

Соединяем с проверками аргументов

Иногда удобно комбинировать NotNullWhen(false) и автоматическую проверку в одном helper’е:

public static bool IsNullOrEmpty([NotNullWhen(false)] string? value)     => string.IsNullOrEmpty(value);

Компилятор читает: если вернули false, то value точно не null — а дальше уже на вызывающем месте вы можете либо работать со строкой, либо быстро выйти. Удобно в guard‑методах валидации DTO или параметров контроллеров.

Когда ставить какой атрибут в Try-методах

NotNullIfNotNull — когда возвращаемое зависит от входного

Ещё один классный контракт, который читается как: «если входной аргумент not null, то и возвращаемое значение not null».

[return: NotNullIfNotNull("input")] public string? Normalize(string? input) {     return input?.Trim(); }

Так можно дать компилятору понять, что Normalize(something) не может вернуть null, если something был не null.

DoesNotReturn — говорим компилятору: “дальше код не пойдёт”

Бывают такие методы, после которых никакой код не должен выполняться. Например, throw‑методы, типа FailFast.

[DoesNotReturn] public static void ThrowInvalidOperation() {     throw new InvalidOperationException("Это конец."); }

Если вы используете ThrowInvalidOperation() в условии:

if (someConditionIsBad) {     ThrowInvalidOperation(); } Console.WriteLine("Я не unreachable — компилятор знает об этом.");

Без DoesNotReturn компилятор мог бы жаловаться, что после if возможно выполнение дальше, хотя на деле — нет.

---

Итоги

Nullable‑аннотации — это способ вшить в код реальные договорённости о значениях: MaybeNull расширяет контракт там, где тип формально не допускает отсутствия данных; NotNullWhen (и компания вроде NotNullIfNotNull, MaybeNullWhen) сужают поток до гарантированно инициализированных объектов в нужных ветках; DoesNotReturn поясняет анализатору контроль потока. Итог — меньше ложных предупреждений, чище публичные API, меньше неявных ! и ловля «пустых» сценариев до рантайма. Делитесь опытом в комментариях: где эти атрибуты реально помогли, какие грабли встретили при миграции на #nullable, и какие внутренние практики договорились использовать в команде.

Если вы работаете с C# и хотите глубже разобраться в возможностях языка — включая тонкости работы с nullable‑аннотациями, контрактами типов и поведением компилятора — обратите внимание на курс «C# углублённый». Он позволит системно подойти к изучению языка и точнее формулировать поведение кода на уровне сигнатур и API.

Также рекомендуем заглянуть в каталог курсов по программированию — там собраны программы для тех, кто работает с кодом в самых разных направлениях.

Чтобы оставаться в курсе самых актуальных технологий и трендов, подписывайтесь на Telegram-канал OTUS.