К основному содержанию
скилл CX Codex

csharp-nullable-reference-types — скилл для Claude Code

Скилл csharp-nullable-reference-types помогает внедрять nullable reference types в C#, настраивать flow-анализ и расставлять атрибуты из System.Diagnostics.CodeAnalysis без лишних правок.

MIT 165 установок ★ 1 271 обновлён 2026-10-11

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add Aaronontheweb/dotnet-skills --skill csharp-nullable-reference-types -a claude-code
Открыть на GitHub

Что делает csharp-nullable-reference-types

Скилл задаёт правила работы с ссылочными типами, допускающими null: от включения <Nullable>enable</Nullable> в .csproj до использования директив вроде #nullable enable в старых проектах. Агент учится не глушить предупреждения компилятора оператором !, а строить безопасный поток исполнения через проверки is not null, guard clauses и локальные переменные.

Внутри собраны правила оформления публичных и внутренних API, включая работу со свойствами required и проверками вроде ArgumentNullException.ThrowIfNull. Описаны сценарии применения атрибутов AllowNull, DisallowNull, NotNullWhen, MemberNotNull и поддержка ключевого слова field из C# 14. Скилл предупреждает: изменение аннотаций в библиотеках сохраняет бинарную совместимость, но способно сломать сборку зависимых проектов, если у них включён TreatWarningsAsErrors.

Какие задачи решает

  • перевести проект на C# Nullable Reference Types без переписывания всей кодовой базы
  • подобрать nullable-атрибуты для сложных контрактов методов
  • устранить предупреждения CS86xx без бездумного подавления через оператор выкрика
  • спроектировать публичные сигнатуры методов с явными контрактами на null

Примеры запросов агенту

  • Разметь nullable-типы и атрибуты для публичного API в файле OrderService.cs
  • Помоги переписать методы с предупреждениями компилятора CS8602 без использования оператора !
  • Добавь атрибуты из System.Diagnostics.CodeAnalysis для методов валидации параметров

Как установить csharp-nullable-reference-types

1Через Skills CLI (Vercel)

npx skills add Aaronontheweb/dotnet-skills --skill csharp-nullable-reference-types -a claude-code

2Вручную: положить файлы

~/.claude/skills/csharp-nullable-reference-types/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/csharp-nullable-reference-types/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о csharp-nullable-reference-types

Как установить csharp-nullable-reference-types в Claude Code?

Выполните команду npx skills add Aaronontheweb/dotnet-skills --skill csharp-nullable-reference-types -a claude-code.

Что делает этот скилл?

Он направляет ИИ при рефакторинге и проектировании C#-кода, обучая использовать системные атрибуты проверки на null и избегать оператора !.

Ломает ли добавление NRT обратную совместимость публичных библиотек?

Бинарная совместимость сохраняется, потому что типы T и T? одинаковы для CLR. При этом сборка у клиентов может упасть, если в их проектах включён режим TreatWarningsAsErrors.

Исходный текст

SKILL.md · MIT
---
name: csharp-nullable-reference-types
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.
version: 1.0.0
tags:
  - csharp
  - nullable
  - nrt
  - code-quality
  - api-design
---

# 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.
```

Introduce explicit null checks (`if (x != null)`, `is not null`, pattern matching) before dereferencing nullable values. Narrow nullability early and keep the non-null state alive. **Null-conditional assignment (C# 14)** lets you write `customer?.Order = CreateOrder();` — the right side is evaluated only when the receiver is non-null.

### Null-forgiving operator (`!`)

`x!` tells the compiler "treat `x` as non-null here." It affects analysis only, not runtime behavior.

- Use `!` only when a real invariant guarantees non-null and the compiler cannot see it.
- Do **not** use `!` as a general fix for warnings. Prefer refactoring control flow, adding attributes, or proper member initialization.

```csharp
_customer = LoadCustomerFromOrm()!; // ORM guarantees this is not null in valid state.
```

### Reorganize code before suppressing warnings

A successful guard clause or pattern match already creates a null-safe region in the current scope. Before adding `!`, make nullable values cross a checked boundary once and keep the remaining code non-nullable:

- narrow early with a guard clause or pattern match;
- copy nullable fields or properties to a local before checking, so repeated reads cannot change underneath the analysis;
- when a method has complex control flow, optionally move the non-null path into a local function or private method with non-nullable parameters;
- keep nullable handling at the boundary instead of spreading `T?`, repeated checks, or `!` through the implementation.

```csharp
public void Process(Order? order)
{
    if (order?.Customer is not { } customer)
    {
        return;
    }

    // The pattern match already proved that customer is non-null here.
    Console.WriteLine(customer.Name);
}
```

Do not extract a function solely to satisfy nullable analysis. Use an explicit non-nullable function boundary when it also simplifies a large or branching implementation. Use `!` only when a real external invariant cannot be represented through control flow, signatures, or nullable-analysis attributes.

## Project Configuration

Enable NRT for new code:

```xml
<PropertyGroup>
  <Nullable>enable</Nullable>
