Result

Result

A result abstraction that can be mapped to HTTP response codes if needed.

Docs

Docs are located in the /docs folder and available online at result.ardalis.com Please add issues for new docs requests and pull requests for docs issues are welcome!

Learn More

What Problem Does This Address?

Many methods on service need to return some kind of value. For instance, they may be looking up some data and returning a set of results or a single object. They might be creating something, persisting it, and then returning it. Typically, such methods are implemented like this:

publicCustomerGetCustomer(intcustomerId){// more logicreturncustomer;}publicCustomerCreateCustomer(stringfirstName,stringlastName){// more logicreturncustomer;}

This works great as long as we're only concerned with the happy path. But what happens if there are multiple failure modes, not all of which make sense to be handled by exceptions?

What happens if customerId is not found?
What happens if required lastName is not provided?
What happens if the current user doesn't have permission to create new customers?

The standard way to address these concerns is with exceptions. Maybe you throw a different exception for each different failure mode, and the calling code is then required to have multiple catch blocks designed for each type of failure. This makes life painful for the consumer, and results in a lot of exceptions for things that aren't necessarily exceptional. Like this:

[HttpGet]publicasyncTask<ActionResult<CustomerDTO>>GetCustomer(intcustomerId){try{varcustomer=_repository.GetById(customerId);varcustomerDTO=CustomerDTO.MapFrom(customer);returnOk(customerDTO);}catch(NullReferenceExceptionex){returnNotFound();}catch(Exceptionex){returnnewStatusCodeResult(StatusCodes.Status500InternalServerError);}}

Another approach is to return a Tuple of the expected result along with other things, like a status code and additional failure mode metadata. While tuples can be great for individual, flexible responses, they're not as good for having a single, standard, reusable approach to a problem.

The Result pattern provides a standard, reusable way to return both success as well as multiple kinds of non-success responses from .NET services in a way that can easily be mapped to API response types. Although the Ardalis.Result package has no dependencies on ASP.NET Core and can be used from any .NET Core application, the Ardalis.Result.AspNetCore companion package includes resources to enhance the use of this pattern within ASP.NET Core web API applications.

Sample Usage

Creating a Result

The sample folder includes some examples of how to use the project. Here are a couple of simple uses.

Imagine the snippet below is defined in a domain service that retrieves WeatherForecasts. When compared to the approach described above, this approach uses a result to handle common failure scenarios like missing data denoted as NotFound and or input validation errors denoted as Invalid. If execution is successful, the result will contain the random data generated by the final return statement.

publicResult<IEnumerable<WeatherForecast>>GetForecast(ForecastRequestDtomodel){if(model.PostalCode=="NotFound")returnResult<IEnumerable<WeatherForecast>>.NotFound();// validate modelif(model.PostalCode.Length>10){returnResult<IEnumerable<WeatherForecast>>.Invalid(newList<ValidationError>{newValidationError{Identifier=nameof(model.PostalCode),ErrorMessage="PostalCode cannot exceed 10 characters."}});}varrng=newRandom();returnnewResult<IEnumerable<WeatherForecast>>(Enumerable.Range(1,5).Select(index =>newWeatherForecast{Date=DateTime.Now.AddDays(index),TemperatureC=rng.Next(-20,55),Summary=Summaries[rng.Next(Summaries.Length)]}).ToArray());}

Translating Results to ActionResults

Continuing with the domain service example from the previous section, it's important to show that the domain service doesn't know about ActionResult or other MVC/etc types. But since it is using a Result<T> abstraction, it can return results that are easily mapped to HTTP status codes. Note that the method above returns a Result<IEnumerable<WeatherForecast> but in some cases, it might need to return an Invalid result, or a NotFound result. Otherwise, it returns a Success result with the actual returned value (just like an API would return an HTTP 200 and the actual result of the API call).

You can apply the [TranslateResultToActionResult] attribute to an API Endpoint (or controller action if you still use those things) and it will automatically translate the Result<T> return type of the method to an ActionResult<T> appropriately based on the Result type.

[TranslateResultToActionResult][HttpPost("Create")]publicResult<IEnumerable<WeatherForecast>>CreateForecast([FromBody]ForecastRequestDtomodel){return_weatherService.GetForecast(model);}

Alternatively, you can use the ToActionResult helper method within an endpoint to achieve the same thing:

[HttpPost("/Forecast/New")]publicoverrideActionResult<IEnumerable<WeatherForecast>>Handle(ForecastRequestDtorequest){returnthis.ToActionResult(_weatherService.GetForecast(request));// alternately// return _weatherService.GetForecast(request).ToActionResult(this);}

Translating Results to Minimal API Results

Similar to how the ToActionResult extension method translates Ardalis.Results to ActionResults, the ToMinimalApiResult translates results to the new Microsoft.AspNetCore.Http.ResultsIResult types in .NET 6+. The following code snippet demonstrates how one might use the domain service that returns a Result<IEnumerable<WeatherForecast>> and convert to a Microsoft.AspNetCore.Http.Results instance.

app.MapPost("/Forecast/New",(ForecastRequestDtorequest,WeatherServiceweatherService)=>{returnweatherService.GetForecast(request).ToMinimalApiResult();}).WithName("NewWeatherForecast");

The full Minimal API sample can be found in the sample folder.

Mapping Results From One Type to Another

A common use case is to map between domain entities to API response types usually represented as DTOs. You can map a result containing a domain entity to a Result containing a DTO by using the Map method. The following example calls the method _weatherService.GetSingleForecast which returns a Result<WeatherForecast> which is then converted to a Result<WeatherForecastSummaryDto> by the call to Map. Then, the result is converted to an ActionResult<WeatherForecastSummaryDto> using the ToActionResult helper method.

[HttpPost("Summary")]publicActionResult<WeatherForecastSummaryDto>CreateSummaryForecast([FromBody]ForecastRequestDtomodel){return_weatherService.GetSingleForecast(model).Map(wf =>newWeatherForecastSummaryDto(wf.Date,wf.Summary)).ToActionResult(this);}

Chaining Result Operations with Bind and BindAsync

You can chain together multiple operations that return Result<T> using the Bind and BindAsync methods. This allows you to perform a sequence of operations where each operation can fail, and if any operation fails, the subsequent operations will not be executed. This can be useful for eliminating checking for success after each Result operation with a more readable and maintainable chain of operations.

[HttpPost("Summary")]publicasyncTask<ActionResult<WeatherForecastSummaryDto>>CreateSummaryForecast([FromBody]ForecastRequestDtomodel){varresult1=await_weatherService.GetSingleForecast(model);if(!result1.IsSuccess){returnresult1.ToActionResult(this);}varresult2=await_weatherService.GetForecastDetailsAsync(result1.Value.Id);returnresult2.Map(details =>newWeatherForecastSummaryDto(details.Date,details.Summary)).ToActionResult(this);}

With the Bind and BindAsync methods, you can simplify this code by chaining the operations together. The following example demonstrates how to use BindAsync to achieve the same result in a more concise manner:

[HttpPost("BindedForecast")]publicasyncTask<ActionResult<WeatherForecastSummaryDto>>CreateSummaryForecastWithBind([FromBody]ForecastRequestDtomodel){returnawait_weatherService.GetSingleForecast(model).BindAsync(wf =>_weatherService.GetForecastDetailsAsync(wf.Id)).Map(details =>newWeatherForecastSummaryDto(details.Date,details.Summary)).ToActionResult(this);}

In this example, if GetSingleForecast returns a failure result, GetForecastDetailsAsync will not be called, and the failure will propagate through the chain. If all operations succeed, the final result will be mapped to a WeatherForecastSummaryDto and returned as an ActionResult.

ASP.NET API Metadata

By default, Asp Net Core and API Explorer know nothing about [TranslateResultToActionResult] and what it is doing. To reflect [TranslateResultToActionResult] behavior in metadata generated by API Explorer (which is then used by tools like Swashbuckle, NSwag etc.), you can use ResultConvention:

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

This will add [ProducesResponseType] for every known ResultStatus to every endpoint marked with [TranslateResultToActionResult]. To customize ResultConvention behavior, one may use the AddResultConvention method:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap()));

This code is functionally equivalent to the previous example.

From here you can modify the ResultStatus to HttpStatusCode mapping

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Ok,HttpStatusCode.OK, resultStatusOptions =>resultStatusOptions.For("POST",HttpStatusCode.Created).For("DELETE",HttpStatusCode.NoContent)).For(ResultStatus.Error,HttpStatusCode.InternalServerError)));

ResultConvention will add [ProducesResponseType] for every result status configured in ResultStatusMap. AddDefaultMap() maps every known ResultType, so if you want to exclude certain ResultType from being listed (e.g. your app doesn't have authentication and authorization, and you don't want 401 and 403 to be listed as SupportedResponseType) you can do this:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Ok,HttpStatusCode.OK, resultStatusOptions =>resultStatusOptions.For("POST",HttpStatusCode.Created).For("DELETE",HttpStatusCode.NoContent)).Remove(ResultStatus.Forbidden).Remove(ResultStatus.Unauthorized)));

Alternatively, you can specify which (failure) result statuses are expected from a certain endpoint:

[TranslateResultToActionResult()][ExpectedFailures(ResultStatus.NotFound,ResultStatus.Invalid)][HttpDelete("Remove/{id}")]publicResultRemovePerson(intid){// Method logic}

!!! If you list a certain Result status in ExpectedFailures, it must be configured in ResultConvention on startup.

Another configurable feature is what part of the Result object is returned in case of specific failure:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Error,HttpStatusCode.BadRequest, resultStatusOptions =>resultStatusOptions.With((ctrlr,result)=>string.Join("\r\n",result.ValidationErrors)))));

Using Results with FluentValidation

We can use Ardalis.Result.FluentValidation on a service with FluentValidation like that:

publicasyncTask<Result<BlogCategory>>UpdateAsync(BlogCategoryblogCategory){if(Guid.Empty==blogCategory.BlogCategoryId)returnResult<BlogCategory>.NotFound();varvalidator=newBlogCategoryValidator();varvalidation=awaitvalidator.ValidateAsync(blogCategory);if(!validation.IsValid){returnResult<BlogCategory>.Invalid(validation.AsErrors());}varitemToUpdate=(awaitGetByIdAsync(blogCategory.BlogCategoryId)).Value;if(itemToUpdate==null){returnResult<BlogCategory>.NotFound();}itemToUpdate.Update(blogCategory.Name,blogCategory.ParentId);returnResult<BlogCategory>.Success(await_blogCategoryRepository.UpdateAsync(itemToUpdate));}

Getting Started

If you're building an ASP.NET Core Web API you can simply install the Ardalis.Result.AspNetCore package to get started. Then, apply the [TranslateResultToActionResult] attribute to any actions or controllers that you want to automatically translate from Result types to ActionResult types.

Result

A result abstraction that can be mapped to HTTP response codes if needed.

Docs

Docs are located in the /docs folder and available online at result.ardalis.com Please add issues for new docs requests and pull requests for docs issues are welcome!

Learn More

What Problem Does This Address?

