DOCSEARCHbyAlgolia
Submit Docs

Ensure.That

repository·master·Indexed 19 days ago

https://github.com/danielwertheim/ensure.that

A lightweight C# library for argument validation using guard clauses. It provides developer-friendly error messages for logging and debugging via three primary patterns: the Ensure.That() extension method for readable chaining, Ensure.Context for contextual validation (introduced in v7.0.0), and EnsureArg for simple static methods (introduced in v5.0.0). The library focuses on standard argument validation and is not intended for user-facing application errors or Internationalization (I18N).

Tokens
999
Snippets
4
Records
5
Agent score
16%

What's inside Ensure.That

  1. What is Ensure.That?

    master

    Ensure.That is a simple guard clause library designed for argument validation.

    Key Characteristics:

    • Purpose: It is intended to provide 'good enough' error messages for developers (e.g., in logs) during argument validation.
    • Not for Application Users: It is not designed for custom application exceptions, user-facing error messages, or Internationalization (I18N).
    • Exception Strategy: It does not support custom exceptions or I18N; it focuses on standard argument validation patterns.

  2. Validate arguments using extension methods

    master

    The primary way to use Ensure.That is through the Ensure.That() extension method pattern. This approach is highly readable and supports method chaining.

    Basic Usage

    You can validate a value directly or include the parameter name for better error reporting:

    Ensure.That(myString).IsNotNullOrWhiteSpace();
Ensure.That(myString, nameof(myString)).IsNotNullOrWhiteSpace();

    Chaining Validations

    Methods are chainable, allowing you to perform multiple checks on the same argument:

    Ensure
  .That(myString)
  .IsNotNullOrWhiteSpace()
  .IsGuid();

    Extending with Custom Validations

    You can extend the validation capabilities by creating extension methods for the Param<T> type (the type returned by Ensure.That):

    public static class StringArgExtensions
{
    public static StringParam IsNotFishy(this StringParam param)
        => param.Value != "fishy"
            ? param
            : throw Ensure.ExceptionFactory.ArgumentException("Something is fishy!", param.Name);
}

Ensure.That(myString, nameof(myString)).IsNotFishy();

    Performance Note: If you are concerned about the performance overhead of the public readonly struct Param<T> created by Ensure.That(), consider using Ensure.Context or EnsureArg instead.

    Ensure.That(myString).IsNotNullOrWhiteSpace();
Ensure.That(myString, nameof(myString)).IsNotNullOrWhiteSpace();

Ensure
  .That(myString)
  .IsNotNullOrWhiteSpace()
  .IsGuid();

  4. Validate arguments using EnsureArg

    master

    Introduced in v5.0.0, EnsureArg provides simple static methods for argument validation. This is a lightweight alternative to the other constructs.

    Basic Usage

    EnsureArg.IsNotNullOrWhiteSpace(myString);
EnsureArg.IsNotNullOrWhiteSpace(myString, nameof(myArg));

    Extending with Custom Validations

    You can extend EnsureArg by adding methods to a partial class definition:

    public static partial class EnsureArg
{
    public static string IsNotFishy(string value, string paramName = null)
        => value != "fishy"
            ? value
            : throw Ensure.ExceptionFactory.ArgumentException("Something is fishy!", paramName);
}

EnsureArg.IsNotFishy(myString, nameof(myString));

  5. Validate arguments using Ensure.Context

    master

    Introduced in v7.0.0, Ensure.Context provides contextual validation using static methods. This is an alternative to the extension method approach, often used to avoid the allocation of the Param<T> struct.

    Basic Usage

    Ensure.String.IsNotNullOrWhiteSpace(myString);
Ensure.String.IsNotNullOrWhiteSpace(myString, nameof(myArg));

    Extending with Custom Validations

    To extend Ensure.Context, write extension methods targeting the specific type (e.g., StringArg):

    public static class StringArgExtensions
{
    public static string IsNotFishy(this StringArg _, string value, string paramName = null)
        => value != "fishy"
            ? value
            : throw Ensure.ExceptionFactory.ArgumentException("Something is fishy!", paramName);
}

Ensure.String.IsNotFishy(myString, nameof(myString));