</PropertyGroup>
```

For legacy codebases, enable incrementally with file-level directives (`#nullable enable`, `#nullable disable`, `#nullable enable warnings`, `#nullable enable annotations`). Treat `CS86xx` nullable warnings as important; consider `TreatWarningsAsErrors` or treating nullable warnings as errors in new projects.

See [nrt-migration-playbook-reference.md](nrt-migration-playbook-reference.md) for the full incremental-adoption strategy, `#nullable` directive reference, legacy interop, and known static-analysis limitations (arrays, `default(struct)`).

## API Design Rules (Signatures)

These rules apply to public and internal APIs and to models.

**Parameters** — if `null` is not allowed, use a non-nullable type and add a runtime guard for public APIs:

```csharp
public void SendEmail(string recipient)
{
    ArgumentNullException.ThrowIfNull(recipient);
    // Implementation
}
```

If `null` is allowed and meaningful, use `T?`, document how `null` is interpreted, and implement correct `null` behavior.

**Return types** — `Customer` when the method never returns `null`; `Customer?` when it can legitimately return `null` (callers must check, and the compiler enforces it).

```csharp
public Customer GetRequiredCustomer(Guid id);  // Throws on failure.
public Customer? TryGetCustomer(Guid id);       // Returns null on failure.
```

**Properties and fields** — follow the same rules as parameters and return types. Non-nullable members must be initialized in constructors, via `required` properties with object initializers, via `field`-backed lazy properties, or via helpers annotated with `[MemberNotNull]`.

```csharp
public class Order
{
    public required string Id { get; init; }
    public required Customer Customer { get; init; }
    public string? Comment { get; init; } // Optional.
}
```

When contracts depend on input/output behavior, conditional behavior, or member initialization, apply the nullable attributes described in [nullable-attributes-reference.md](nullable-attributes-reference.md).

### Public API compatibility for libraries

Treat nullable annotations and nullable-analysis attributes as part of a shipped API contract. `T` and `T?` have the same CLR type, so annotation-only changes are generally binary compatible, but they can be source breaking by introducing warnings for nullable-enabled consumers. Those warnings often become build failures when consumers treat warnings as errors.

Review public nullability changes before release, especially:

- weakening an output from `T` to `T?` or adding `[MaybeNull]`;
- tightening an input from `T?` to `T` or adding `[DisallowNull]`;
- changing generic constraints such as `class?`, `class`, or `notnull`;
- changing annotations or attributes on virtual members, interfaces, delegates, and implementations, where mismatches produce compiler warnings.

Adding annotations to a previously nullable-oblivious API can create the same source-compatibility problems. Compare the annotated surface with the last released version, test a nullable-enabled consumer, and document or version intentional source-breaking changes according to the library's compatibility policy.

## The `field` Keyword (C# 14 / .NET 10)

The `field` contextual keyword lets you write a property accessor body without declaring an explicit backing field. This is a primary NRT scenario (lazily-initialized properties) and the compiler performs a special *null-resilience* analysis so you do not get nuisance `CS8618` in constructors:

```csharp
public class C
{
    public C() { } // No warning: the getter is null-resilient.
    string Prop => field ??= GetPropValue();
}
```

See [nullable-attributes-reference.md](nullable-attributes-reference.md) for the full `field` nullability rules (null-resilient vs non-resilient getters, the `[field: AllowNull, MaybeNull]` escape hatch, and setter/constructor analysis).

## Reference Files

- [nullable-attributes-reference.md](nullable-attributes-reference.md): The complete `System.Diagnostics.CodeAnalysis` attribute catalog — preconditions (`AllowNull`, `DisallowNull`), postconditions (`MaybeNull`, `NotNull`), conditional postconditions (`NotNullWhen`, `MaybeNullWhen`, `NotNullIfNotNull`), helper methods (`MemberNotNull`, `MemberNotNullWhen`), unreachable-code helpers (`DoesNotReturn`, `DoesNotReturnIf`), and the `field` keyword nullability rules. Each with intent, pattern, and agent rules.
- [nrt-migration-playbook-reference.md](nrt-migration-playbook-reference.md): Incremental adoption strategy, `#nullable` directive reference, legacy/unannotated API interop, polyfilling nullable attributes for older target frameworks (with tradeoffs and a confirm-before-adding decision process), known static-analysis limitations (arrays of non-nullable references, `default(struct)` with reference fields), warning handling, and the full generation checklist.

## Generation Checklist (Summary)

1. **Project** — `<Nullable>enable</Nullable>` present; disable only around unavoidable legacy code.
2. **Types** — non-nullable for required params/returns/properties; `T?` only when `null` is valid and expected.
3. **Initialization** — constructors, `required` + object initializers, `field`-backed lazy getters, or `[MemberNotNull]` helpers. Avoid `null!` except as a documented escape hatch.
4. **Null checks** — explicit guards at public boundaries; narrow with control flow, and extract a non-nullable helper only when it improves complex code; `!` only with a clear invariant.
5. **Attributes** — apply to express contracts the type system cannot express (see reference file).
6. **Interop** — trust BCL/annotated libraries; add your own guards and attributes when wrapping unannotated APIs.
7. **Warnings** — never ignore; fix design or add attributes rather than suppressing with `!` or `#pragma`.
8. **Compatibility** — for released libraries, review public nullability changes as potential source breaks and test nullable-enabled consumers.