Many methods on service need to return some kind of value. For instance, they may be looking up some data and returning a set of results or a single object. They might be creating something, persisting it, and then returning it. Typically, such methods are implemented like this:

publicCustomerGetCustomer(intcustomerId){// more logicreturncustomer;}publicCustomerCreateCustomer(stringfirstName,stringlastName){// more logicreturncustomer;}

This works great as long as we're only concerned with the happy path. But what happens if there are multiple failure modes, not all of which make sense to be handled by exceptions?

What happens if customerId is not found?
What happens if required lastName is not provided?
What happens if the current user doesn't have permission to create new customers?

The standard way to address these concerns is with exceptions. Maybe you throw a different exception for each different failure mode, and the calling code is then required to have multiple catch blocks designed for each type of failure. This makes life painful for the consumer, and results in a lot of exceptions for things that aren't necessarily exceptional. Like this:

[HttpGet]publicasyncTask<ActionResult<CustomerDTO>>GetCustomer(intcustomerId){try{varcustomer=_repository.GetById(customerId);varcustomerDTO=CustomerDTO.MapFrom(customer);returnOk(customerDTO);}catch(NullReferenceExceptionex){returnNotFound();}catch(Exceptionex){returnnewStatusCodeResult(StatusCodes.Status500InternalServerError);}}

Another approach is to return a Tuple of the expected result along with other things, like a status code and additional failure mode metadata. While tuples can be great for individual, flexible responses, they're not as good for having a single, standard, reusable approach to a problem.

The Result pattern provides a standard, reusable way to return both success as well as multiple kinds of non-success responses from .NET services in a way that can easily be mapped to API response types. Although the Ardalis.Result package has no dependencies on ASP.NET Core and can be used from any .NET Core application, the Ardalis.Result.AspNetCore companion package includes resources to enhance the use of this pattern within ASP.NET Core web API applications.

Sample Usage

Creating a Result

The sample folder includes some examples of how to use the project. Here are a couple of simple uses.

Imagine the snippet below is defined in a domain service that retrieves WeatherForecasts. When compared to the approach described above, this approach uses a result to handle common failure scenarios like missing data denoted as NotFound and or input validation errors denoted as Invalid. If execution is successful, the result will contain the random data generated by the final return statement.

publicResult<IEnumerable<WeatherForecast>>GetForecast(ForecastRequestDtomodel){if(model.PostalCode=="NotFound")returnResult<IEnumerable<WeatherForecast>>.NotFound();// validate modelif(model.PostalCode.Length>10){returnResult<IEnumerable<WeatherForecast>>.Invalid(newList<ValidationError>{newValidationError{Identifier=nameof(model.PostalCode),ErrorMessage="PostalCode cannot exceed 10 characters."}});}varrng=newRandom();returnnewResult<IEnumerable<WeatherForecast>>(Enumerable.Range(1,5).Select(index =>newWeatherForecast{Date=DateTime.Now.AddDays(index),TemperatureC=rng.Next(-20,55),Summary=Summaries[rng.Next(Summaries.Length)]}).ToArray());}

Translating Results to ActionResults

Continuing with the domain service example from the previous section, it's important to show that the domain service doesn't know about ActionResult or other MVC/etc types. But since it is using a Result<T> abstraction, it can return results that are easily mapped to HTTP status codes. Note that the method above returns a Result<IEnumerable<WeatherForecast> but in some cases, it might need to return an Invalid result, or a NotFound result. Otherwise, it returns a Success result with the actual returned value (just like an API would return an HTTP 200 and the actual result of the API call).

You can apply the [TranslateResultToActionResult] attribute to an API Endpoint (or controller action if you still use those things) and it will automatically translate the Result<T> return type of the method to an ActionResult<T> appropriately based on the Result type.

[TranslateResultToActionResult][HttpPost("Create")]publicResult<IEnumerable<WeatherForecast>>CreateForecast([FromBody]ForecastRequestDtomodel){return_weatherService.GetForecast(model);}

Alternatively, you can use the ToActionResult helper method within an endpoint to achieve the same thing:

[HttpPost("/Forecast/New")]publicoverrideActionResult<IEnumerable<WeatherForecast>>Handle(ForecastRequestDtorequest){returnthis.ToActionResult(_weatherService.GetForecast(request));// alternately// return _weatherService.GetForecast(request).ToActionResult(this);}

Translating Results to Minimal API Results

Similar to how the ToActionResult extension method translates Ardalis.Results to ActionResults, the ToMinimalApiResult translates results to the new Microsoft.AspNetCore.Http.ResultsIResult types in .NET 6+. The following code snippet demonstrates how one might use the domain service that returns a Result<IEnumerable<WeatherForecast>> and convert to a Microsoft.AspNetCore.Http.Results instance.

app.MapPost("/Forecast/New",(ForecastRequestDtorequest,WeatherServiceweatherService)=>{returnweatherService.GetForecast(request).ToMinimalApiResult();}).WithName("NewWeatherForecast");

The full Minimal API sample can be found in the sample folder.

Mapping Results From One Type to Another

A common use case is to map between domain entities to API response types usually represented as DTOs. You can map a result containing a domain entity to a Result containing a DTO by using the Map method. The following example calls the method _weatherService.GetSingleForecast which returns a Result<WeatherForecast> which is then converted to a Result<WeatherForecastSummaryDto> by the call to Map. Then, the result is converted to an ActionResult<WeatherForecastSummaryDto> using the ToActionResult helper method.

[HttpPost("Summary")]publicActionResult<WeatherForecastSummaryDto>CreateSummaryForecast([FromBody]ForecastRequestDtomodel){return_weatherService.GetSingleForecast(model).Map(wf =>newWeatherForecastSummaryDto(wf.Date,wf.Summary)).ToActionResult(this);}

Chaining Result Operations with Bind and BindAsync

You can chain together multiple operations that return Result<T> using the Bind and BindAsync methods. This allows you to perform a sequence of operations where each operation can fail, and if any operation fails, the subsequent operations will not be executed. This can be useful for eliminating checking for success after each Result operation with a more readable and maintainable chain of operations.

[HttpPost("Summary")]publicasyncTask<ActionResult<WeatherForecastSummaryDto>>CreateSummaryForecast([FromBody]ForecastRequestDtomodel){varresult1=await_weatherService.GetSingleForecast(model);if(!result1.IsSuccess){returnresult1.ToActionResult(this);}varresult2=await_weatherService.GetForecastDetailsAsync(result1.Value.Id);returnresult2.Map(details =>newWeatherForecastSummaryDto(details.Date,details.Summary)).ToActionResult(this);}

With the Bind and BindAsync methods, you can simplify this code by chaining the operations together. The following example demonstrates how to use BindAsync to achieve the same result in a more concise manner:

[HttpPost("BindedForecast")]publicasyncTask<ActionResult<WeatherForecastSummaryDto>>CreateSummaryForecastWithBind([FromBody]ForecastRequestDtomodel){returnawait_weatherService.GetSingleForecast(model).BindAsync(wf =>_weatherService.GetForecastDetailsAsync(wf.Id)).Map(details =>newWeatherForecastSummaryDto(details.Date,details.Summary)).ToActionResult(this);}

In this example, if GetSingleForecast returns a failure result, GetForecastDetailsAsync will not be called, and the failure will propagate through the chain. If all operations succeed, the final result will be mapped to a WeatherForecastSummaryDto and returned as an ActionResult.

ASP.NET API Metadata

By default, Asp Net Core and API Explorer know nothing about [TranslateResultToActionResult] and what it is doing. To reflect [TranslateResultToActionResult] behavior in metadata generated by API Explorer (which is then used by tools like Swashbuckle, NSwag etc.), you can use ResultConvention:

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

This will add [ProducesResponseType] for every known ResultStatus to every endpoint marked with [TranslateResultToActionResult]. To customize ResultConvention behavior, one may use the AddResultConvention method:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap()));

This code is functionally equivalent to the previous example.

From here you can modify the ResultStatus to HttpStatusCode mapping

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Ok,HttpStatusCode.OK, resultStatusOptions =>resultStatusOptions.For("POST",HttpStatusCode.Created).For("DELETE",HttpStatusCode.NoContent)).For(ResultStatus.Error,HttpStatusCode.InternalServerError)));

ResultConvention will add [ProducesResponseType] for every result status configured in ResultStatusMap. AddDefaultMap() maps every known ResultType, so if you want to exclude certain ResultType from being listed (e.g. your app doesn't have authentication and authorization, and you don't want 401 and 403 to be listed as SupportedResponseType) you can do this:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Ok,HttpStatusCode.OK, resultStatusOptions =>resultStatusOptions.For("POST",HttpStatusCode.Created).For("DELETE",HttpStatusCode.NoContent)).Remove(ResultStatus.Forbidden).Remove(ResultStatus.Unauthorized)));

Alternatively, you can specify which (failure) result statuses are expected from a certain endpoint:

[TranslateResultToActionResult()][ExpectedFailures(ResultStatus.NotFound,ResultStatus.Invalid)][HttpDelete("Remove/{id}")]publicResultRemovePerson(intid){// Method logic}

!!! If you list a certain Result status in ExpectedFailures, it must be configured in ResultConvention on startup.

Another configurable feature is what part of the Result object is returned in case of specific failure:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Error,HttpStatusCode.BadRequest, resultStatusOptions =>resultStatusOptions.With((ctrlr,result)=>string.Join("\r\n",result.ValidationErrors)))));

Using Results with FluentValidation

We can use Ardalis.Result.FluentValidation on a service with FluentValidation like that:

publicasyncTask<Result<BlogCategory>>UpdateAsync(BlogCategoryblogCategory){if(Guid.Empty==blogCategory.BlogCategoryId)returnResult<BlogCategory>.NotFound();varvalidator=newBlogCategoryValidator();varvalidation=awaitvalidator.ValidateAsync(blogCategory);if(!validation.IsValid){returnResult<BlogCategory>.Invalid(validation.AsErrors());}varitemToUpdate=(awaitGetByIdAsync(blogCategory.BlogCategoryId)).Value;if(itemToUpdate==null){returnResult<BlogCategory>.NotFound();}itemToUpdate.Update(blogCategory.Name,blogCategory.ParentId);returnResult<BlogCategory>.Success(await_blogCategoryRepository.UpdateAsync(itemToUpdate));}

Getting Started

If you're building an ASP.NET Core Web API you can simply install the Ardalis.Result.AspNetCore package to get started. Then, apply the [TranslateResultToActionResult] attribute to any actions or controllers that you want to automatically translate from Result types to ActionResult types.

Result

A result abstraction that can be mapped to HTTP response codes if needed.

Docs

Docs are located in the /docs folder and available online at result.ardalis.com Please add issues for new docs requests and pull requests for docs issues are welcome!

Learn More

What Problem Does This Address?

Many methods on service need to return some kind of value. For instance, they may be looking up some data and returning a set of results or a single object. They might be creating something, persisting it, and then returning it. Typically, such methods are implemented like this:

publicCustomerGetCustomer(intcustomerId){// more logicreturncustomer;}publicCustomerCreateCustomer(stringfirstName,stringlastName){// more logicreturncustomer;}

This works great as long as we're only concerned with the happy path. But what happens if there are multiple failure modes, not all of which make sense to be handled by exceptions?

What happens if customerId is not found?
What happens if required lastName is not provided?
What happens if the current user doesn't have permission to create new customers?

The standard way to address these concerns is with exceptions. Maybe you throw a different exception for each different failure mode, and the calling code is then required to have multiple catch blocks designed for each type of failure. This makes life painful for the consumer, and results in a lot of exceptions for things that aren't necessarily exceptional. Like this:

[HttpGet]publicasyncTask<ActionResult<CustomerDTO>>GetCustomer(intcustomerId){try{varcustomer=_repository.GetById(customerId);varcustomerDTO=CustomerDTO.MapFrom(customer);returnOk(customerDTO);}catch(NullReferenceExceptionex){returnNotFound();}catch(Exceptionex){returnnewStatusCodeResult(StatusCodes.Status500InternalServerError);}}

Another approach is to return a Tuple of the expected result along with other things, like a status code and additional failure mode metadata. While tuples can be great for individual, flexible responses, they're not as good for having a single, standard, reusable approach to a problem.

The Result pattern provides a standard, reusable way to return both success as well as multiple kinds of non-success responses from .NET services in a way that can easily be mapped to API response types. Although the Ardalis.Result package has no dependencies on ASP.NET Core and can be used from any .NET Core application, the Ardalis.Result.AspNetCore companion package includes resources to enhance the use of this pattern within ASP.NET Core web API applications.

Sample Usage

Creating a Result

The sample folder includes some examples of how to use the project. Here are a couple of simple uses.

Imagine the snippet below is defined in a domain service that retrieves WeatherForecasts. When compared to the approach described above, this approach uses a result to handle common failure scenarios like missing data denoted as NotFound and or input validation errors denoted as Invalid. If execution is successful, the result will contain the random data generated by the final return statement.

publicResult<IEnumerable<WeatherForecast>>GetForecast(ForecastRequestDtomodel){if(model.PostalCode=="NotFound")returnResult<IEnumerable<WeatherForecast>>.NotFound();// validate modelif(model.PostalCode.Length>10){returnResult<IEnumerable<WeatherForecast>>.Invalid(newList<ValidationError>{newValidationError{Identifier=nameof(model.PostalCode),ErrorMessage="PostalCode cannot exceed 10 characters."}});}varrng=newRandom();returnnewResult<IEnumerable<WeatherForecast>>(Enumerable.Range(1,5).Select(index =>newWeatherForecast{Date=DateTime.Now.AddDays(index),TemperatureC=rng.Next(-20,55),Summary=Summaries[rng.Next(Summaries.Length)]}).ToArray());}

Translating Results to ActionResults

Continuing with the domain service example from the previous section, it's important to show that the domain service doesn't know about ActionResult or other MVC/etc types. But since it is using a Result<T> abstraction, it can return results that are easily mapped to HTTP status codes. Note that the method above returns a Result<IEnumerable<WeatherForecast> but in some cases, it might need to return an Invalid result, or a NotFound result. Otherwise, it returns a Success result with the actual returned value (just like an API would return an HTTP 200 and the actual result of the API call).

You can apply the [TranslateResultToActionResult] attribute to an API Endpoint (or controller action if you still use those things) and it will automatically translate the Result<T> return type of the method to an ActionResult<T> appropriately based on the Result type.

[TranslateResultToActionResult][HttpPost("Create")]publicResult<IEnumerable<WeatherForecast>>CreateForecast([FromBody]ForecastRequestDtomodel){return_weatherService.GetForecast(model);}

Alternatively, you can use the ToActionResult helper method within an endpoint to achieve the same thing:

[HttpPost("/Forecast/New")]publicoverrideActionResult<IEnumerable<WeatherForecast>>Handle(ForecastRequestDtorequest){returnthis.ToActionResult(_weatherService.GetForecast(request));// alternately// return _weatherService.GetForecast(request).ToActionResult(this);}

Translating Results to Minimal API Results

Similar to how the ToActionResult extension method translates Ardalis.Results to ActionResults, the ToMinimalApiResult translates results to the new Microsoft.AspNetCore.Http.ResultsIResult types in .NET 6+. The following code snippet demonstrates how one might use the domain service that returns a Result<IEnumerable<WeatherForecast>> and convert to a Microsoft.AspNetCore.Http.Results instance.

app.MapPost("/Forecast/New",(ForecastRequestDtorequest,WeatherServiceweatherService)=>{returnweatherService.GetForecast(request).ToMinimalApiResult();}).WithName("NewWeatherForecast");

The full Minimal API sample can be found in the sample folder.

Mapping Results From One Type to Another

A common use case is to map between domain entities to API response types usually represented as DTOs. You can map a result containing a domain entity to a Result containing a DTO by using the Map method. The following example calls the method _weatherService.GetSingleForecast which returns a Result<WeatherForecast> which is then converted to a Result<WeatherForecastSummaryDto> by the call to Map. Then, the result is converted to an ActionResult<WeatherForecastSummaryDto> using the ToActionResult helper method.

[HttpPost("Summary")]publicActionResult<WeatherForecastSummaryDto>CreateSummaryForecast([FromBody]ForecastRequestDtomodel){return_weatherService.GetSingleForecast(model).Map(wf =>newWeatherForecastSummaryDto(wf.Date,wf.Summary)).ToActionResult(this);}

Chaining Result Operations with Bind and BindAsync

You can chain together multiple operations that return Result<T> using the Bind and BindAsync methods. This allows you to perform a sequence of operations where each operation can fail, and if any operation fails, the subsequent operations will not be executed. This can be useful for eliminating checking for success after each Result operation with a more readable and maintainable chain of operations.

[HttpPost("Summary")]publicasyncTask<ActionResult<WeatherForecastSummaryDto>>CreateSummaryForecast([FromBody]ForecastRequestDtomodel){varresult1=await_weatherService.GetSingleForecast(model);if(!result1.IsSuccess){returnresult1.ToActionResult(this);}varresult2=await_weatherService.GetForecastDetailsAsync(result1.Value.Id);returnresult2.Map(details =>newWeatherForecastSummaryDto(details.Date,details.Summary)).ToActionResult(this);}

With the Bind and BindAsync methods, you can simplify this code by chaining the operations together. The following example demonstrates how to use BindAsync to achieve the same result in a more concise manner:

[HttpPost("BindedForecast")]publicasyncTask<ActionResult<WeatherForecastSummaryDto>>CreateSummaryForecastWithBind([FromBody]ForecastRequestDtomodel){returnawait_weatherService.GetSingleForecast(model).BindAsync(wf =>_weatherService.GetForecastDetailsAsync(wf.Id)).Map(details =>newWeatherForecastSummaryDto(details.Date,details.Summary)).ToActionResult(this);}

In this example, if GetSingleForecast returns a failure result, GetForecastDetailsAsync will not be called, and the failure will propagate through the chain. If all operations succeed, the final result will be mapped to a WeatherForecastSummaryDto and returned as an ActionResult.

ASP.NET API Metadata

By default, Asp Net Core and API Explorer know nothing about [TranslateResultToActionResult] and what it is doing. To reflect [TranslateResultToActionResult] behavior in metadata generated by API Explorer (which is then used by tools like Swashbuckle, NSwag etc.), you can use ResultConvention:

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

This will add [ProducesResponseType] for every known ResultStatus to every endpoint marked with [TranslateResultToActionResult]. To customize ResultConvention behavior, one may use the AddResultConvention method:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap()));

This code is functionally equivalent to the previous example.

From here you can modify the ResultStatus to HttpStatusCode mapping

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Ok,HttpStatusCode.OK, resultStatusOptions =>resultStatusOptions.For("POST",HttpStatusCode.Created).For("DELETE",HttpStatusCode.NoContent)).For(ResultStatus.Error,HttpStatusCode.InternalServerError)));

ResultConvention will add [ProducesResponseType] for every result status configured in ResultStatusMap. AddDefaultMap() maps every known ResultType, so if you want to exclude certain ResultType from being listed (e.g. your app doesn't have authentication and authorization, and you don't want 401 and 403 to be listed as SupportedResponseType) you can do this:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Ok,HttpStatusCode.OK, resultStatusOptions =>resultStatusOptions.For("POST",HttpStatusCode.Created).For("DELETE",HttpStatusCode.NoContent)).Remove(ResultStatus.Forbidden).Remove(ResultStatus.Unauthorized)));

Alternatively, you can specify which (failure) result statuses are expected from a certain endpoint:

[TranslateResultToActionResult()][ExpectedFailures(ResultStatus.NotFound,ResultStatus.Invalid)][HttpDelete("Remove/{id}")]publicResultRemovePerson(intid){// Method logic}

!!! If you list a certain Result status in ExpectedFailures, it must be configured in ResultConvention on startup.

Another configurable feature is what part of the Result object is returned in case of specific failure:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Error,HttpStatusCode.BadRequest, resultStatusOptions =>resultStatusOptions.With((ctrlr,result)=>string.Join("\r\n",result.ValidationErrors)))));

Using Results with FluentValidation

We can use Ardalis.Result.FluentValidation on a service with FluentValidation like that:

publicasyncTask<Result<BlogCategory>>UpdateAsync(BlogCategoryblogCategory){if(Guid.Empty==blogCategory.BlogCategoryId)returnResult<BlogCategory>.NotFound();varvalidator=newBlogCategoryValidator();varvalidation=awaitvalidator.ValidateAsync(blogCategory);if(!validation.IsValid){returnResult<BlogCategory>.Invalid(validation.AsErrors());}varitemToUpdate=(awaitGetByIdAsync(blogCategory.BlogCategoryId)).Value;if(itemToUpdate==null){returnResult<BlogCategory>.NotFound();}itemToUpdate.Update(blogCategory.Name,blogCategory.ParentId);returnResult<BlogCategory>.Success(await_blogCategoryRepository.UpdateAsync(itemToUpdate));}

Getting Started

If you're building an ASP.NET Core Web API you can simply install the Ardalis.Result.AspNetCore package to get started. Then, apply the [TranslateResultToActionResult] attribute to any actions or controllers that you want to automatically translate from Result types to ActionResult types.

Result

A result abstraction that can be mapped to HTTP response codes if needed.

Docs

Docs are located in the /docs folder and available online at result.ardalis.com Please add issues for new docs requests and pull requests for docs issues are welcome!

Learn More

What Problem Does This Address?

Many methods on service need to return some kind of value. For instance, they may be looking up some data and returning a set of results or a single object. They might be creating something, persisting it, and then returning it. Typically, such methods are implemented like this:

publicCustomerGetCustomer(intcustomerId){// more logicreturncustomer;}publicCustomerCreateCustomer(stringfirstName,stringlastName){// more logicreturncustomer;}

This works great as long as we're only concerned with the happy path. But what happens if there are multiple failure modes, not all of which make sense to be handled by exceptions?

What happens if customerId is not found?
What happens if required lastName is not provided?
What happens if the current user doesn't have permission to create new customers?

The standard way to address these concerns is with exceptions. Maybe you throw a different exception for each different failure mode, and the calling code is then required to have multiple catch blocks designed for each type of failure. This makes life painful for the consumer, and results in a lot of exceptions for things that aren't necessarily exceptional. Like this:

[HttpGet]publicasyncTask<ActionResult<CustomerDTO>>GetCustomer(intcustomerId){try{varcustomer=_repository.GetById(customerId);varcustomerDTO=CustomerDTO.MapFrom(customer);returnOk(customerDTO);}catch(NullReferenceExceptionex){returnNotFound();}catch(Exceptionex){returnnewStatusCodeResult(StatusCodes.Status500InternalServerError);}}

Another approach is to return a Tuple of the expected result along with other things, like a status code and additional failure mode metadata. While tuples can be great for individual, flexible responses, they're not as good for having a single, standard, reusable approach to a problem.

The Result pattern provides a standard, reusable way to return both success as well as multiple kinds of non-success responses from .NET services in a way that can easily be mapped to API response types. Although the Ardalis.Result package has no dependencies on ASP.NET Core and can be used from any .NET Core application, the Ardalis.Result.AspNetCore companion package includes resources to enhance the use of this pattern within ASP.NET Core web API applications.

Sample Usage

Creating a Result

The sample folder includes some examples of how to use the project. Here are a couple of simple uses.

Imagine the snippet below is defined in a domain service that retrieves WeatherForecasts. When compared to the approach described above, this approach uses a result to handle common failure scenarios like missing data denoted as NotFound and or input validation errors denoted as Invalid. If execution is successful, the result will contain the random data generated by the final return statement.

publicResult<IEnumerable<WeatherForecast>>GetForecast(ForecastRequestDtomodel){if(model.PostalCode=="NotFound")returnResult<IEnumerable<WeatherForecast>>.NotFound();// validate modelif(model.PostalCode.Length>10){returnResult<IEnumerable<WeatherForecast>>.Invalid(newList<ValidationError>{newValidationError{Identifier=nameof(model.PostalCode),ErrorMessage="PostalCode cannot exceed 10 characters."}});}varrng=newRandom();returnnewResult<IEnumerable<WeatherForecast>>(Enumerable.Range(1,5).Select(index =>newWeatherForecast{Date=DateTime.Now.AddDays(index),TemperatureC=rng.Next(-20,55),Summary=Summaries[rng.Next(Summaries.Length)]}).ToArray());}

Translating Results to ActionResults

Continuing with the domain service example from the previous section, it's important to show that the domain service doesn't know about ActionResult or other MVC/etc types. But since it is using a Result<T> abstraction, it can return results that are easily mapped to HTTP status codes. Note that the method above returns a Result<IEnumerable<WeatherForecast> but in some cases, it might need to return an Invalid result, or a NotFound result. Otherwise, it returns a Success result with the actual returned value (just like an API would return an HTTP 200 and the actual result of the API call).

You can apply the [TranslateResultToActionResult] attribute to an API Endpoint (or controller action if you still use those things) and it will automatically translate the Result<T> return type of the method to an ActionResult<T> appropriately based on the Result type.

[TranslateResultToActionResult][HttpPost("Create")]publicResult<IEnumerable<WeatherForecast>>CreateForecast([FromBody]ForecastRequestDtomodel){return_weatherService.GetForecast(model);}

Alternatively, you can use the ToActionResult helper method within an endpoint to achieve the same thing:

[HttpPost("/Forecast/New")]publicoverrideActionResult<IEnumerable<WeatherForecast>>Handle(ForecastRequestDtorequest){returnthis.ToActionResult(_weatherService.GetForecast(request));// alternately// return _weatherService.GetForecast(request).ToActionResult(this);}

Translating Results to Minimal API Results

Similar to how the ToActionResult extension method translates Ardalis.Results to ActionResults, the ToMinimalApiResult translates results to the new Microsoft.AspNetCore.Http.ResultsIResult types in .NET 6+. The following code snippet demonstrates how one might use the domain service that returns a Result<IEnumerable<WeatherForecast>> and convert to a Microsoft.AspNetCore.Http.Results instance.

app.MapPost("/Forecast/New",(ForecastRequestDtorequest,WeatherServiceweatherService)=>{returnweatherService.GetForecast(request).ToMinimalApiResult();}).WithName("NewWeatherForecast");

The full Minimal API sample can be found in the sample folder.

Mapping Results From One Type to Another

A common use case is to map between domain entities to API response types usually represented as DTOs. You can map a result containing a domain entity to a Result containing a DTO by using the Map method. The following example calls the method _weatherService.GetSingleForecast which returns a Result<WeatherForecast> which is then converted to a Result<WeatherForecastSummaryDto> by the call to Map. Then, the result is converted to an ActionResult<WeatherForecastSummaryDto> using the ToActionResult helper method.

[HttpPost("Summary")]publicActionResult<WeatherForecastSummaryDto>CreateSummaryForecast([FromBody]ForecastRequestDtomodel){return_weatherService.GetSingleForecast(model).Map(wf =>newWeatherForecastSummaryDto(wf.Date,wf.Summary)).ToActionResult(this);}

Chaining Result Operations with Bind and BindAsync

You can chain together multiple operations that return Result<T> using the Bind and BindAsync methods. This allows you to perform a sequence of operations where each operation can fail, and if any operation fails, the subsequent operations will not be executed. This can be useful for eliminating checking for success after each Result operation with a more readable and maintainable chain of operations.

[HttpPost("Summary")]publicasyncTask<ActionResult<WeatherForecastSummaryDto>>CreateSummaryForecast([FromBody]ForecastRequestDtomodel){varresult1=await_weatherService.GetSingleForecast(model);if(!result1.IsSuccess){returnresult1.ToActionResult(this);}varresult2=await_weatherService.GetForecastDetailsAsync(result1.Value.Id);returnresult2.Map(details =>newWeatherForecastSummaryDto(details.Date,details.Summary)).ToActionResult(this);}

With the Bind and BindAsync methods, you can simplify this code by chaining the operations together. The following example demonstrates how to use BindAsync to achieve the same result in a more concise manner:

[HttpPost("BindedForecast")]publicasyncTask<ActionResult<WeatherForecastSummaryDto>>CreateSummaryForecastWithBind([FromBody]ForecastRequestDtomodel){returnawait_weatherService.GetSingleForecast(model).BindAsync(wf =>_weatherService.GetForecastDetailsAsync(wf.Id)).Map(details =>newWeatherForecastSummaryDto(details.Date,details.Summary)).ToActionResult(this);}

In this example, if GetSingleForecast returns a failure result, GetForecastDetailsAsync will not be called, and the failure will propagate through the chain. If all operations succeed, the final result will be mapped to a WeatherForecastSummaryDto and returned as an ActionResult.

ASP.NET API Metadata

By default, Asp Net Core and API Explorer know nothing about [TranslateResultToActionResult] and what it is doing. To reflect [TranslateResultToActionResult] behavior in metadata generated by API Explorer (which is then used by tools like Swashbuckle, NSwag etc.), you can use ResultConvention:

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

This will add [ProducesResponseType] for every known ResultStatus to every endpoint marked with [TranslateResultToActionResult]. To customize ResultConvention behavior, one may use the AddResultConvention method:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap()));

This code is functionally equivalent to the previous example.

From here you can modify the ResultStatus to HttpStatusCode mapping

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Ok,HttpStatusCode.OK, resultStatusOptions =>resultStatusOptions.For("POST",HttpStatusCode.Created).For("DELETE",HttpStatusCode.NoContent)).For(ResultStatus.Error,HttpStatusCode.InternalServerError)));

ResultConvention will add [ProducesResponseType] for every result status configured in ResultStatusMap. AddDefaultMap() maps every known ResultType, so if you want to exclude certain ResultType from being listed (e.g. your app doesn't have authentication and authorization, and you don't want 401 and 403 to be listed as SupportedResponseType) you can do this:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Ok,HttpStatusCode.OK, resultStatusOptions =>resultStatusOptions.For("POST",HttpStatusCode.Created).For("DELETE",HttpStatusCode.NoContent)).Remove(ResultStatus.Forbidden).Remove(ResultStatus.Unauthorized)));

Alternatively, you can specify which (failure) result statuses are expected from a certain endpoint:

[TranslateResultToActionResult()][ExpectedFailures(ResultStatus.NotFound,ResultStatus.Invalid)][HttpDelete("Remove/{id}")]publicResultRemovePerson(intid){// Method logic}

!!! If you list a certain Result status in ExpectedFailures, it must be configured in ResultConvention on startup.

Another configurable feature is what part of the Result object is returned in case of specific failure:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Error,HttpStatusCode.BadRequest, resultStatusOptions =>resultStatusOptions.With((ctrlr,result)=>string.Join("\r\n",result.ValidationErrors)))));

Using Results with FluentValidation

We can use Ardalis.Result.FluentValidation on a service with FluentValidation like that:

publicasyncTask<Result<BlogCategory>>UpdateAsync(BlogCategoryblogCategory){if(Guid.Empty==blogCategory.BlogCategoryId)returnResult<BlogCategory>.NotFound();varvalidator=newBlogCategoryValidator();varvalidation=awaitvalidator.ValidateAsync(blogCategory);if(!validation.IsValid){returnResult<BlogCategory>.Invalid(validation.AsErrors());}varitemToUpdate=(awaitGetByIdAsync(blogCategory.BlogCategoryId)).Value;if(itemToUpdate==null){returnResult<BlogCategory>.NotFound();}itemToUpdate.Update(blogCategory.Name,blogCategory.ParentId);returnResult<BlogCategory>.Success(await_blogCategoryRepository.UpdateAsync(itemToUpdate));}

Getting Started

If you're building an ASP.NET Core Web API you can simply install the Ardalis.Result.AspNetCore package to get started. Then, apply the [TranslateResultToActionResult] attribute to any actions or controllers that you want to automatically translate from Result types to ActionResult types.

Result

A result abstraction that can be mapped to HTTP response codes if needed.

Docs

Docs are located in the /docs folder and available online at result.ardalis.com Please add issues for new docs requests and pull requests for docs issues are welcome!

Learn More

What Problem Does This Address?

Many methods on service need to return some kind of value. For instance, they may be looking up some data and returning a set of results or a single object. They might be creating something, persisting it, and then returning it. Typically, such methods are implemented like this:

publicCustomerGetCustomer(intcustomerId){// more logicreturncustomer;}publicCustomerCreateCustomer(stringfirstName,stringlastName){// more logicreturncustomer;}

This works great as long as we're only concerned with the happy path. But what happens if there are multiple failure modes, not all of which make sense to be handled by exceptions?

What happens if customerId is not found?
What happens if required lastName is not provided?
What happens if the current user doesn't have permission to create new customers?

The standard way to address these concerns is with exceptions. Maybe you throw a different exception for each different failure mode, and the calling code is then required to have multiple catch blocks designed for each type of failure. This makes life painful for the consumer, and results in a lot of exceptions for things that aren't necessarily exceptional. Like this:

[HttpGet]publicasyncTask<ActionResult<CustomerDTO>>GetCustomer(intcustomerId){try{varcustomer=_repository.GetById(customerId);varcustomerDTO=CustomerDTO.MapFrom(customer);returnOk(customerDTO);}catch(NullReferenceExceptionex){returnNotFound();}catch(Exceptionex){returnnewStatusCodeResult(StatusCodes.Status500InternalServerError);}}

Another approach is to return a Tuple of the expected result along with other things, like a status code and additional failure mode metadata. While tuples can be great for individual, flexible responses, they're not as good for having a single, standard, reusable approach to a problem.

The Result pattern provides a standard, reusable way to return both success as well as multiple kinds of non-success responses from .NET services in a way that can easily be mapped to API response types. Although the Ardalis.Result package has no dependencies on ASP.NET Core and can be used from any .NET Core application, the Ardalis.Result.AspNetCore companion package includes resources to enhance the use of this pattern within ASP.NET Core web API applications.

Sample Usage

Creating a Result

The sample folder includes some examples of how to use the project. Here are a couple of simple uses.

Imagine the snippet below is defined in a domain service that retrieves WeatherForecasts. When compared to the approach described above, this approach uses a result to handle common failure scenarios like missing data denoted as NotFound and or input validation errors denoted as Invalid. If execution is successful, the result will contain the random data generated by the final return statement.

publicResult<IEnumerable<WeatherForecast>>GetForecast(ForecastRequestDtomodel){if(model.PostalCode=="NotFound")returnResult<IEnumerable<WeatherForecast>>.NotFound();// validate modelif(model.PostalCode.Length>10){returnResult<IEnumerable<WeatherForecast>>.Invalid(newList<ValidationError>{newValidationError{Identifier=nameof(model.PostalCode),ErrorMessage="PostalCode cannot exceed 10 characters."}});}varrng=newRandom();returnnewResult<IEnumerable<WeatherForecast>>(Enumerable.Range(1,5).Select(index =>newWeatherForecast{Date=DateTime.Now.AddDays(index),TemperatureC=rng.Next(-20,55),Summary=Summaries[rng.Next(Summaries.Length)]}).ToArray());}

Translating Results to ActionResults

Continuing with the domain service example from the previous section, it's important to show that the domain service doesn't know about ActionResult or other MVC/etc types. But since it is using a Result<T> abstraction, it can return results that are easily mapped to HTTP status codes. Note that the method above returns a Result<IEnumerable<WeatherForecast> but in some cases, it might need to return an Invalid result, or a NotFound result. Otherwise, it returns a Success result with the actual returned value (just like an API would return an HTTP 200 and the actual result of the API call).

You can apply the [TranslateResultToActionResult] attribute to an API Endpoint (or controller action if you still use those things) and it will automatically translate the Result<T> return type of the method to an ActionResult<T> appropriately based on the Result type.

[TranslateResultToActionResult][HttpPost("Create")]publicResult<IEnumerable<WeatherForecast>>CreateForecast([FromBody]ForecastRequestDtomodel){return_weatherService.GetForecast(model);}

Alternatively, you can use the ToActionResult helper method within an endpoint to achieve the same thing:

[HttpPost("/Forecast/New")]publicoverrideActionResult<IEnumerable<WeatherForecast>>Handle(ForecastRequestDtorequest){returnthis.ToActionResult(_weatherService.GetForecast(request));// alternately// return _weatherService.GetForecast(request).ToActionResult(this);}

Translating Results to Minimal API Results

Similar to how the ToActionResult extension method translates Ardalis.Results to ActionResults, the ToMinimalApiResult translates results to the new Microsoft.AspNetCore.Http.ResultsIResult types in .NET 6+. The following code snippet demonstrates how one might use the domain service that returns a Result<IEnumerable<WeatherForecast>> and convert to a Microsoft.AspNetCore.Http.Results instance.

app.MapPost("/Forecast/New",(ForecastRequestDtorequest,WeatherServiceweatherService)=>{returnweatherService.GetForecast(request).ToMinimalApiResult();}).WithName("NewWeatherForecast");

The full Minimal API sample can be found in the sample folder.

Mapping Results From One Type to Another

A common use case is to map between domain entities to API response types usually represented as DTOs. You can map a result containing a domain entity to a Result containing a DTO by using the Map method. The following example calls the method _weatherService.GetSingleForecast which returns a Result<WeatherForecast> which is then converted to a Result<WeatherForecastSummaryDto> by the call to Map. Then, the result is converted to an ActionResult<WeatherForecastSummaryDto> using the ToActionResult helper method.

[HttpPost("Summary")]publicActionResult<WeatherForecastSummaryDto>CreateSummaryForecast([FromBody]ForecastRequestDtomodel){return_weatherService.GetSingleForecast(model).Map(wf =>newWeatherForecastSummaryDto(wf.Date,wf.Summary)).ToActionResult(this);}

Chaining Result Operations with Bind and BindAsync

You can chain together multiple operations that return Result<T> using the Bind and BindAsync methods. This allows you to perform a sequence of operations where each operation can fail, and if any operation fails, the subsequent operations will not be executed. This can be useful for eliminating checking for success after each Result operation with a more readable and maintainable chain of operations.

[HttpPost("Summary")]publicasyncTask<ActionResult<WeatherForecastSummaryDto>>CreateSummaryForecast([FromBody]ForecastRequestDtomodel){varresult1=await_weatherService.GetSingleForecast(model);if(!result1.IsSuccess){returnresult1.ToActionResult(this);}varresult2=await_weatherService.GetForecastDetailsAsync(result1.Value.Id);returnresult2.Map(details =>newWeatherForecastSummaryDto(details.Date,details.Summary)).ToActionResult(this);}

With the Bind and BindAsync methods, you can simplify this code by chaining the operations together. The following example demonstrates how to use BindAsync to achieve the same result in a more concise manner:

[HttpPost("BindedForecast")]publicasyncTask<ActionResult<WeatherForecastSummaryDto>>CreateSummaryForecastWithBind([FromBody]ForecastRequestDtomodel){returnawait_weatherService.GetSingleForecast(model).BindAsync(wf =>_weatherService.GetForecastDetailsAsync(wf.Id)).Map(details =>newWeatherForecastSummaryDto(details.Date,details.Summary)).ToActionResult(this);}

In this example, if GetSingleForecast returns a failure result, GetForecastDetailsAsync will not be called, and the failure will propagate through the chain. If all operations succeed, the final result will be mapped to a WeatherForecastSummaryDto and returned as an ActionResult.

ASP.NET API Metadata

By default, Asp Net Core and API Explorer know nothing about [TranslateResultToActionResult] and what it is doing. To reflect [TranslateResultToActionResult] behavior in metadata generated by API Explorer (which is then used by tools like Swashbuckle, NSwag etc.), you can use ResultConvention:

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

This will add [ProducesResponseType] for every known ResultStatus to every endpoint marked with [TranslateResultToActionResult]. To customize ResultConvention behavior, one may use the AddResultConvention method:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap()));

This code is functionally equivalent to the previous example.

From here you can modify the ResultStatus to HttpStatusCode mapping

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Ok,HttpStatusCode.OK, resultStatusOptions =>resultStatusOptions.For("POST",HttpStatusCode.Created).For("DELETE",HttpStatusCode.NoContent)).For(ResultStatus.Error,HttpStatusCode.InternalServerError)));

ResultConvention will add [ProducesResponseType] for every result status configured in ResultStatusMap. AddDefaultMap() maps every known ResultType, so if you want to exclude certain ResultType from being listed (e.g. your app doesn't have authentication and authorization, and you don't want 401 and 403 to be listed as SupportedResponseType) you can do this:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Ok,HttpStatusCode.OK, resultStatusOptions =>resultStatusOptions.For("POST",HttpStatusCode.Created).For("DELETE",HttpStatusCode.NoContent)).Remove(ResultStatus.Forbidden).Remove(ResultStatus.Unauthorized)));

Alternatively, you can specify which (failure) result statuses are expected from a certain endpoint:

[TranslateResultToActionResult()][ExpectedFailures(ResultStatus.NotFound,ResultStatus.Invalid)][HttpDelete("Remove/{id}")]publicResultRemovePerson(intid){// Method logic}

!!! If you list a certain Result status in ExpectedFailures, it must be configured in ResultConvention on startup.

Another configurable feature is what part of the Result object is returned in case of specific failure:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Error,HttpStatusCode.BadRequest, resultStatusOptions =>resultStatusOptions.With((ctrlr,result)=>string.Join("\r\n",result.ValidationErrors)))));

Using Results with FluentValidation

We can use Ardalis.Result.FluentValidation on a service with FluentValidation like that:

publicasyncTask<Result<BlogCategory>>UpdateAsync(BlogCategoryblogCategory){if(Guid.Empty==blogCategory.BlogCategoryId)returnResult<BlogCategory>.NotFound();varvalidator=newBlogCategoryValidator();varvalidation=awaitvalidator.ValidateAsync(blogCategory);if(!validation.IsValid){returnResult<BlogCategory>.Invalid(validation.AsErrors());}varitemToUpdate=(awaitGetByIdAsync(blogCategory.BlogCategoryId)).Value;if(itemToUpdate==null){returnResult<BlogCategory>.NotFound();}itemToUpdate.Update(blogCategory.Name,blogCategory.ParentId);returnResult<BlogCategory>.Success(await_blogCategoryRepository.UpdateAsync(itemToUpdate));}

Getting Started

If you're building an ASP.NET Core Web API you can simply install the Ardalis.Result.AspNetCore package to get started. Then, apply the [TranslateResultToActionResult] attribute to any actions or controllers that you want to automatically translate from Result types to ActionResult types.

Result

A result abstraction that can be mapped to HTTP response codes if needed.

Docs

Docs are located in the /docs folder and available online at result.ardalis.com Please add issues for new docs requests and pull requests for docs issues are welcome!

Learn More

What Problem Does This Address?

Many methods on service need to return some kind of value. For instance, they may be looking up some data and returning a set of results or a single object. They might be creating something, persisting it, and then returning it. Typically, such methods are implemented like this:

