Light.GuardClauses 11.0.0

dotnet add package Light.GuardClauses --version 11.0.0
NuGet\Install-Package Light.GuardClauses -Version 11.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Light.GuardClauses" Version="11.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Light.GuardClauses --version 11.0.0
#r "nuget: Light.GuardClauses, 11.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Light.GuardClauses as a Cake Addin
#addin nuget:?package=Light.GuardClauses&version=11.0.0

// Install Light.GuardClauses as a Cake Tool
#tool nuget:?package=Light.GuardClauses&version=11.0.0

Light.GuardClauses

A lightweight .NET library for expressive Guard Clauses.

License NuGet Source Code Documentation Documentation

Light.GuardClauses - easy precondition checks in C# / .NET

Read the full docs in the Wiki

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();
    }
}

As of version 10, Light.GuardClauses supports the CallerArgumentExpressionAttribute of C# 10. If your C# compiler is on a lower version, then the CallerArgumentExpressionAttribute might not be respected - you should then call all assertions with an explicit parameter name, e.g. bar.MustNotBeNull(nameof(bar)). You can use the C# 10 compiler by e.g. installing .NET 6 and/or Visual Studio 2022. The CallerArgumentExpressionAttribute is backwards-compatible, so it can be used with projects targeting .NET Standard 2, .NET Framework, or .NET Core.

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>, IEnumerable, IEnumerable<T>, and Span<T>. Just have a look at these examples:

public class ConsoleWriter
{
    private readonly ConsoleColor _foregroundColor;

    public ConsoleWriter(ConsoleColor foregroundColor = ConsoleColor.Black) =>
        _foregroundColor = foregroundColor.MustBeValidEnumValue();
}
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();
        _targetUrl = targetUrl.MustBeHttpOrHttpsUrl();
    }
}

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 or check out this overview.

Light.GuardClauses is optimized

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

Light.GuardClauses has support for .NET analyzers / FxCopAnalyzers with the ValidatedNotNullAttribute. Analyzers will know when an assertion validated that a parameters is not null and consequently, CA1062 will not be raised.

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. Since version 10.1.0, Light.GuardClauses also annotates assertions that do not iterate over an IEnumerable<T> with ReSharper's NoEnumerationAttribute - ReSharper will then not indicate a "Possible multiple enumeration" (thanks to cdonnellytx for this contribution).

Since version 11, Light.GuardClauses supports Native AOT.

Light.GuardClauses supports C#8 Nullable Reference Types since version 8.0.

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

Supported Platforms

Light.GuardClauses is built against .NET Standard 2.0 and 2.1, thus it can be used in frameworks like .NET 6, .NET 7, .NET Framework 4.6.1 or newer, Unity, Mono, or UWP.

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
  • Package Reference in csproj: <PackageReference Include="Light.GuardClauses" Version="11.0.0" />

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. You can learn more about it here.

Let there be... Light

Light Libraries Logo

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (24)

Showing the top 5 NuGet packages that depend on Light.GuardClauses:

Package Downloads
Updatedge.net

C# wrapper for the updatedge API

Synnotech.Migrations.Core

Core implementation of a generic migration engine that can be adapted to any target system.

Synnotech.Linq2Db

Package Description

Light.ViewModels

Simplify your XAML applications with Light.ViewModels!

Light.DependencyInjection

The DI Container you always wanted.

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on Light.GuardClauses:

Repository Stars
ExtendedXmlSerializer/home
A configurable and eXtensible Xml serializer for .NET.
Version Downloads Last updated
11.0.0 42,965 11/16/2023
11.0.0-preview1 91 9/24/2023
10.3.0 5,759 10/9/2023
10.2.0 1,094 9/22/2023
10.1.0 12,531 8/6/2023
10.0.0 343,990 12/6/2021
9.0.0 98,144 12/6/2020
8.1.0 54,312 5/27/2020
8.0.1 21,176 3/26/2020
8.0.0 561 3/25/2020
7.0.0 41,224 7/13/2019
6.2.0 17,673 2/12/2019
6.1.0 19,539 11/18/2018
6.0.0 844 11/10/2018
5.0.1 58,608 8/3/2018
5.0.0 1,204 7/29/2018
4.0.0 1,279 7/10/2018
3.5.0 2,681 9/3/2017
3.4.0 969 8/27/2017
3.3.0 1,179 8/15/2017
3.2.0 983 8/13/2017
3.1.0 962 8/6/2017
3.0.0 1,354 7/23/2017
2.0.0 1,310 5/29/2017
1.3.0 1,042 4/12/2017
1.2.1 1,735 11/16/2016
1.2.0 3,056 7/25/2016
1.1.0 1,450 6/2/2016
1.0.0 1,057 6/1/2016
0.2.0 1,080 3/29/2016
0.1.0 1,263 3/23/2016

Light.GuardClauses 11.0.0
--------------------------------

- Light.GuardClauses now targets .NET 8 and is AOT-compatible
- breaking: EnumInfo<T> no longer has the UnderlyingType property
- In AOT scenarios, avoid the Type-related assertions, they are marked with the DynamicallyAccessedMembersAttribute