## References

- [Nullable reference types (overview)](https://learn.microsoft.com/dotnet/csharp/nullable-references)
- [Attributes for null-state static analysis](https://learn.microsoft.com/dotnet/csharp/language-reference/attributes/nullable-analysis)
- [Nullable migration strategies](https://learn.microsoft.com/dotnet/csharp/advanced-topics/update-applications/nullable-migration-strategies)
- [Breaking change: Nullable reference type annotation changes](https://learn.microsoft.com/dotnet/core/compatibility/core-libraries/6.0/nullable-ref-type-annotation-changes)
- [Tutorial: Express your design intent with nullable and non-nullable reference types](https://learn.microsoft.com/dotnet/csharp/whats-new/tutorials/nullable-reference-types)
- [What's new in C# 14](https://learn.microsoft.com/dotnet/csharp/whats-new/csharp-14) (extension members, `field` keyword GA, null-conditional assignment)
- [The `field` contextual keyword (feature spec)](https://learn.microsoft.com/dotnet/csharp/language-reference/proposals/csharp-14.0/field-keyword)

© Aaronontheweb · MIT · Aaronontheweb/dotnet-skills

Похожие скиллы

Все скиллы по теме «Языки программирования» →
migrate-nullable-references dotnet Скилл migrate-nullable-references для Claude Code и Codex: включение nullable reference types в C#-проекте и систематическое устранение всех предупреждений. CX Codex +1 4 400установок modern-csharp codewithmukesh Скилл modern-csharp для Claude Code подсказывает агенту синтаксис C# 14: первичные конструкторы, коллекционные выражения, field и блоки расширений. Помогает писать новый код и чистить старый. CX Codex +1 4 100установок csharp-refactoring dotnet Скилл csharp-refactoring для Claude Code, Codex, Cursor, GitHub Copilot и Gemini CLI, который рефакторит C#/.NET-код без изменения поведения. Переименовывает, выносит, вливает и дедуплицирует по биндингам — не по тексту. CX Codex +1 3 000установок dotnet-csharp-async-patterns wshaddix Скилл dotnet-csharp-async-patterns задаёт правила написания асинхронного кода на C# и устраняет частые ошибки нейросетей вроде блокировок через .Result или вызовов async void. CX Codex +1 136установок csharp официальный github Правило csharp для GitHub Copilot задаёт стиль C#-кода: именование, nullable-типы, форматирование и работу с ASP.NET Core. Обеспечивает единообразный код во всех файлах проекта. CX Codex +1 ★ 41 430звёзд репо csharp-pro Seth Hobson Субагент csharp-pro для Claude, Codex и Cursor, который пишет современный C# и разбирает сложные .NET-задачи: рефакторинг, async, тесты. CX Codex ★ 42 780звёзд репо

Из того же набора35

Весь набор →
verify-email-snapshots Скилл verify-email-snapshots для снапшот-тестирования HTML-писем через Verify: рендер шаблона сравнивается с утверждённым эталоном, и тест падает при расхождении. CX Codex +1 445установок akka-hosting-actor-patterns Скилл akka-hosting-actor-patterns для Claude Code задаёт паттерны сущностных акторов Akka.NET через Akka.Hosting для локальных тестов и кластерного продакшена. CX Codex +1 443установок opentelemetry-net-instrumentation Скилл opentelemetry-net-instrumentation для Claude Code расставляет трассировку, метрики и логи в .NET-коде по спецификации OpenTelemetry. Покрывает телеметрией библиотеку или приложение. CX Codex +1 442установок akka-net-testing-patterns Скилл akka-net-testing-patterns для написания юнит- и интеграционных тестов акторов Akka.NET на Akka.Hosting.TestKit: внедрение зависимостей, TestProbes, проверка персистентности. CX Codex +1 440установок akka-net-management Скилл akka-net-management подсказывает агенту, как настроить Akka.Management и Cluster Bootstrap: динамическое обнаружение узлов, health-эндпоинты, работа в Kubernetes и Azure. CX Codex +1 439установок akka-net-aspire-configuration Скилл akka-net-aspire-configuration помогает связать Akka.NET и .NET Aspire: актор-система, кластер, персистентность и Akka.Management в одном проекте. CX Codex +1 425установок marketplace-publishing Скилл marketplace-publishing для Claude Code описывает путь от новой папки со SKILL.md до тега релиза в маркетплейсе dotnet-skills. Ведёт собственный каталог плагинов. CX Codex +1 419установок r3-reactive-extensions Скилл r3-reactive-extensions помогает собирать реактивные потоки на R3 и разбираться с ошибками, асинхронным кодом и планированием событий. Пригодится при работе с UI-событиями и миграции с Rx.NET. CX Codex +1 170установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой