FluentResults
A generalised Result object implementation for .NET/C#
Install / Use
/learn @altmann/FluentResultsREADME
FluentResults is a lightweight .NET library developed to solve a common problem. It returns an object indicating success or failure of an operation instead of throwing/using exceptions.
You can install FluentResults with NuGet:
Install-Package FluentResults
:heart: The most needed community feature is pushed to nuget: FluentResults.Extensions.AspNetCore Read documentation. Try it, test it, give feedback.
Key Features
- Generalised container which works in all contexts (ASP.NET MVC/WebApi, WPF, DDD Domain Model, etc)
- Store multiple errors in one Result object
- Store powerful and elaborative Error and Success objects instead of only error messages in string format
- Designing Errors/Success in an object-oriented way
- Store the root cause with chain of errors in a hierarchical way
- Provide
- .NET Standard, .NET Core, .NET 5+ and .NET Full Framework support (details see .NET Targeting)
- SourceLink support
- powerful code samples which show the integration with famous or common frameworks/libraries
- NEW Enhanced FluentAssertions Extension to assert FluentResult objects in an elegant way
- IN PREVIEW Returning Result Objects from ASP.NET Controller
Why Results instead of exceptions
To be honest, the pattern - returning a Result object indicating success or failure - is not at all a new idea. This pattern comes from functional programming languages. With FluentResults this pattern can also be applied in .NET/C#.
The article Exceptions for Flow Control by Vladimir Khorikov describes very well in which scenarios the Result pattern makes sense or not. See the list of Best Practices and the list of resources to learn more about the Result Pattern.
Creating a Result
A Result can store multiple Error and Success messages.
// create a result which indicates success
Result successResult1 = Result.Ok();
// create a result which indicates failure
Result errorResult1 = Result.Fail("My error message");
Result errorResult2 = Result.Fail(new Error("My error message"));
Result errorResult3 = Result.Fail(new StartDateIsAfterEndDateError(startDate, endDate));
Result errorResult4 = Result.Fail(new List<string> { "Error 1", "Error 2" });
Result errorResult5 = Result.Fail(new List<IError> { new Error("Error 1"), new Error("Error 2") });
The class Result is typically used by void methods which have no return value.
public Result DoTask()
{
if (this.State == TaskState.Done)
return Result.Fail("Task is in the wrong state.");
// rest of the logic
return Result.Ok();
}
Additionally a value from a specific type can also be stored if necessary.
// create a result which indicates success
Result<int> successResult1 = Result.Ok(42);
Result<MyCustomObject> successResult2 = Result.Ok(new MyCustomObject());
// create a result which indicates failure
Result<int> errorResult = Result.Fail<int>("My error message");
The class Result<T> is typically used by methods with a return type.
public Result<Task> GetTask()
{
if (this.State == TaskState.Deleted)
return Result.Fail<Task>("Deleted Tasks can not be displayed.");
// rest of the logic
return Result.Ok(task);
}
Processing a Result
After you get a Result object from a method you have to process it. This means, you have to check if the operation was completed successfully or not. The properties IsSuccess and IsFailed in the Result object indicate success or failure. The value of a Result<T> can be accessed via the properties Value and ValueOrDefault.
Result<int> result = DoSomething();
// get all reasons why result object indicates success or failure.
// contains Error and Success messages
IEnumerable<IReason> reasons = result.Reasons;
// get all Error messages
IEnumerable<IError> errors = result.Errors;
// get all Success messages
IEnumerable<ISuccess> successes = result.Successes;
if (result.IsFailed)
{
// handle error case
var value1 = result.Value; // throws exception because result is in failed state
var value2 = result.ValueOrDefault; // return default value (=0) because result is in failed state
return;
}
// handle success case
var value3 = result.Value; // return value and doesn't throw exception because result is in success state
var value4 = result.ValueOrDefault; // return value because result is in success state
Designing errors and success messages
There are many Result Libraries which store only simple string messages. FluentResults instead stores powerful object-oriented Error and Success objects. The advantage is all the relevant information of an error or success is encapsulated within one class.
The entire public api of this library uses the interfaces IReason, IError and ISuccess for representing a reason, error or success. IError and ISuccess inherit from IReason. If at least one IError object exists in the Reasons property then the result indicates a failure and the property IsSuccess is false.
You can create your own Success or Error classes when you inherit from ISuccess or IError or if you inherit from Success or Error.
public class StartDateIsAfterEndDateError : Error
{
public StartDateIsAfterEndDateError(DateTime startDate, DateTime endDate)
: base($"The start date {startDate} is after the end date {endDate}")
{
Metadata.Add("ErrorCode", "12");
}
}
With this mechanism you can also create a class Warning. You can choose if a Warning in your system indicates a success or a failure by inheriting from Success or Error classes.
Further features
Chaining error and success messages
In some cases it is necessary to chain multiple error and success messages in one result object.
var result = Result.Fail("error message 1")
.WithError("error message 2")
.WithError("error message 3")
.WithSuccess("success message 1");
Create a result depending on success/failure condition
Very often you have to create a fail or success result depending on a condition. Usually you can write it in this way:
var result = string.IsNullOrEmpty(firstName) ? Result.Fail("First Name is empty") : Result.Ok();
With the methods FailIf() and OkIf() you can also write in a more readable way. You can also supply a collection of errors:
var result = Result.FailIf(string.IsNullOrEmpty(firstName), "First Name is empty");
bool isValid = false; // Some check
var errors = new List<Error>{ new Error("Error 1"), new Error("Error 2") };
var result2 = Result.FailIf(isValid, errors);
If your success check is based on whether or not there are errors, you can use FailIfNotEmpty()
var errors = PerformSomeValidation();
var result = Result.FailIfNotEmpty(errors);
If an error instance should be lazily initialized, overloads accepting Func<string> or Func<IError> can be used to that effect:
var list = Enumerable.Range(1, 9).ToList();
var result = Result.FailIf(
list.Any(IsDivisibleByTen),
() => new Error($"Item {list.First(IsDivisibleByTen)} should not be on the list"));
bool IsDivisibleByTen(int i) => i % 10 == 0;
var errors = PerformSomeValidation();
var result = Result.FailIfNotEmpty(
errors,
(err) => new Error("Custom error message based on err"));
// rest of the code
Try
In some scenarios you want to execute an action. If this action throws an exception then the exception should be caught and transformed to a result object.
var result = Result.Try(() => DoSomethingCritical());
You can also return your own Result object
var result = Result.Try(() => {
if(IsInvalid())
{
return Result.Fail("Some error");
}
int id = DoSomethingCritical();
return Result.Ok(id);
});
In the above example the default catchHandler is used. The behavior of the default catchHandler can be overwritten via the global Result settings (see next example). You can control how the Error object looks.
Result.Setup(cfg =>
{
cfg.DefaultTryCatchHandler = exception =>
{
if (exception is SqlTypeException sqlException)
return new ExceptionalError("Sql Fehler", sqlException);
if (exception is DomainException domainException)
return n