publicCustomerGetCustomer(intcustomerId){// more logicreturncustomer;}publicCustomerCreateCustomer(stringfirstName,stringlastName){// more logicreturncustomer;}

This works great as long as we're only concerned with the happy path. But what happens if there are multiple failure modes, not all of which make sense to be handled by exceptions?

What happens if customerId is not found?
What happens if required lastName is not provided?
What happens if the current user doesn't have permission to create new customers?

The standard way to address these concerns is with exceptions. Maybe you throw a different exception for each different failure mode, and the calling code is then required to have multiple catch blocks designed for each type of failure. This makes life painful for the consumer, and results in a lot of exceptions for things that aren't necessarily exceptional. Like this:

[HttpGet]publicasyncTask<ActionResult<CustomerDTO>>GetCustomer(intcustomerId){try{varcustomer=_repository.GetById(customerId);varcustomerDTO=CustomerDTO.MapFrom(customer);returnOk(customerDTO);}catch(NullReferenceExceptionex){returnNotFound();}catch(Exceptionex){returnnewStatusCodeResult(StatusCodes.Status500InternalServerError);}}

Another approach is to return a Tuple of the expected result along with other things, like a status code and additional failure mode metadata. While tuples can be great for individual, flexible responses, they're not as good for having a single, standard, reusable approach to a problem.

The Result pattern provides a standard, reusable way to return both success as well as multiple kinds of non-success responses from .NET services in a way that can easily be mapped to API response types. Although the Ardalis.Result package has no dependencies on ASP.NET Core and can be used from any .NET Core application, the Ardalis.Result.AspNetCore companion package includes resources to enhance the use of this pattern within ASP.NET Core web API applications.

Sample Usage

Creating a Result

The sample folder includes some examples of how to use the project. Here are a couple of simple uses.

Imagine the snippet below is defined in a domain service that retrieves WeatherForecasts. When compared to the approach described above, this approach uses a result to handle common failure scenarios like missing data denoted as NotFound and or input validation errors denoted as Invalid. If execution is successful, the result will contain the random data generated by the final return statement.

publicResult<IEnumerable<WeatherForecast>>GetForecast(ForecastRequestDtomodel){if(model.PostalCode=="NotFound")returnResult<IEnumerable<WeatherForecast>>.NotFound();// validate modelif(model.PostalCode.Length>10){returnResult<IEnumerable<WeatherForecast>>.Invalid(newList<ValidationError>{newValidationError{Identifier=nameof(model.PostalCode),ErrorMessage="PostalCode cannot exceed 10 characters."}});}varrng=newRandom();returnnewResult<IEnumerable<WeatherForecast>>(Enumerable.Range(1,5).Select(index =>newWeatherForecast{Date=DateTime.Now.AddDays(index),TemperatureC=rng.Next(-20,55),Summary=Summaries[rng.Next(Summaries.Length)]}).ToArray());}

Translating Results to ActionResults

Continuing with the domain service example from the previous section, it's important to show that the domain service doesn't know about ActionResult or other MVC/etc types. But since it is using a Result<T> abstraction, it can return results that are easily mapped to HTTP status codes. Note that the method above returns a Result<IEnumerable<WeatherForecast> but in some cases, it might need to return an Invalid result, or a NotFound result. Otherwise, it returns a Success result with the actual returned value (just like an API would return an HTTP 200 and the actual result of the API call).

You can apply the [TranslateResultToActionResult] attribute to an API Endpoint (or controller action if you still use those things) and it will automatically translate the Result<T> return type of the method to an ActionResult<T> appropriately based on the Result type.

[TranslateResultToActionResult][HttpPost("Create")]publicResult<IEnumerable<WeatherForecast>>CreateForecast([FromBody]ForecastRequestDtomodel){return_weatherService.GetForecast(model);}

Alternatively, you can use the ToActionResult helper method within an endpoint to achieve the same thing:

[HttpPost("/Forecast/New")]publicoverrideActionResult<IEnumerable<WeatherForecast>>Handle(ForecastRequestDtorequest){returnthis.ToActionResult(_weatherService.GetForecast(request));// alternately// return _weatherService.GetForecast(request).ToActionResult(this);}

Translating Results to Minimal API Results

Similar to how the ToActionResult extension method translates Ardalis.Results to ActionResults, the ToMinimalApiResult translates results to the new Microsoft.AspNetCore.Http.ResultsIResult types in .NET 6+. The following code snippet demonstrates how one might use the domain service that returns a Result<IEnumerable<WeatherForecast>> and convert to a Microsoft.AspNetCore.Http.Results instance.

app.MapPost("/Forecast/New",(ForecastRequestDtorequest,WeatherServiceweatherService)=>{returnweatherService.GetForecast(request).ToMinimalApiResult();}).WithName("NewWeatherForecast");

The full Minimal API sample can be found in the sample folder.

Mapping Results From One Type to Another

A common use case is to map between domain entities to API response types usually represented as DTOs. You can map a result containing a domain entity to a Result containing a DTO by using the Map method. The following example calls the method _weatherService.GetSingleForecast which returns a Result<WeatherForecast> which is then converted to a Result<WeatherForecastSummaryDto> by the call to Map. Then, the result is converted to an ActionResult<WeatherForecastSummaryDto> using the ToActionResult helper method.

[HttpPost("Summary")]publicActionResult<WeatherForecastSummaryDto>CreateSummaryForecast([FromBody]ForecastRequestDtomodel){return_weatherService.GetSingleForecast(model).Map(wf =>newWeatherForecastSummaryDto(wf.Date,wf.Summary)).ToActionResult(this);}

Chaining Result Operations with Bind and BindAsync

You can chain together multiple operations that return Result<T> using the Bind and BindAsync methods. This allows you to perform a sequence of operations where each operation can fail, and if any operation fails, the subsequent operations will not be executed. This can be useful for eliminating checking for success after each Result operation with a more readable and maintainable chain of operations.

[HttpPost("Summary")]publicasyncTask<ActionResult<WeatherForecastSummaryDto>>CreateSummaryForecast([FromBody]ForecastRequestDtomodel){varresult1=await_weatherService.GetSingleForecast(model);if(!result1.IsSuccess){returnresult1.ToActionResult(this);}varresult2=await_weatherService.GetForecastDetailsAsync(result1.Value.Id);returnresult2.Map(details =>newWeatherForecastSummaryDto(details.Date,details.Summary)).ToActionResult(this);}

With the Bind and BindAsync methods, you can simplify this code by chaining the operations together. The following example demonstrates how to use BindAsync to achieve the same result in a more concise manner:

[HttpPost("BindedForecast")]publicasyncTask<ActionResult<WeatherForecastSummaryDto>>CreateSummaryForecastWithBind([FromBody]ForecastRequestDtomodel){returnawait_weatherService.GetSingleForecast(model).BindAsync(wf =>_weatherService.GetForecastDetailsAsync(wf.Id)).Map(details =>newWeatherForecastSummaryDto(details.Date,details.Summary)).ToActionResult(this);}

In this example, if GetSingleForecast returns a failure result, GetForecastDetailsAsync will not be called, and the failure will propagate through the chain. If all operations succeed, the final result will be mapped to a WeatherForecastSummaryDto and returned as an ActionResult.

ASP.NET API Metadata

By default, Asp Net Core and API Explorer know nothing about [TranslateResultToActionResult] and what it is doing. To reflect [TranslateResultToActionResult] behavior in metadata generated by API Explorer (which is then used by tools like Swashbuckle, NSwag etc.), you can use ResultConvention:

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

This will add [ProducesResponseType] for every known ResultStatus to every endpoint marked with [TranslateResultToActionResult]. To customize ResultConvention behavior, one may use the AddResultConvention method:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap()));

This code is functionally equivalent to the previous example.

From here you can modify the ResultStatus to HttpStatusCode mapping

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Ok,HttpStatusCode.OK, resultStatusOptions =>resultStatusOptions.For("POST",HttpStatusCode.Created).For("DELETE",HttpStatusCode.NoContent)).For(ResultStatus.Error,HttpStatusCode.InternalServerError)));

ResultConvention will add [ProducesResponseType] for every result status configured in ResultStatusMap. AddDefaultMap() maps every known ResultType, so if you want to exclude certain ResultType from being listed (e.g. your app doesn't have authentication and authorization, and you don't want 401 and 403 to be listed as SupportedResponseType) you can do this:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Ok,HttpStatusCode.OK, resultStatusOptions =>resultStatusOptions.For("POST",HttpStatusCode.Created).For("DELETE",HttpStatusCode.NoContent)).Remove(ResultStatus.Forbidden).Remove(ResultStatus.Unauthorized)));

Alternatively, you can specify which (failure) result statuses are expected from a certain endpoint:

[TranslateResultToActionResult()][ExpectedFailures(ResultStatus.NotFound,ResultStatus.Invalid)][HttpDelete("Remove/{id}")]publicResultRemovePerson(intid){// Method logic}

!!! If you list a certain Result status in ExpectedFailures, it must be configured in ResultConvention on startup.

Another configurable feature is what part of the Result object is returned in case of specific failure:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Error,HttpStatusCode.BadRequest, resultStatusOptions =>resultStatusOptions.With((ctrlr,result)=>string.Join("\r\n",result.ValidationErrors)))));

Using Results with FluentValidation

We can use Ardalis.Result.FluentValidation on a service with FluentValidation like that:

publicasyncTask<Result<BlogCategory>>UpdateAsync(BlogCategoryblogCategory){if(Guid.Empty==blogCategory.BlogCategoryId)returnResult<BlogCategory>.NotFound();varvalidator=newBlogCategoryValidator();varvalidation=awaitvalidator.ValidateAsync(blogCategory);if(!validation.IsValid){returnResult<BlogCategory>.Invalid(validation.AsErrors());}varitemToUpdate=(awaitGetByIdAsync(blogCategory.BlogCategoryId)).Value;if(itemToUpdate==null){returnResult<BlogCategory>.NotFound();}itemToUpdate.Update(blogCategory.Name,blogCategory.ParentId);returnResult<BlogCategory>.Success(await_blogCategoryRepository.UpdateAsync(itemToUpdate));}

Getting Started

If you're building an ASP.NET Core Web API you can simply install the Ardalis.Result.AspNetCore package to get started. Then, apply the [TranslateResultToActionResult] attribute to any actions or controllers that you want to automatically translate from Result types to ActionResult types.

Result

A result abstraction that can be mapped to HTTP response codes if needed.

Docs

Docs are located in the /docs folder and available online at result.ardalis.com Please add issues for new docs requests and pull requests for docs issues are welcome!

Learn More

What Problem Does This Address?

Many methods on service need to return some kind of value. For instance, they may be looking up some data and returning a set of results or a single object. They might be creating something, persisting it, and then returning it. Typically, such methods are implemented like this:

