Ardalis.Result

Ardalis.Result is a result abstraction designed to provide a standard, reusable way to return both success and various non-success responses (like NotFound or Invalid) from .NET services.

Instead of using exceptions for flow control (which can be expensive and difficult to manage) or Tuples (which lack a standard structure), the Result pattern allows services to return a Result<T> or Result object. This object can then be easily mapped to HTTP response codes in ASP.NET Core applications.

Key packages:

• Ardalis.Result: The core abstraction (no dependencies on ASP.NET Core).
• Ardalis.Result.AspNetCore: Companion package for mapping results to ActionResult or Minimal API IResult types.
• Ardalis.Result.FluentValidation: Integration for using results with FluentValidation.

If you prefer not to use attributes, you can manually translate a result to an ActionResult<T> within your controller action using extension methods. There are two ways to do this:

1. On the ControllerBase: Call this.ToActionResult(result).
2. On the Result instance: Call result.ToActionResult(this), passing the current controller instance as an argument.

[HttpPost("/Person/Create/")]
public override ActionResult<Person> Handle(CreatePersonRequestDto request)
{
    // Option 1: Extension method on ControllerBase
    return this.ToActionResult(_personService.Create(request.FirstName, request.LastName)); // 👈

    // Option 2: Extension method on a Result instance
    Result<Person> result = _personService.Create(request.FirstName, request.LastName);
    return result.ToActionResult(this); // 👈
}

For .NET 6+ Minimal APIs, use the ToMinimalApiResult() extension method. This converts an Ardalis.Result into a Microsoft.AspNetCore.Http.Results.IResult type, which is the standard return type for Minimal API endpoints.

app.MapPost("/Forecast/New", (ForecastRequestDto request, WeatherService weatherService) =>
{
    return weatherService.GetForecast(request).ToMinimalApiResult();
})
.WithName("NewWeatherForecast");

By default, ASP.NET Core and API Explorer do not recognize the [TranslateResultToActionResult] attribute. To ensure tools like Swashbuckle or NSwag correctly reflect the possible response types in your API documentation, you must configure ResultConvention during service registration.

Use AddDefaultResultConvention() to automatically add [ProducesResponseType] for every known ResultStatus to endpoints marked with [TranslateResultToActionResult].

services.AddControllers(mvcOptions => mvcOptions.AddDefaultResultConvention());

To use automatic result translation in an ASP.NET Core Web API, install the Ardalis.Result.AspNetCore NuGet package. This package provides the necessary attributes and extension methods to convert Result and Result<T> types into appropriate HTTP responses (like ActionResult or Minimal API results).

dotnet add package Ardalis.Result.AspNetCore

Instead of throwing exceptions for expected business logic outcomes (like a record not being found), use the Result abstraction. This avoids using exceptions for control flow, which is a best practice in web APIs to prevent unnecessary 500 Server Error responses and to clearly communicate status (like a 404 Not Found) to the caller.

By returning a Result, your method signature becomes intention-revealing, and the calling code can use standard conditionals to handle different outcomes.

public Result Remove(int id)
{
    if (!Exists(id))
    {
        return Result.NotFound($"Record with id {id} Not Found");
    }

    // Remove the record

    return Result.Success();
}

Depending on your needs, you can install the core library or its specialized integration packages via NuGet:

• Ardalis.Result: The base package containing all core functionality and types for domain models or business services. It has no third-party dependencies.
• Ardalis.Result.AspNetCore: Provides helpers to map Ardalis.Result types to ActionResult and IResult for ASP.NET Core Controller-based APIs and Minimal APIs.
• Ardalis.Result.FluentValidation: Enables easy integration with the FluentValidation library and its error types.

dotnet add package Ardalis.Result
dotnet add package Ardalis.Result.AspNetCore
dotnet add package Ardalis.Result.FluentValidation

In Minimal APIs, you can automatically translate a Result or Result<T> into a Minimal API response by calling the .ToMinimalApiResult() extension method on the result object in your return statement.

app.MapPost("/Forecast/New", (ForecastRequestDto request, WeatherService weatherService) =>
{
    return weatherService.GetForecast(request).ToMinimalApiResult(); // 👈
});