Catalog / Generators / add-null-checks

Add Null Checks

Adds an argument null guard at the start of a method or constructor for each reference-type parameter that is meant never to be null.

This is a generator: it changes behaviour, because a call that passed null now throws ArgumentNullException at the start of the method instead of failing later or not at all. The after/ fixtures pin one design, described below, rather than the only correct answer.

The target is the method or constructor, by symbol: "target": { "symbol": "M:Shop.Order.#ctor(Shop.Customer,System.String)" }.

Precondition

The method or constructor has a body, block or expression.
At least one parameter needs a guard: a reference type (including a type parameter constrained to a class) that is not out, not annotated as nullable, does not default to null, and is not already guarded.

Transformation

Each parameter needing one gets ArgumentNullException.ThrowIfNull(name);, in parameter order, at the top of the body, followed by a blank line before the first existing statement.
A parameter counts as already guarded when the body calls ArgumentNullException.ThrowIfNull on it, throws in an if whose condition is p == null, null == p or p is null, or uses p ?? throw.
An expression body becomes a block: the expression is returned, or becomes a statement when the method returns nothing (void, a constructor, or an async method returning Task or ValueTask).
using System; is added when ArgumentNullException does not bind where the guards go.

Preserved

The existing statements, with the comments and blank lines around them; a comment above the first statement stays with it, below the guards.
Behaviour for every call that passes non-null arguments.

Limitations

In a constructor the guards run after the base(...) or this(...) call, which may already have used the parameter.
In an iterator or async method the guard runs when iteration or the task starts, not at the call, as for any statement in such a body.
Unconstrained type parameters are not guarded, since they may be value types; nor are parameters annotated nullable, which are declared to accept null.
Existing guards in other shapes, such as a helper method, are not recognised, so their parameters are guarded again.
Local functions, lambdas, property setters and indexers are not covered.

Error codes

Code	Meaning
`no-body`	the method is abstract, extern, partial without a body, or an interface member
`nothing-to-guard`	no parameter is a reference type left unguarded

Cases

Diffs show each file from before to after. /*[*/ … /*]*/ marks a selection and /*^*/ a caret; the runner removes them before the refactoring runs.

#comments-and-existing-guard

Leaves a parameter the method already guards, and keeps the comment above the first statement with that statement

success

Targetsymbol M:Shop.Mailer.Send(System.String,System.String,System.String)

Mailer.csmodified

View fixture on GitHub

#constructor

Guards a constructor's parameters; the guards run after the base constructor call

success

Targetsymbol M:Shop.Order.#ctor(Shop.Customer,System.String)

Order.csmodified

View fixture on GitHub

#expression-bodied

Gives an expression-bodied method a block body so the guard can precede the returned expression

success

Targetsymbol M:Shop.Text.Shout(System.String)

Text.csmodified

View fixture on GitHub

#generic-overload

Guards a type parameter constrained to a class but not an unconstrained one, and only in the chosen overload

success

Targetsymbol M:Shop.Cache.Put``2(System.String,``0,``1)

Cache.csmodified

View fixture on GitHub

#no-body

Refuses an abstract method, which has no body to guard

refusal

Targetsymbol M:Shop.Shape.Describe(System.String)

Refusesno-body; every file is left unchanged

Shape.csinput

View fixture on GitHub

#nothing-to-guard

Refuses a method whose parameters are all value types

refusal

Targetsymbol M:Shop.Maths.Add(System.Int32,System.Int32)

Refusesnothing-to-guard; every file is left unchanged

Maths.csinput

View fixture on GitHub

#nullable-annotations

In a nullable context, parameters annotated as nullable accept null and are not guarded

success

Targetsymbol M:Shop.Greeter.Greet(System.String,System.String)

Projectnullable enable

Greeter.csmodified

View fixture on GitHub

#reference-parameters

Guards each reference-type parameter, skipping value types and parameters that default to null, and imports System

success

Targetsymbol M:Shop.Printer.Print(Shop.Customer,System.Int32,System.String,System.String)

Printer.csmodified

View fixture on GitHub

#void-expression-bodied

A void method's expression body becomes a statement after the guard

success

Targetsymbol M:Shop.Text.Log(System.String)

Text.csmodified

View fixture on GitHub

1	1		using System;
2	2		using System.Collections.Generic;
3	3
4	4		namespace Shop
5	5		{
6	6		public class Mailer
7	7		{
8	8		private readonly List<string> _sent = new List<string>();
9	9
10	10		/// <summary>Queues a message.</summary>
11	11		public void Send(string to, string subject, string body)
12	12		{
	13	+	ArgumentNullException.ThrowIfNull(subject);
	14	+	ArgumentNullException.ThrowIfNull(body);
	15	+
13	16		// Normalise the address first
14	17		if (to == null)
15	18		throw new ArgumentNullException(nameof(to));
16	19
17	20		_sent.Add(to.Trim() + ": " + subject + body); // record it
18	21		}
19	22		}
20	23		}

	1	+	using System;
	2	+
1	3		namespace Shop
2	4		{
3	5		public class Customer
4	6		{
5	7		}
6	8
7	9		public class Entity
8	10		{
9	11		protected Entity(string id)
10	12		{
11	13		Id = id;
12	14		}
13	15
14	16		public string Id { get; }
15	17		}
16	18
17	19		public class Order : Entity
18	20		{
19	21		private readonly Customer _customer;
20	22
21	23		public Order(Customer customer, string id) : base(id)
22	24		{
	25	+	ArgumentNullException.ThrowIfNull(customer);
	26	+	ArgumentNullException.ThrowIfNull(id);
	27	+
23	28		_customer = customer;
24	29		}
25	30		}
26	31		}

1	1		using System;
2	2
3	3		namespace Shop
4	4		{
5	5		public static class Text
6	6		{
7		−	public static string Shout(string text) => text.ToUpperInvariant() + "!";
	7	+	public static string Shout(string text)
	8	+	{
	9	+	ArgumentNullException.ThrowIfNull(text);
	10	+
	11	+	return text.ToUpperInvariant() + "!";
	12	+	}
8	13
9	14		public static void Log(string text) => Console.WriteLine(text);
10	15		}
11	16		}

1	1		using System;
2	2		using System.Collections.Generic;
3	3
4	4		namespace Shop
5	5		{
6	6		public class Cache
7	7		{
8	8		private readonly Dictionary<string, object> _items = new Dictionary<string, object>();
9	9
10	10		public void Put(string key, object value)
11	11		{
12	12		_items[key] = value;
13	13		}
14	14
15	15		public void Put<TValue, TTag>(string key, TValue value, TTag tag) where TValue : class
16	16		{
	17	+	ArgumentNullException.ThrowIfNull(key);
	18	+	ArgumentNullException.ThrowIfNull(value);
	19	+
17	20		_items[key] = value;
18	21		_items[key + "#tag"] = tag;
19	22		}
20	23		}
21	24		}

1		namespace Shop
2		{
3		public static class Maths
4		{
5		public static int Add(int left, int right)
6		{
7		return left + right;
8		}
9		}
10		}

1		namespace Shop
2		{
3		public abstract class Shape
4		{
5		public abstract string Describe(string prefix);
6		}
7		}

1	1		using System;
2	2
3	3		namespace Shop
4	4		{
5	5		public class Greeter
6	6		{
7	7		public string Greet(string name, string? title)
8	8		{
	9	+	ArgumentNullException.ThrowIfNull(name);
	10	+
9	11		return title is null ? "Hello " + name : "Hello " + title + " " + name;
10	12		}
11	13		}
12	14		}