Table of Contents

Namespace Existential

Classes

ArgumentTypeException

A custom exception that represents errors when a method argument is of an unexpected type. It extends the System.ArgumentException class, adding more specific context to the error scenario.

Disposable

Provides methods to help prevent resource leaks by safely handling disposable objects and enumerators:

  • a utility method, SafelyReturn<T>, for creation and initialization of System.IDisposable objects in line with best practices, so that they can be safely returned from the calling method without violating CodeAnalysis error CA2000 .
  • overloaded extension methods (UsingNonGenericEnumerator) for collections accessed through the System.Collections.IEnumerable interface that help to ensure their System.Collections.IEnumerator is correctly disposed if it happens to be disposable.
ExceptionExtensions

Provides extension methods for the System.Exception class, to support semantic logging of exceptions from within exception filters. Logging from within the exception filter ensures that the stack information for the exception is captured correctly, at the point that the exception is raised. Depending on the method chosen, it also allows exceptions to be logged regardless of whether they are subsequently handled.

The methods are named ShouldBeHandledLog and ShouldBeUnhandledLog. The ShouldBeHandledLog methods should be used when an exception is to be logged and then handled, while the ShouldBeUnhandledLog methods should be used when an exception is to be logged but not handled, allowing it to propagate up the call stack.

The methods accept a defined logger message , with up to six strongly typed parameters, and an implementation of Microsoft.Extensions.Logging.ILogger. An optional System.IO.TextWriter implementation can be provided to handle writing the error message to somewhere else in case logging fails. If no such implementation is provided, and logging fails, the message will be written as an error to the trace listeners registered in the System.Diagnostics.Trace.Listeners collection.

GetGenericEnumerable

Provides methods to convert one or more items, or a non-generic collection, of the same type to a generic IEnumerable.

GetGenericEnumerable<T>

Provides methods to convert one or more items, or a non-generic collection, where possible, to a generic System.Collections.Generic.IEnumerable<T> collection of the specified type T.

HashCodeHelper

Provides a method to calculate hash codes from provided values. A hash code can be generated for any type of object by passing its fields as arguments to this method.

ILoggerExtensions

Provides extension methods for the Microsoft.Extensions.Logging.ILogger interface, to support semantic logging of exceptions from within exception filters. Logging from within the exception filter ensures that the stack information for the exception is captured correctly, at the point that the exception is raised. Depending on the method chosen, it also allows exceptions to be logged regardless of whether they are subsequently handled.

The methods are named LogsThenHandle and LogsThenRethrow. The LogsThenHandle methods should be used when an exception is to be logged and then handled, while the LogsThenRethrow methods should be used when an exception is to be logged but not handled, allowing it to propagate up the call stack.

The methods accept a defined logger message , with up to six strongly typed parameters, and the System.Exception being logged. An optional System.IO.TextWriter implementation can be provided to handle writing the error message to somewhere else in case logging fails. If no such implementation is provided, and logging fails, the message will be written as an error to the trace listeners registered in the System.Diagnostics.Trace.Listeners collection.

Maybe

Provides utility methods for creating Maybe<T> instances, with or without values.

MaybeExtensions

Provides extension methods for IEnumerable<T>, and for some specific types of Maybe<T>, to support the use of Maybe<T> with types such as:

  • IEnumerable<T>,
  • IEnumerable<Maybe<T>>,
  • Maybe<string>,
  • Maybe<Guid>,
  • Maybe<T[]>, and
  • Maybe<List<T>>
These methods make it easier to work with Maybe<T> in a variety of contexts.
MaybeReferenceTypeExtensions

Provides extension methods for converting Maybe<T>, to a nullable reference type (T?) in a nullable context. When used outside a nullable context, the value will be returned as a reference type (T), which may be null. Static null checking is better in a nullable context.

MaybeValueTypeExtensions

Provides extension methods for converting Maybe<T>, to System.Nullable<T> where T is a value type.

MultiTextWriter

An implementation of System.IO.TextWriter that's constructed with a collection of IWriteStrategy. When its write methods are invoked, they will write the provided text using each of the strategies in the collection, allowing the same text to be directed to multiple outputs.

ObjectExtensions

Provides extension methods for values of any type that can be used to convert the value to a Maybe<T>.

PredicateExtensions

Provides an extension method to create a new System.Predicate<T> that's the negation of the one on which the method was called.

ThisMethod

A utility class for obtaining the name of the calling method at compile time.

TypeExtensions

Contains extension methods for System.Type that will include any generic parameters in the Type name.

Although the System.Type class allows the generic parameters of the Type to be enumerated, it doesn't include them in the name of the class. The extension methods in this class allow names to be retrieved from the Type in a format that lists its generic parameters between angle brackets.

Validate

The static Validate class contains a collection of methods for validating arguments; mainly to ensure they're not null or empty. The name of the value being validated must be passed in to ensure that it can be included in any exception message.

There are several practical advantages of these methods.

  • The name of the parameter that failed validation will be included in the exception message.
  • They're expressive, but succinct - they'll save you several lines of code every time you need a check.
  • If the value validates, the method returns it - so pass-through validation is possible in places like chained constructor calls, where you just can't write several lines of code to do this.

Since the nameof operator was introduced in C# 6.0, it's been possible for callers of the methods in this class to use nameof to retrieve the parameter's name in a way that will not be broken by refactoring tools. When using older versions of C#, it was necessary to pass an explicit string value.

Structs

Maybe<T>

Represents a value of type T that may or may not exist. Using Maybe<T> helps to avoid null references in a safe and expressive manner, by encapsulating an optional value in a type-safe way and allowing operations to be applied to it in ways that don't require a value to be present.

The Maybe<T> struct provides properties and methods for dealing with the encapsulated optional value:

  • Exists: Indicates whether the Maybe<T> contains a value.
  • ToMaybe: Converts a nullable value to a Maybe<T>.
  • Match, DoEither, IfExists: Execute different actions depending on whether the Maybe<T> contains a value or not.
  • TryGetValue: Tries to get the value of the Maybe<T>, returning a boolean indicating success or failure.
  • Map, Apply, Select, Bind, SelectMany: Transform the value inside the Maybe<T>, if it exists.
  • Where: Filters the value inside the Maybe<T> based on a predicate.
  • GetValueOr, GetValueOrMaybe, GetValueOrThrow: Retrieve the value inside the Maybe<T>, with different strategies for when it doesn't exist.

Interfaces

IWriteStrategy

Represents a string writing strategy. Implementations of this interface can provide different strategies for writing text, such as writing to a console, a file, or a network stream.