FluentResults

To integrate FluentResult with MediatR request handlers:

• Return Results, Not Exceptions: Return business validation errors via a Result object from the MediatR request handler instead of throwing exceptions.
• Validation Pipelines: Use MediatR IPipelineBehavior to inject command and query validation. The behavior should return a Result object containing validation errors back to the consumer.

When using FluentResult within a Domain-Driven Design (DDD) context, follow these best practices:

• Protect Invariants: Use factory methods that return a Result object to ensure domain invariants are maintained.
• Custom Errors: Create unique error types by inheriting from the Error class or implementing the IError interface.
• Selective Usage: Only use Result as a return type if the method has a legitimate failure scenario. If a method cannot fail, return the type directly.
• Error Aggregation: You can merge multiple failed results or return the first failed result immediately to stop processing.

To use FluentResults in your .NET project, install the package using the NuGet Package Manager Console.

Install-Package FluentResults

When working with system boundaries like ASP.NET WebApi or Hangfire, do not serialize FluentResult objects directly.

Instead, implement a custom ResultDto class for your public API to:

• Control exactly which data is submitted and serialized.
• Decouple your public API from third-party libraries like FluentResults.
• Maintain a stable public API contract even if the underlying library changes.

Use Result.Setup() to override the default factories for ISuccess, IError, and IExceptionalError. This allows you to inject custom logic (like adding timestamps via metadata) whenever a result is created via shorthand methods like Result.Ok() or Result.Fail().

Result.Setup(cfg =>
{
    cfg.SuccessFactory = successMessage => new Success(successMessage).WithMetadata("Timestamp", DateTime.Now);
    cfg.ErrorFactory = errorMessage => new Error(errorMessage).WithMetadata("Timestamp", DateTime.Now);
    cfg.ExceptionalErrorFactory = (errorMessage, exception) => new ExceptionalError(errorMessage ?? exception.Message, exception)
        .WithMetadata("Timestamp", DateTime.Now);
});

You can append multiple error or success messages to a single Result object using WithError() and WithSuccess().

var result = Result.Fail("error message 1")
                   .WithError("error message 2")
                   .WithError("error message 3")
                   .WithSuccess("success message 1");

Attach metadata to Error or Success objects using WithMetadata(key, value). This can be done during result creation or within custom error class constructors.

// During creation
var result1 = Result.Fail(new Error("Error 1").WithMetadata("metadata name", "metadata value"));

// In a custom error class
public class DomainError : Error
{
    public DomainError(string message)
        : base(message)
    {
        WithMetadata("ErrorCode", "12");
    }
}

Use Result.Try() to wrap code that might throw exceptions. The exception is caught and transformed into a Result object. You can provide a custom catchHandler via the Try method or configure a global DefaultTryCatchHandler via Result.Setup().

// Basic usage
var result = Result.Try(() => DoSomethingCritical());

// Custom catch handler per call
var result2 = Result.Try(() => DoSomethingCritical(), ex => new MyCustomExceptionError(ex));

// Global configuration
Result.Setup(cfg =>
{
    cfg.DefaultTryCatchHandler = exception =>
    {
        if (exception is SqlTypeException sqlException)
            return new ExceptionalError("Sql Fehler", sqlException);
        return new Error(exception.Message);
    };
});

Use the Result class for methods that do not return a value (void equivalents). Use Result<T> for methods that return a specific type. You can create success results using Result.Ok() and failure results using Result.Fail() with strings, custom error objects, or lists of errors.

// For void-like methods
Result successResult1 = Result.Ok();
Result errorResult1 = Result.Fail("My error message");
Result errorResult3 = Result.Fail(new StartDateIsAfterEndDateError(startDate, endDate));

// For methods returning a value
Result<int> successResult1 = Result.Ok(42);
Result<int> errorResult = Result.Fail<int>("My error message");