publicCustomerGetCustomer(intcustomerId){// more logicreturncustomer;}publicCustomerCreateCustomer(stringfirstName,stringlastName){// more logicreturncustomer;}

This works great as long as we're only concerned with the happy path. But what happens if there are multiple failure modes, not all of which make sense to be handled by exceptions?

What happens if customerId is not found?
What happens if required lastName is not provided?
What happens if the current user doesn't have permission to create new customers?

The standard way to address these concerns is with exceptions. Maybe you throw a different exception for each different failure mode, and the calling code is then required to have multiple catch blocks designed for each type of failure. This makes life painful for the consumer, and results in a lot of exceptions for things that aren't necessarily exceptional. Like this:

[HttpGet]publicasyncTask<ActionResult<CustomerDTO>>GetCustomer(intcustomerId){try{varcustomer=_repository.GetById(customerId);varcustomerDTO=CustomerDTO.MapFrom(customer);returnOk(customerDTO);}catch(NullReferenceExceptionex){returnNotFound();}catch(Exceptionex){returnnewStatusCodeResult(StatusCodes.Status500InternalServerError);}}

Another approach is to return a Tuple of the expected result along with other things, like a status code and additional failure mode metadata. While tuples can be great for individual, flexible responses, they're not as good for having a single, standard, reusable approach to a problem.

The Result pattern provides a standard, reusable way to return both success as well as multiple kinds of non-success responses from .NET services in a way that can easily be mapped to API response types. Although the Ardalis.Result package has no dependencies on ASP.NET Core and can be used from any .NET Core application, the Ardalis.Result.AspNetCore companion package includes resources to enhance the use of this pattern within ASP.NET Core web API applications.

Sample Usage

Creating a Result

The sample folder includes some examples of how to use the project. Here are a couple of simple uses.

Imagine the snippet below is defined in a domain service that retrieves WeatherForecasts. When compared to the approach described above, this approach uses a result to handle common failure scenarios like missing data denoted as NotFound and or input validation errors denoted as Invalid. If execution is successful, the result will contain the random data generated by the final return statement.

publicResult<IEnumerable<WeatherForecast>>GetForecast(ForecastRequestDtomodel){if(model.PostalCode=="NotFound")returnResult<IEnumerable<WeatherForecast>>.NotFound();// validate modelif(model.PostalCode.Length>10){returnResult<IEnumerable<WeatherForecast>>.Invalid(newList<ValidationError>{newValidationError{Identifier=nameof(model.PostalCode),ErrorMessage="PostalCode cannot exceed 10 characters."}});}varrng=newRandom();returnnewResult<IEnumerable<WeatherForecast>>(Enumerable.Range(1,5).Select(index =>newWeatherForecast{Date=DateTime.Now.AddDays(index),TemperatureC=rng.Next(-20,55),Summary=Summaries[rng.Next(Summaries.Length)]}).ToArray());}

Translating Results to ActionResults

Continuing with the domain service example from the previous section, it's important to show that the domain service doesn't know about ActionResult or other MVC/etc types. But since it is using a Result<T> abstraction, it can return results that are easily mapped to HTTP status codes. Note that the method above returns a Result<IEnumerable<WeatherForecast> but in some cases, it might need to return an Invalid result, or a NotFound result. Otherwise, it returns a Success result with the actual returned value (just like an API would return an HTTP 200 and the actual result of the API call).

You can apply the [TranslateResultToActionResult] attribute to an API Endpoint (or controller action if you still use those things) and it will automatically translate the Result<T> return type of the method to an ActionResult<T> appropriately based on the Result type.

[TranslateResultToActionResult][HttpPost("Create")]publicResult<IEnumerable<WeatherForecast>>CreateForecast([FromBody]ForecastRequestDtomodel){return_weatherService.GetForecast(model);}

Alternatively, you can use the ToActionResult helper method within an endpoint to achieve the same thing:

[HttpPost("/Forecast/New")]publicoverrideActionResult<IEnumerable<WeatherForecast>>Handle(ForecastRequestDtorequest){returnthis.ToActionResult(_weatherService.GetForecast(request));// alternately// return _weatherService.GetForecast(request).ToActionResult(this);}

Translating Results to Minimal API Results

Similar to how the ToActionResult extension method translates Ardalis.Results to ActionResults, the ToMinimalApiResult translates results to the new Microsoft.AspNetCore.Http.ResultsIResult types in .NET 6+. The following code snippet demonstrates how one might use the domain service that returns a Result<IEnumerable<WeatherForecast>> and convert to a Microsoft.AspNetCore.Http.Results instance.

app.MapPost("/Forecast/New",(ForecastRequestDtorequest,WeatherServiceweatherService)=>{returnweatherService.GetForecast(request).ToMinimalApiResult();}).WithName("NewWeatherForecast");

The full Minimal API sample can be found in the sample folder.

Mapping Results From One Type to Another

A common use case is to map between domain entities to API response types usually represented as DTOs. You can map a result containing a domain entity to a Result containing a DTO by using the Map method. The following example calls the method _weatherService.GetSingleForecast which returns a Result<WeatherForecast> which is then converted to a Result<WeatherForecastSummaryDto> by the call to Map. Then, the result is converted to an ActionResult<WeatherForecastSummaryDto> using the ToActionResult helper method.

[HttpPost("Summary")]publicActionResult<WeatherForecastSummaryDto>CreateSummaryForecast([FromBody]ForecastRequestDtomodel){return_weatherService.GetSingleForecast(model).Map(wf =>newWeatherForecastSummaryDto(wf.Date,wf.Summary)).ToActionResult(this);}

Chaining Result Operations with Bind and BindAsync

You can chain together multiple operations that return Result<T> using the Bind and BindAsync methods. This allows you to perform a sequence of operations where each operation can fail, and if any operation fails, the subsequent operations will not be executed. This can be useful for eliminating checking for success after each Result operation with a more readable and maintainable chain of operations.

[HttpPost("Summary")]publicasyncTask<ActionResult<WeatherForecastSummaryDto>>CreateSummaryForecast([FromBody]ForecastRequestDtomodel){varresult1=await_weatherService.GetSingleForecast(model);if(!result1.IsSuccess){returnresult1.ToActionResult(this);}varresult2=await_weatherService.GetForecastDetailsAsync(result1.Value.Id);returnresult2.Map(details =>newWeatherForecastSummaryDto(details.Date,details.Summary)).ToActionResult(this);}

With the Bind and BindAsync methods, you can simplify this code by chaining the operations together. The following example demonstrates how to use BindAsync to achieve the same result in a more concise manner:

[HttpPost("BindedForecast")]publicasyncTask<ActionResult<WeatherForecastSummaryDto>>CreateSummaryForecastWithBind([FromBody]ForecastRequestDtomodel){returnawait_weatherService.GetSingleForecast(model).BindAsync(wf =>_weatherService.GetForecastDetailsAsync(wf.Id)).Map(details =>newWeatherForecastSummaryDto(details.Date,details.Summary)).ToActionResult(this);}

In this example, if GetSingleForecast returns a failure result, GetForecastDetailsAsync will not be called, and the failure will propagate through the chain. If all operations succeed, the final result will be mapped to a WeatherForecastSummaryDto and returned as an ActionResult.

ASP.NET API Metadata

By default, Asp Net Core and API Explorer know nothing about [TranslateResultToActionResult] and what it is doing. To reflect [TranslateResultToActionResult] behavior in metadata generated by API Explorer (which is then used by tools like Swashbuckle, NSwag etc.), you can use ResultConvention:

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

This will add [ProducesResponseType] for every known ResultStatus to every endpoint marked with [TranslateResultToActionResult]. To customize ResultConvention behavior, one may use the AddResultConvention method:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap()));

This code is functionally equivalent to the previous example.

From here you can modify the ResultStatus to HttpStatusCode mapping

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Ok,HttpStatusCode.OK, resultStatusOptions =>resultStatusOptions.For("POST",HttpStatusCode.Created).For("DELETE",HttpStatusCode.NoContent)).For(ResultStatus.Error,HttpStatusCode.InternalServerError)));

ResultConvention will add [ProducesResponseType] for every result status configured in ResultStatusMap. AddDefaultMap() maps every known ResultType, so if you want to exclude certain ResultType from being listed (e.g. your app doesn't have authentication and authorization, and you don't want 401 and 403 to be listed as SupportedResponseType) you can do this:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Ok,HttpStatusCode.OK, resultStatusOptions =>resultStatusOptions.For("POST",HttpStatusCode.Created).For("DELETE",HttpStatusCode.NoContent)).Remove(ResultStatus.Forbidden).Remove(ResultStatus.Unauthorized)));

Alternatively, you can specify which (failure) result statuses are expected from a certain endpoint:

[TranslateResultToActionResult()][ExpectedFailures(ResultStatus.NotFound,ResultStatus.Invalid)][HttpDelete("Remove/{id}")]publicResultRemovePerson(intid){// Method logic}

!!! If you list a certain Result status in ExpectedFailures, it must be configured in ResultConvention on startup.

Another configurable feature is what part of the Result object is returned in case of specific failure:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Error,HttpStatusCode.BadRequest, resultStatusOptions =>resultStatusOptions.With((ctrlr,result)=>string.Join("\r\n",result.ValidationErrors)))));

Using Results with FluentValidation

We can use Ardalis.Result.FluentValidation on a service with FluentValidation like that:

publicasyncTask<Result<BlogCategory>>UpdateAsync(BlogCategoryblogCategory){if(Guid.Empty==blogCategory.BlogCategoryId)returnResult<BlogCategory>.NotFound();varvalidator=newBlogCategoryValidator();varvalidation=awaitvalidator.ValidateAsync(blogCategory);if(!validation.IsValid){returnResult<BlogCategory>.Invalid(validation.AsErrors());}varitemToUpdate=(awaitGetByIdAsync(blogCategory.BlogCategoryId)).Value;if(itemToUpdate==null){returnResult<BlogCategory>.NotFound();}itemToUpdate.Update(blogCategory.Name,blogCategory.ParentId);returnResult<BlogCategory>.Success(await_blogCategoryRepository.UpdateAsync(itemToUpdate));}

Getting Started

If you're building an ASP.NET Core Web API you can simply install the Ardalis.Result.AspNetCore package to get started. Then, apply the [TranslateResultToActionResult] attribute to any actions or controllers that you want to automatically translate from Result types to ActionResult types.

Result

A result abstraction that can be mapped to HTTP response codes if needed.

Docs

Docs are located in the /docs folder and available online at result.ardalis.com Please add issues for new docs requests and pull requests for docs issues are welcome!

Learn More

What Problem Does This Address?

Many methods on service need to return some kind of value. For instance, they may be looking up some data and returning a set of results or a single object. They might be creating something, persisting it, and then returning it. Typically, such methods are implemented like this:

