dotnet-csharp-nullable-reference-types

Name: dotnet-csharp-nullable-reference-types
Author: wshaddix

65stars10forks

How to install dotnet-csharp-nullable-reference-types?

wshaddix/dotnet-skills/dotnet-csharp-nullable-reference-types

$npx -y skills add wshaddix/dotnet-skills --skill dotnet-csharp-nullable-reference-types

Installs into the current project.

Summary

Enabling nullable reference types. Annotation strategies, attributes, common agent mistakes.

Files · 1

View on GitHub

SKILL.md

1	# dotnet-csharp-nullable-reference-types
2
3	Nullable reference type (NRT) annotation strategies, migration guidance for legacy codebases, and the most common annotation mistakes AI agents make. NRT is enabled by default in all modern .NET templates (net6.0+), but many existing codebases still need migration.
4
5	Cross-references: [skill:dotnet-csharp-coding-standards] for null-handling style, [skill:dotnet-csharp-modern-patterns] for pattern matching with nulls.
6
7	---
8
9	## Quick Reference: NRT Defaults by TFM
10
11	\| TFM \| `<Nullable>` default \| Notes \|
12	\|-----\|---------------------\|-------\|
13	\| net8.0+ \| `enable` (in templates) \| New projects have NRT enabled by default \|
14	\| net6.0/net7.0 \| `enable` (in templates) \| Same as net8.0 \|
15	\| netstandard2.0/2.1 \| not set \| Must opt in explicitly \|
16	\| net48 / older \| not set \| Must opt in explicitly \|
17
18	Important: The TFM does not enforce NRT -- the `<Nullable>enable</Nullable>` MSBuild property does. Legacy projects upgraded to net8.0 may not have it enabled.
19
20	---
21
22	## Enabling NRT
23
24	### Project-Wide (Recommended)
25
26	```xml
27	<!-- In .csproj or Directory.Build.props -->
28	<PropertyGroup>
29	<Nullable>enable</Nullable>
30	</PropertyGroup>
31	```
32
33	### Per-File (Migration)
34
35	```csharp
36	#nullable enable // top of file -- enables NRT for this file only
37	```
38
39	### Migration Strategy
40
41	For large codebases, enable NRT incrementally:
42
43	1. Set `<Nullable>enable</Nullable>` in the project
44	2. Add `#nullable disable` at the top of every existing file (script or IDE tooling)
45	3. Remove `#nullable disable` file-by-file, fixing warnings as you go
46	4. Track progress: count remaining `#nullable disable` directives
47
48	---
49
50	## Annotation Patterns
51
52	### Nullable and Non-Nullable
53
54	```csharp
55	public class UserService
56	{
57	// Non-nullable: must never be null
58	private readonly IUserRepository _repo;
59
60	// Nullable: explicitly may be null
61	public User? FindByEmail(string email)
62	{
63	return _repo.FindByEmail(email); // may return null
64	}
65
66	// Non-nullable parameter: caller must provide non-null
67	public async Task<User> GetByIdAsync(int id, CancellationToken ct = default)
68	{
69	return await _repo.GetByIdAsync(id, ct)
70	?? throw new NotFoundException($"User {id} not found");
71	}
72	}
73	```
74
75	### Nullable Attributes
76
77	Use attributes from `System.Diagnostics.CodeAnalysis` to express nullability contracts the compiler cannot infer:
78
79	```csharp
80	using System.Diagnostics.CodeAnalysis;
81
82	// Output is non-null when method returns true
83	public bool TryGetValue(string key, [NotNullWhen(true)] out string? value)
84	{
85	value = _dict.GetValueOrDefault(key);
86	return value is not null;
87	}
88
89	// Guarantees member is non-null after method returns
90	public class Connection
91	{
92	public string? ConnectionString { get; private set; }
93
94	[MemberNotNull(nameof(ConnectionString))]
95	public void Initialize(string connectionString)
96	{
97	ConnectionString = connectionString
98	?? throw new ArgumentNullException(nameof(connectionString));
99	}
100	}
101
102	// Return is non-null if input is non-null
103	[return: NotNullIfNotNull(nameof(input))]
104	public static string? Trim(string? input)
105	{
106	return input?.Trim();
107	}
108
109	// Parameter must not be null when method returns (for assertion methods)
110	public static void EnsureNotNull([NotNull] object? value, string paramName)
111	{
112	if (value is null)
113	{
114	throw new ArgumentNullException(paramName);
115	}
116	}
117
118	// Method never returns normally (always throws)
119	[DoesNotReturn]
120	public static void ThrowNotFound(string message)
121	{
122	throw new NotFoundException(message);
123	}
124	```
125
126	### Common Attributes Summary
127
128	\| Attribute \| Where \| Meaning \|
129	\|-----------\|-------\|---------\|
130	\| `[NotNullWhen(true)]` \| `out` parameter \| Non-null when method returns `true` \|
131	\| `[NotNullWhen(false)]` \| `out` parameter \| Non-null when method returns `false` \|
132	\| `[MemberNotNull]` \| method \| Named member is non-null after call \|
133	\| `[MemberNotNullWhen(true)]` \| method \| Named member is non-null when returns `true` \|
134	\| `[NotNullIfNotNull]` \| return \| Return is non-null if named param is non-null \|
135	\| `[NotNull]` \| parameter \| Parameter is non-null after call (assertion) \|
136	\| `[DoesNotReturn]` \| method \| Method never returns (always throws) \|
137	\| `[AllowNull]` \| parameter/property \| Caller may pass null even if type is non-nullable \|
138	\| `[DisallowNull]` \| parameter/property \| Caller must not pass null even if type is nullable \|
139	\| `[MaybeNull]` \| return/out \| Return may be null even if type is non-nullable \|
140	\| `[MaybeNullWhen(false)]` \| `out` parameter \| May be null when method returns `false` \|
141
142	---
143
144	## Agent Gotchas
145
146	These are the most common NRT mistakes AI agents make when generating C# code.
147
148	### 1. Using `!` (Null-Forgiving Operator) to Silence Warnings
149
150	```csharp
151	// WRONG -- hides real null bugs
152	var user = _repo.FindByEmail(email)!; // will throw N

People who liked this also viewed

6 picks

Type

hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, SkillsJul 2026262k37k
request-refactor-planSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026165k181k
analyze-projectRigor Analyze / Rigor Audit read-only skill for deep learning research repositories. Use when the user wants to read and understand a repository, inspect model structure and training or inference entrSkillsMay 2026161k507
explore-codeRigor Improve implementation leaf skill for auditable candidate implementation in deep learning research repositories. Use when the researcher explicitly authorizes exploratory work on an isolated braSkillsMay 2026161k507
ubiquitous-languageSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026160k181k
scaffold-exercisesSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026149k181k

dotnet-csharp-nullable-reference-types

65stars10forks

View on GitHub

How to install dotnet-csharp-nullable-reference-types?

wshaddix/dotnet-skills/dotnet-csharp-nullable-reference-types

$npx -y skills add wshaddix/dotnet-skills --skill dotnet-csharp-nullable-reference-types

Installs into the current project.

Summary

Enabling nullable reference types. Annotation strategies, attributes, common agent mistakes.

Files · 1

View on GitHub

SKILL.md

1	# dotnet-csharp-nullable-reference-types
2
3	Nullable reference type (NRT) annotation strategies, migration guidance for legacy codebases, and the most common annotation mistakes AI agents make. NRT is enabled by default in all modern .NET templates (net6.0+), but many existing codebases still need migration.
4
5	Cross-references: [skill:dotnet-csharp-coding-standards] for null-handling style, [skill:dotnet-csharp-modern-patterns] for pattern matching with nulls.
6
7	---
8
9	## Quick Reference: NRT Defaults by TFM
10
11	\| TFM \| `<Nullable>` default \| Notes \|
12	\|-----\|---------------------\|-------\|
13	\| net8.0+ \| `enable` (in templates) \| New projects have NRT enabled by default \|
14	\| net6.0/net7.0 \| `enable` (in templates) \| Same as net8.0 \|
15	\| netstandard2.0/2.1 \| not set \| Must opt in explicitly \|
16	\| net48 / older \| not set \| Must opt in explicitly \|
17
18	Important: The TFM does not enforce NRT -- the `<Nullable>enable</Nullable>` MSBuild property does. Legacy projects upgraded to net8.0 may not have it enabled.
19
20	---
21
22	## Enabling NRT
23
24	### Project-Wide (Recommended)
25
26	```xml
27	<!-- In .csproj or Directory.Build.props -->
28	<PropertyGroup>
29	<Nullable>enable</Nullable>
30	</PropertyGroup>
31	```
32
33	### Per-File (Migration)
34
35	```csharp
36	#nullable enable // top of file -- enables NRT for this file only
37	```
38
39	### Migration Strategy
40
41	For large codebases, enable NRT incrementally:
42
43	1. Set `<Nullable>enable</Nullable>` in the project
44	2. Add `#nullable disable` at the top of every existing file (script or IDE tooling)
45	3. Remove `#nullable disable` file-by-file, fixing warnings as you go
46	4. Track progress: count remaining `#nullable disable` directives
47
48	---
49
50	## Annotation Patterns
51
52	### Nullable and Non-Nullable
53
54	```csharp
55	public class UserService
56	{
57	// Non-nullable: must never be null
58	private readonly IUserRepository _repo;
59
60	// Nullable: explicitly may be null
61	public User? FindByEmail(string email)
62	{
63	return _repo.FindByEmail(email); // may return null
64	}
65
66	// Non-nullable parameter: caller must provide non-null
67	public async Task<User> GetByIdAsync(int id, CancellationToken ct = default)
68	{
69	return await _repo.GetByIdAsync(id, ct)
70	?? throw new NotFoundException($"User {id} not found");
71	}
72	}
73	```
74
75	### Nullable Attributes
76
77	Use attributes from `System.Diagnostics.CodeAnalysis` to express nullability contracts the compiler cannot infer:
78
79	```csharp
80	using System.Diagnostics.CodeAnalysis;
81
82	// Output is non-null when method returns true
83	public bool TryGetValue(string key, [NotNullWhen(true)] out string? value)
84	{
85	value = _dict.GetValueOrDefault(key);
86	return value is not null;
87	}
88
89	// Guarantees member is non-null after method returns
90	public class Connection
91	{
92	public string? ConnectionString { get; private set; }
93
94	[MemberNotNull(nameof(ConnectionString))]
95	public void Initialize(string connectionString)
96	{
97	ConnectionString = connectionString
98	?? throw new ArgumentNullException(nameof(connectionString));
99	}
100	}
101
102	// Return is non-null if input is non-null
103	[return: NotNullIfNotNull(nameof(input))]
104	public static string? Trim(string? input)
105	{
106	return input?.Trim();
107	}
108
109	// Parameter must not be null when method returns (for assertion methods)
110	public static void EnsureNotNull([NotNull] object? value, string paramName)
111	{
112	if (value is null)
113	{
114	throw new ArgumentNullException(paramName);
115	}
116	}
117
118	// Method never returns normally (always throws)
119	[DoesNotReturn]
120	public static void ThrowNotFound(string message)
121	{
122	throw new NotFoundException(message);
123	}
124	```
125
126	### Common Attributes Summary
127
128	\| Attribute \| Where \| Meaning \|
129	\|-----------\|-------\|---------\|
130	\| `[NotNullWhen(true)]` \| `out` parameter \| Non-null when method returns `true` \|
131	\| `[NotNullWhen(false)]` \| `out` parameter \| Non-null when method returns `false` \|
132	\| `[MemberNotNull]` \| method \| Named member is non-null after call \|
133	\| `[MemberNotNullWhen(true)]` \| method \| Named member is non-null when returns `true` \|
134	\| `[NotNullIfNotNull]` \| return \| Return is non-null if named param is non-null \|
135	\| `[NotNull]` \| parameter \| Parameter is non-null after call (assertion) \|
136	\| `[DoesNotReturn]` \| method \| Method never returns (always throws) \|
137	\| `[AllowNull]` \| parameter/property \| Caller may pass null even if type is non-nullable \|
138	\| `[DisallowNull]` \| parameter/property \| Caller must not pass null even if type is nullable \|
139	\| `[MaybeNull]` \| return/out \| Return may be null even if type is non-nullable \|
140	\| `[MaybeNullWhen(false)]` \| `out` parameter \| May be null when method returns `false` \|
141
142	---
143
144	## Agent Gotchas
145
146	These are the most common NRT mistakes AI agents make when generating C# code.
147
148	### 1. Using `!` (Null-Forgiving Operator) to Silence Warnings
149
150	```csharp
151	// WRONG -- hides real null bugs
152	var user = _repo.FindByEmail(email)!; // will throw N

People who liked this also viewed

6 picks

Type