Linger.Results.AspNetCore 1.5.5

Linger.Results.AspNetCore

Linger.Results.AspNetCore provides extension methods that seamlessly integrate the Linger.Results library with ASP.NET Core framework, allowing API controllers to easily return results in a unified format.

Features

• Elegantly convert Result and Result<T> objects to ASP.NET Core ActionResult
• Support for Minimal API - convert Result and Result<T> to IResult using modern Results static class
• Automatically select appropriate HTTP status codes based on result status
• Support for custom success and failure status codes
• Provide RFC 7807 standard ProblemDetails format output

Supported Framework Versions

• .NET 8.0+

Installation

dotnet add package Linger.Results.AspNetCore

Basic Usage

Using in Controllers

[ApiController]
[Route("api/[controller]")]
public class UsersController : ControllerBase
{
    [HttpGet("{id}")]
    public async Task<ActionResult<UserDto>> GetUser(int id)
    {
        var result = await _userService.GetUserByIdAsync(id);
        return result.ToActionResult(); // Success returns UserDto, failure returns error array
    }

    [HttpPost]
    public async Task<ActionResult<UserDto>> CreateUser(CreateUserRequest request)
    {
        var result = await _userService.CreateUserAsync(request);
        return result.ToActionResult(HttpStatusCode.Created);
    }

    [HttpDelete("{id}")]
    public async Task<ActionResult> DeleteUser(int id)
    {
        var result = await _userService.DeleteUserAsync(id);
        return result.ToActionResult(HttpStatusCode.NoContent); // Success returns 204, failure returns error
    }

    // Compatible with methods returning IActionResult type signature
    // This only applies to non-generic Result; Result<T> should use ActionResult<T>
    [HttpPut("{id}")]
    public async Task<IActionResult> UpdateUser(int id, UpdateUserRequest request)
    {
        var result = await _userService.UpdateUserAsync(id, request);
      return result.ToActionResult(); // Non-generic Result can be returned directly as IActionResult
    }
}

Using in Minimal API

var app = WebApplication.Create();

app.MapGet("/api/users/{id}", async (int id, IUserService userService) =>
{
    var result = await userService.GetUserByIdAsync(id);
    return result.ToHttpResult(); // Automatic status code mapping
});

app.MapPost("/api/users", async (CreateUserRequest request, IUserService userService) =>
{
    var result = await userService.CreateUserAsync(request);
    // Check IsSuccess because accessing result.Value requires the result to be successful
    return result.IsSuccess
      ? result.ToCreatedResult($"/api/users/{result.Value.Id}")
      : result.ToHttpResult(); // Failure returns ProblemDetails automatically
});

app.MapDelete("/api/users/{id}", async (int id, IUserService userService) =>
{
    var result = await userService.DeleteUserAsync(id);
    return result.ToNoContentResult(); // Success returns 204 No Content
});

API Method Comparison

When to use

• Use ToActionResult() / ToHttpResult() for most standard CRUD operations (default auto-mapping handles status codes correctly)
• Use ToCreatedResult() for POST endpoints to return 201 Created with location header
• Use ToNoContentResult() for DELETE/PUT endpoints to return 204 No Content on success
• Use ToProblemDetails() when you explicitly need RFC 7807 Problem Details format response

Status Code Parameters:

• ToActionResult() / ToActionResult<T>() / ToHttpResult() / ToHttpResult<T>(): Both successStatusCode and failureStatusCode are optional. When not specified, successStatusCode defaults to 200 OK; failureStatusCode is auto-determined by Result.Status (e.g., NotFound → 404, others → 400)
• ToProblemDetails() / ToProblemDetails<T>(): Only failureStatusCode is optional, same auto-determination applies

Response Format Examples

Success Responses

// Result<UserDto> success
{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com"
}

// Result success
{
  "status": "Ok",
  "isSuccess": true,
  "isFailure": false,
  "errors": []
}

Failure Responses

// Standard error format
[
  {
    "code": "User.NotFound",
    "message": "User with ID 123 not found"
  }
]

See detailed request/response mapping and error contract in
[REQUEST_RESPONSE_MAPPING.zh-CN.md](../Linger.HttpClient.Standard/REQUEST_RESPONSE_MAPPING.zh-CN.md).

Short summary: `errors` values are arrays of strings per field; `CreateProblemDetails` groups `Error` items by `Code` and writes `string[]` into `errors`. The client will prioritize `detail` for the global message, otherwise the first `errors` entry.
Note: `errors` is an RFC 7807 extension member and SHOULD use string arrays (e.g. `{"Field": ["msg1", "msg2"]}`) so a single field can carry multiple validation messages. The server adds it via `ProblemDetails.Extensions["errors"]`; ASP.NET Core serializes `Extensions` entries as top-level properties, so you will see a top-level `errors` field.

Client mapping notes:

- The library exposes `ProblemDetails` with `errors` where each value is an array of strings. `CreateProblemDetails` groups `Error` items by `Code` and sets each group's messages as `string[]` in `errors`.
- Consumers should expect `errors` values to be arrays and handle multiple messages per field. When using `ToProblemDetails()`, clients will receive `errors` that map to `ApiResult.Errors` where each array element becomes an `Error` item (`Error.Code` = field, `Error.Message` = single message).

## Status Code Mapping

- `Result.Success()` → 200 OK
- `Result.NotFound()` → 404 Not Found
- `Result.Failure()` → 400 Bad Request

## Best Practices

1. **Separation of Concerns**: Service layer returns `Result`, controller handles HTTP response conversion
2. **Consistent API Responses**: Maintain unified error formats across the application
3. **Use ProblemDetails**: Prefer RFC 7807 format for client-facing APIs
4. **Choose Right API Style**: Use Controllers for complex scenarios, Minimal API for simple cases


## Design Decision: Why No `IActionResult` Conversion Methods?

`ActionResult` and `ActionResult<T>` are the recommended modern approach, and we intentionally do not provide `IActionResult` conversion methods for the following reasons:

- **Type Safety**: `ActionResult<T>` is generic and preserves the complete type information of return values, facilitating framework features like OpenAPI/Swagger generation and type checking. `IActionResult` is a non-generic interface that loses generic type information, hindering tool chain support.

- **Seamless Compatibility**: Non-generic `Result` converts directly to `ActionResult`, so when your method signature needs to return `IActionResult` you can return `ToActionResult()` directly; `Result<T>` should use `ActionResult<T>` as the return type.

- **Consistency**: We follow ASP.NET Core official best practices by prioritizing the use of generic `ActionResult<T>` over non-generic `IActionResult`.

**Summary**: If your method return type is `IActionResult`, you can directly use `ToActionResult()` for non-generic `Result`; if you are returning `Result<T>`, change the method signature to `ActionResult<T>`.

## Using with Linger.Results

This library is an extension of [Linger.Results](../Linger.Results/README.md). Please also refer to the Linger.Results documentation to learn more about result object functionality.