publicCustomerGetCustomer(intcustomerId){// more logicreturncustomer;}publicCustomerCreateCustomer(stringfirstName,stringlastName){// more logicreturncustomer;}

This works great as long as we're only concerned with the happy path. But what happens if there are multiple failure modes, not all of which make sense to be handled by exceptions?

What happens if customerId is not found?
What happens if required lastName is not provided?
What happens if the current user doesn't have permission to create new customers?

The standard way to address these concerns is with exceptions. Maybe you throw a different exception for each different failure mode, and the calling code is then required to have multiple catch blocks designed for each type of failure. This makes life painful for the consumer, and results in a lot of exceptions for things that aren't necessarily exceptional. Like this:

[HttpGet]publicasyncTask<ActionResult<CustomerDTO>>GetCustomer(intcustomerId){try{varcustomer=_repository.GetById(customerId);varcustomerDTO=CustomerDTO.MapFrom(customer);returnOk(customerDTO);}catch(NullReferenceExceptionex){returnNotFound();}catch(Exceptionex){returnnewStatusCodeResult(StatusCodes.Status500InternalServerError);}}

Another approach is to return a Tuple of the expected result along with other things, like a status code and additional failure mode metadata. While tuples can be great for individual, flexible responses, they're not as good for having a single, standard, reusable approach to a problem.

The Result pattern provides a standard, reusable way to return both success as well as multiple kinds of non-success responses from .NET services in a way that can easily be mapped to API response types. Although the Ardalis.Result package has no dependencies on ASP.NET Core and can be used from any .NET Core application, the Ardalis.Result.AspNetCore companion package includes resources to enhance the use of this pattern within ASP.NET Core web API applications.

Sample Usage

Creating a Result

The sample folder includes some examples of how to use the project. Here are a couple of simple uses.

Imagine the snippet below is defined in a domain service that retrieves WeatherForecasts. When compared to the approach described above, this approach uses a result to handle common failure scenarios like missing data denoted as NotFound and or input validation errors denoted as Invalid. If execution is successful, the result will contain the random data generated by the final return statement.

publicResult<IEnumerable<WeatherForecast>>GetForecast(ForecastRequestDtomodel){if(model.PostalCode=="NotFound")returnResult<IEnumerable<WeatherForecast>>.NotFound();// validate modelif(model.PostalCode.Length>10){returnResult<IEnumerable<WeatherForecast>>.Invalid(newList<ValidationError>{newValidationError{Identifier=nameof(model.PostalCode),ErrorMessage="PostalCode cannot exceed 10 characters."}});}varrng=newRandom();returnnewResult<IEnumerable<WeatherForecast>>(Enumerable.Range(1,5).Select(index =>newWeatherForecast{Date=DateTime.Now.AddDays(index),TemperatureC=rng.Next(-20,55),Summary=Summaries[rng.Next(Summaries.Length)]}).ToArray());}

Translating Results to ActionResults

Continuing with the domain service example from the previous section, it's important to show that the domain service doesn't know about ActionResult or other MVC/etc types. But since it is using a Result<T> abstraction, it can return results that are easily mapped to HTTP status codes. Note that the method above returns a Result<IEnumerable<WeatherForecast> but in some cases, it might need to return an Invalid result, or a NotFound result. Otherwise, it returns a Success result with the actual returned value (just like an API would return an HTTP 200 and the actual result of the API call).

You can apply the [TranslateResultToActionResult] attribute to an API Endpoint (or controller action if you still use those things) and it will automatically translate the Result<T> return type of the method to an ActionResult<T> appropriately based on the Result type.

[TranslateResultToActionResult][HttpPost("Create")]publicResult<IEnumerable<WeatherForecast>>CreateForecast([FromBody]ForecastRequestDtomodel){return_weatherService.GetForecast(model);}

Alternatively, you can use the ToActionResult helper method within an endpoint to achieve the same thing:

[HttpPost("/Forecast/New")]publicoverrideActionResult<IEnumerable<WeatherForecast>>Handle(ForecastRequestDtorequest){returnthis.ToActionResult(_weatherService.GetForecast(request));// alternately// return _weatherService.GetForecast(request).ToActionResult(this);}

Translating Results to Minimal API Results

Similar to how the ToActionResult extension method translates Ardalis.Results to ActionResults, the ToMinimalApiResult translates results to the new Microsoft.AspNetCore.Http.ResultsIResult types in .NET 6+. The following code snippet demonstrates how one might use the domain service that returns a Result<IEnumerable<WeatherForecast>> and convert to a Microsoft.AspNetCore.Http.Results instance.

app.MapPost("/Forecast/New",(ForecastRequestDtorequest,WeatherServiceweatherService)=>{returnweatherService.GetForecast(request).ToMinimalApiResult();}).WithName("NewWeatherForecast");

The full Minimal API sample can be found in the sample folder.

Mapping Results From One Type to Another

A common use case is to map between domain entities to API response types usually represented as DTOs. You can map a result containing a domain entity to a Result containing a DTO by using the Map method. The following example calls the method _weatherService.GetSingleForecast which returns a Result<WeatherForecast> which is then converted to a Result<WeatherForecastSummaryDto> by the call to Map. Then, the result is converted to an ActionResult<WeatherForecastSummaryDto> using the ToActionResult helper method.

[HttpPost("Summary")]publicActionResult<WeatherForecastSummaryDto>CreateSummaryForecast([FromBody]ForecastRequestDtomodel){return_weatherService.GetSingleForecast(model).Map(wf =>newWeatherForecastSummaryDto(wf.Date,wf.Summary)).ToActionResult(this);}

Chaining Result Operations with Bind and BindAsync

You can chain together multiple operations that return Result<T> using the Bind and BindAsync methods. This allows you to perform a sequence of operations where each operation can fail, and if any operation fails, the subsequent operations will not be executed. This can be useful for eliminating checking for success after each Result operation with a more readable and maintainable chain of operations.

[HttpPost("Summary")]publicasyncTask<ActionResult<WeatherForecastSummaryDto>>CreateSummaryForecast([FromBody]ForecastRequestDtomodel){varresult1=await_weatherService.GetSingleForecast(model);if(!result1.IsSuccess){returnresult1.ToActionResult(this);}varresult2=await_weatherService.GetForecastDetailsAsync(result1.Value.Id);returnresult2.Map(details =>newWeatherForecastSummaryDto(details.Date,details.Summary)).ToActionResult(this);}

With the Bind and BindAsync methods, you can simplify this code by chaining the operations together. The following example demonstrates how to use BindAsync to achieve the same result in a more concise manner:

[HttpPost("BindedForecast")]publicasyncTask<ActionResult<WeatherForecastSummaryDto>>CreateSummaryForecastWithBind([FromBody]ForecastRequestDtomodel){returnawait_weatherService.GetSingleForecast(model).BindAsync(wf =>_weatherService.GetForecastDetailsAsync(wf.Id)).Map(details =>newWeatherForecastSummaryDto(details.Date,details.Summary)).ToActionResult(this);}

In this example, if GetSingleForecast returns a failure result, GetForecastDetailsAsync will not be called, and the failure will propagate through the chain. If all operations succeed, the final result will be mapped to a WeatherForecastSummaryDto and returned as an ActionResult.

ASP.NET API Metadata

By default, Asp Net Core and API Explorer know nothing about [TranslateResultToActionResult] and what it is doing. To reflect [TranslateResultToActionResult] behavior in metadata generated by API Explorer (which is then used by tools like Swashbuckle, NSwag etc.), you can use ResultConvention:

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

This will add [ProducesResponseType] for every known ResultStatus to every endpoint marked with [TranslateResultToActionResult]. To customize ResultConvention behavior, one may use the AddResultConvention method:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap()));

This code is functionally equivalent to the previous example.

From here you can modify the ResultStatus to HttpStatusCode mapping

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Ok,HttpStatusCode.OK, resultStatusOptions =>resultStatusOptions.For("POST",HttpStatusCode.Created).For("DELETE",HttpStatusCode.NoContent)).For(ResultStatus.Error,HttpStatusCode.InternalServerError)));

ResultConvention will add [ProducesResponseType] for every result status configured in ResultStatusMap. AddDefaultMap() maps every known ResultType, so if you want to exclude certain ResultType from being listed (e.g. your app doesn't have authentication and authorization, and you don't want 401 and 403 to be listed as SupportedResponseType) you can do this:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Ok,HttpStatusCode.OK, resultStatusOptions =>resultStatusOptions.For("POST",HttpStatusCode.Created).For("DELETE",HttpStatusCode.NoContent)).Remove(ResultStatus.Forbidden).Remove(ResultStatus.Unauthorized)));

Alternatively, you can specify which (failure) result statuses are expected from a certain endpoint:

[TranslateResultToActionResult()][ExpectedFailures(ResultStatus.NotFound,ResultStatus.Invalid)][HttpDelete("Remove/{id}")]publicResultRemovePerson(intid){// Method logic}

!!! If you list a certain Result status in ExpectedFailures, it must be configured in ResultConvention on startup.

Another configurable feature is what part of the Result object is returned in case of specific failure:

services.AddControllers(mvcOptions =>mvcOptions.AddResultConvention(resultStatusMap =>resultStatusMap.AddDefaultMap().For(ResultStatus.Error,HttpStatusCode.BadRequest, resultStatusOptions =>resultStatusOptions.With((ctrlr,result)=>string.Join("\r\n",result.ValidationErrors)))));

Using Results with FluentValidation

We can use Ardalis.Result.FluentValidation on a service with FluentValidation like that:

publicasyncTask<Result<BlogCategory>>UpdateAsync(BlogCategoryblogCategory){if(Guid.Empty==blogCategory.BlogCategoryId)returnResult<BlogCategory>.NotFound();varvalidator=newBlogCategoryValidator();varvalidation=awaitvalidator.ValidateAsync(blogCategory);if(!validation.IsValid){returnResult<BlogCategory>.Invalid(validation.AsErrors());}varitemToUpdate=(awaitGetByIdAsync(blogCategory.BlogCategoryId)).Value;if(itemToUpdate==null){returnResult<BlogCategory>.NotFound();}itemToUpdate.Update(blogCategory.Name,blogCategory.ParentId);returnResult<BlogCategory>.Success(await_blogCategoryRepository.UpdateAsync(itemToUpdate));}

Getting Started

If you're building an ASP.NET Core Web API you can simply install the Ardalis.Result.AspNetCore package to get started. Then, apply the [TranslateResultToActionResult] attribute to any actions or controllers that you want to automatically translate from Result types to ActionResult types.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
sample		sample
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
Ardalis.Result.sln		Ardalis.Result.sln
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Directory.Packages.props		Directory.Packages.props
LICENSE		LICENSE
README.md		README.md

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
sample		sample
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
Ardalis.Result.sln		Ardalis.Result.sln
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Directory.Packages.props		Directory.Packages.props
LICENSE		LICENSE
README.md		README.md

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
sample		sample
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
Ardalis.Result.sln		Ardalis.Result.sln
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Directory.Packages.props		Directory.Packages.props
LICENSE		LICENSE
README.md		README.md

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
sample		sample
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
Ardalis.Result.sln		Ardalis.Result.sln
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Directory.Packages.props		Directory.Packages.props
LICENSE		LICENSE
README.md		README.md

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
sample		sample
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
Ardalis.Result.sln		Ardalis.Result.sln
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Directory.Packages.props		Directory.Packages.props
LICENSE		LICENSE
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

Result

Docs

Learn More

What Problem Does This Address?

Sample Usage

Creating a Result

Translating Results to ActionResults

Translating Results to Minimal API Results

Mapping Results From One Type to Another

Chaining Result Operations with Bind and BindAsync

ASP.NET API Metadata

Using Results with FluentValidation

Getting Started

About

Topics

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Result

Docs

Learn More

What Problem Does This Address?

Sample Usage

Creating a Result

Translating Results to ActionResults

Translating Results to Minimal API Results

Mapping Results From One Type to Another

Chaining Result Operations with Bind and BindAsync

ASP.NET API Metadata

Using Results with FluentValidation

Getting Started

About

Topics

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Result

Docs

Learn More

What Problem Does This Address?

Sample Usage

Creating a Result

Translating Results to ActionResults

Translating Results to Minimal API Results

Mapping Results From One Type to Another

Chaining Result Operations with Bind and BindAsync

ASP.NET API Metadata

Using Results with FluentValidation

Getting Started

About

Topics

Resources