/dotnet.futurum.webapiendpoint.micro.core.extensions

Primary LanguageC#MIT LicenseMIT

Futurum.WebApiEndpoint.Micro.Core.Extensions

license CI Coverage Status NuGet version

A dotnet library that extends Futurum.WebApiEndpoint.Micro, making it fully compatible with Futurum.Core.

Full compatibility with Futurum.Core

Comprehensive set of extension methods to transform a Result and Result<T> to an TypedResult.

  • If the method passed in is a success, then the IResult will be returned.
  • If the method passed in is a failure, then a BadRequest<ProblemDetails> will be returned, with the appropriate details set on the ProblemDetails. The error message will be safe to return to the client, that is, it will not contain any sensitive information e.g. StackTrace.

The returned type from ToWebApi is always augmented to additionally include BadRequest<ProblemDetails>

Result<T> -> Results<T, BadRequest<ProblemDetails>>

Result<Results<TIResult1, TIResult2>> -> Results<TIResult1, TIResult2, BadRequest<ProblemDetails>>

Result<Results<TIResult1, TIResult2, TIResult3>> -> Results<TIResult1, TIResult2, TIResult3, BadRequest<ProblemDetails>>

Result<Results<TIResult1, TIResult2, TIResult3, TIResult4>> -> Results<TIResult1, TIResult2, TIResult3, TIResult4, BadRequest<ProblemDetails>>

Result<Results<TIResult1, TIResult2, TIResult3, TIResult4, TIResult5>> -> Results<TIResult1, TIResult2, TIResult3, TIResult5, BadRequest<ProblemDetails>>

Results has a maximum of 6 types. So 5 are allowed leaving one space left for the BadRequest<ProblemDetails>.

How to handle successful and failure cases in a typed way with TypedResult

You can optionally specify which TypedResult success cases you want to handle. This is useful if you want to handle a specific successes case differently.

You can specify which TypedResult error cases you want to handle. This is useful if you want to handle a specific error case differently.

If you have a success case, you must pass in the the success helper function first, then the failure helper functions.

There can only be 1 success helper function, but there can be multiple failure helper functions.

Example use

The ToWebApi extension method will change the method return type to add BadRequest<ProblemDetails>, with the appropriate details set on the ProblemDetails. The error message will be safe to return to the client, that is, it will not contain any sensitive information e.g. StackTrace.

You can then pass in additional helper functions to deal with successes and failures and these will change the return type to the appropriate TypedResult's.

ToOk is a function that will convert a T to an Ok<T>.

ToValidationProblem is a function that will convert a ValidationResultError to a ValidationProblem.

Full Example

private static Results<Ok<ArticleDto>, ValidationProblem, BadRequest<ProblemDetails>> ValidationHandler(HttpContext context, IValidationService<ArticleDto> validationService,
                                                                                                        ArticleDto articleDto) =>
    validationService.Execute(articleDto)
                     .Map(() => new Article(null, articleDto.Url))
                     .Map(ArticleMapper.MapToDto)
                     .ToWebApi(context, ToOk, ToValidationProblem);

Success and Failure helper functions

If you have a success case, you must pass in the the success helper function first, then the failure helper functions.

There can only be 1 success helper function, but there can be multiple failure helper functions.

Note: It is recommended to add the following to your GlobalUsings.cs file.

global using static Futurum.WebApiEndpoint.Micro.WebApiResultsExtensions;

This means you can use the helper functions without having to specify the namespace. As in the examples.

Failure helper functions

ToNotFound

If a ResultErrorKeyNotFound has occured then it will convert it to a NotFound<ProblemDetails>, with the correct information set on the ProblemDetails.

ToNotFound

ToValidationProblem

If a ResultErrorValidation has occured then it will convert it to a ValidationProblem, with the correct information set on the HttpValidationProblemDetails.

ToValidationProblem

Validation

ValidationService

Executes FluentValidation and DataAnnotations

IValidationService<ArticleDto> validationService

e.g.

private static Results<Ok<ArticleDto>, ValidationProblem, BadRequest<ProblemDetails>> ValidationHandler(HttpContext context, IValidationService<ArticleDto> validationService,
                                                                                                        ArticleDto articleDto) =>
    validationService.Execute(articleDto)
                     .Map(() => new Article(null, articleDto.Url))
                     .Map(ArticleMapper.MapToDto)
                     .ToWebApi(context, ToOk, ToValidationProblem);

FluentValidationService

Calls FluentValidation

IFluentValidationService<ArticleDto> fluentValidationService

e.g.

private static Results<Ok<ArticleDto>, ValidationProblem, BadRequest<ProblemDetails>> FluentValidationHandler(HttpContext context, IFluentValidationService<ArticleDto> fluentValidationService,
                                                                                                              ArticleDto articleDto) =>
    fluentValidationService.Execute(articleDto)
                           .Map(() => new Article(null, articleDto.Url))
                           .Map(ArticleMapper.MapToDto)
                           .ToWebApi(context, ToOk, ToValidationProblem);

public class ArticleDtoValidator : AbstractValidator<ArticleDto>
{
    public ArticleDtoValidator()
    {
        RuleFor(x => x.Url).NotEmpty().WithMessage("must have a value;");
    }
}

DataAnnotationsValidationService

Calls DataAnnotations validation

IDataAnnotationsValidationService dataAnnotationsValidationService

e.g.

private static Results<Ok<ArticleDto>, ValidationProblem, BadRequest<ProblemDetails>> DataAnnotationsValidationHandler(HttpContext context,
                                                                                                                       IDataAnnotationsValidationService dataAnnotationsValidationService,
                                                                                                                       ArticleDto articleDto) =>
    dataAnnotationsValidationService.Execute(articleDto)
                                    .Map(() => new Article(null, articleDto.Url))
                                    .Map(ArticleMapper.MapToDto)
                                    .ToWebApi(context, ToOk, ToValidationProblem);

Comprehensive samples

There are examples showing the following:

  • A basic blog CRUD implementation
  • The ToDo sample from Damian Edwards here
  • Exception handling
  • Result error handling
  • Validation - DataAnnotations and FluentValidation and both combined

Comprehensive samples