Home

Light.GuardClauses

Easy precondition checks in C# / .NET

As a software developer, you're used to writing if statements at the beginning of your methods which validate the parameters that are passed in. Most often you'll probably check for null:

public class Foo
{
    private readonly IBar _bar;
    
    public Foo(IBar bar)
    {
        if (bar == null)
            throw new ArgumentNullException(nameof(bar));
        
        _bar = bar;
    }
}

Light.GuardClauses simplifies these precondition checks for you by providing extension methods that you can directly call on your parameters:

public class Foo
{
    private readonly IBar _bar;
    
    public Foo(IBar bar)
    {
        _bar = bar.MustNotBeNull(nameof(bar));
    }
}

By using Light.GuardClauses, you'll gain access to assertions for a vast amount of scenarios like checking strings, collections, enums, URIs, DateTime, Type, IComparable<T>, IEnumerableand IEnumerable<T>. Just have a look at these examples:

public class ConsoleWriter
{
    private readonly ConsoleColor _foregroundColor;

    public ConsoleWriter(ConsoleColor foregroundColor = ConsoleColor.Black) =>
        _foregroundColor = foregroundColor.MustBeValidEnumValue(nameof(foregroundColor));
}

public void SetMovieRating(Guid movieId, int numberOfStars)
{
    movieId.MustNotBeEmpty();
    numberOfStars.MustBeIn(Range.FromInclusive(0).ToInclusive(5));
    
    var movie = _movieRepo.GetById(movieId);
    movie.AddRating(numberOfStars);
}

public class WebGateway
{
    private readonly HttpClient _httpClient;
    private readonly Uri _targetUrl;

    public WebGateway(HttpClient httpClient, Uri targetUrl)
    {
        _httpClient = httpClient.MustNotBeNull(nameof(httpClient));
        _targetUrl = targetUrl.MustBeHttpOrHttpsUrl(nameof(targetUrl));
    }
}

In addition to assertions that throw exceptions (all these start with Must), Light.GuardClauses provides assertions that return a Boolean. Some examples are:

• string.IsNullOrWhitespace()
• collection.IsNullOrEmpty()
• enum.IsValidEnumValue()

You can use these in your branching logic to easily check if an assertion is true or false.

Every assertion is well-documented - explore them using IntelliSense.

Light.GuardClauses is optimized

Since version 4.x, Light.GuardClauses is optimized for performance (measured in .NET 4.7.x and .NET Core 2.x). With the incredible help of @redknightlois and the awesome tool Benchmark.NET, most assertions are as fast as your imperative code would be.

Furthermore, Light.GuardClauses has support for ReSharper since version 4.x. Via Contract Annotations, R# knows when assertions do not return a null value and thus removes squiggly lines indicating a possible NullReferenceException.

And, of course, the functional correctness of Light.GuardClauses is covered by a vast suite of automated tests.

Supported Platforms

Since version 4.x, Light.GuardClauses supports the following platforms:

• .NET Standard 1.0 and 2.0
• .NET 4.5, .NET 4.0, .NET 3.5, .NET 3.5 Compact Framework (it's called WinCE for a reason)
• Silverlight 5

How to Install

Light.GuardClauses is available as a NuGet package.

• dotnet CLI: dotnet add package Light.GuardClauses
• Visual Studio Package Manager Console: Install-Package Light.GuardClauses

Also, you can incorporate Light.GuardClauses as a single source file where the API is changed to internal. This is especially interesting for framework / library developers that do not want to have a dependency on the Light.GuardClauses DLL. You can grab the default .NET Standard 2.0 version in Light.GuardClauses.SingleFile.cs or you can use the Light.GuardClauses.SourceCodeTransformation project to create your custom file.