Skip to main content

RA.Utilities.Core.Results

NuGet version NuGet Downloads Codecov Publish NuGet GitHub license

RA.Utilities.Core.Results is a lightweight .NET library designed to enhance error handling by providing a functional Result type. It helps you write cleaner, more predictable, and more robust code by avoiding exceptions for expected operational failures. This approach allows for a clear and explicit representation of success or failure, making your application's control flow easier to follow and maintain.

🎯 Purpose​

In many applications, exceptions are used for both unexpected system faults (e.g., NullReferenceException) and predictable business-level failures (e.g., "user not found"). This can lead to complex try-catch blocks and makes it difficult to distinguish between recoverable errors and true exceptions.

The Result type solves this by providing a wrapper that explicitly represents one of two outcomes:

  • Success: The operation completed successfully, and may contain a value.
  • Failure: The operation failed, and contains an Exception detailing the error.

This pattern encourages you to handle failures as part of your normal code flow, leading to more readable and resilient applications.

🛠️ Installation​

You can install the package via the .NET CLI:

dotnet add package RA.Utilities.Core.Results

Or through the NuGet Package Manager console:

Install-Package RA.Utilities.Core.Results

Or through the NuGet Package Manager in Visual Studio.

When to use Results Pattern and when to use Exceptions​

LayerUse Results PatternUse Exceptions
✅ Application Layer✅ Yes❌ Avoid
✅ Domain Layer✅ Yes❌ Avoid
🌐 Infrastructure❌ Rarely✅ Yes
🌍 External APIs❌✅ Required
🧪 Tests✅ Preferred✅ Avoid
SituationUse
Input validation failed✅ Result pattern
Business rule not satisfied✅ Result pattern
DB connection failed⚠️ Exception
File not found (unexpected)⚠️ Exception
You want to chain logic steps✅ Result pattern
You need a stack trace.⚠️ Exception

The Result Type​

  • Result: Represents the outcome of an operation that does not return a value. It can be either a success or a failure.
  • Result<T>: Represents the outcome of an operation that returns a value of type T. It can be a success holding a T value, or a failure holding an Exception.

Chaining methods (Map, Bind, OnSuccess, OnFailure, Match and their async counterparts) are extension methods declared in the RA.Utilities.Core.Results.Extensions namespace.

Namespace change in 10.0.1

The extension methods lived in RA.Utilities.Core.Results up to and including 10.0.0 and moved to RA.Utilities.Core.Results.Extensions in 10.0.1 — add using RA.Utilities.Core.Results.Extensions; when upgrading. See the migration guide.

Factory Methods​

  • Result.Success(): Creates a success result.
  • Result.Failure(Exception exception): Creates a failure result.