Converts a IDomainResult-based object (returned from the Domain Layer) to various ActionResult-based types providing 20+ static extension methods.
To be used in Web API projects to accompany 'DomainResult.Common' package used in the Domain Layer.
NuGet for decoupling domain operation results from ActionResult-based types of ASP.NET Web API
Two tiny NuGet packages addressing challenges in the ASP.NET Web API realm posed by separation of the Domain Layer (aka Business Layer) from the Application Layer:
eliminating dependency on Microsoft.AspNetCore.Mvc (and IActionResult in particular) in the Domain Layer (usually a separate project);
mapping various of responses from the Domain Layer to appropriate -related type.
public async Task<(InvoiceResponseDto, IDomainResult)> GetInvoice(int invoiceId)
{
if (invoiceId < 0)
// Returns a validation error
return IDomainResult.Failed<InvoiceResponseDto>("Try harder");
var invoice = await DataContext.Invoices.FindAsync(invoiceId);
if (invoice == null)
// Returns a Not Found response
return IDomainResult.NotFound<InvoiceResponseDto>();
// Returns the invoice
return IDomainResult.Success(invoice);
}
or if you're against ValueTuple or static methods on interfaces (added in C# 8), then a more traditional method signature:
public async Task<IDomainResult<InvoiceResponseDto>> GetInvoice(int invoiceId)
{
if (invoiceId < 0)
// Returns a validation error
return DomainResult.Failed<InvoiceResponseDto>("Try harder");
var invoice = await DataContext.Invoices.FindAsync(invoiceId);
if (invoice == null)
// Returns a Not Found response
return DomainResult.NotFound<InvoiceResponseDto>();
// Returns the invoice
return DomainResult.Success(invoice);
}
HTTP code 400 Bad Request with a message "Try harder" when the invoice ID < 1 (the HTTP code can be configured to 422 Unprocessable Entity).
HTTP code 404 Not Found for incorrect invoice IDs.
Quick start
Install DomainResult NuGet package for the Web API project.
Install DomainResult.Common NuGet package for the Domain Layer (aka Business Layer) projects. If the Domain Layer is inside the Web API project, then skip this step.
Follow the documentation below, samples in the repo and common sense.
The library targets .NET Core 3.1, .NET 5.0 and .NET 6.0.
'DomainResult.Common' package. Returning result from Domain Layer method
A tiny package with no dependency on Microsoft.AspNetCore.* namespaces that provides:
data types for returning from domain operations (wraps up the returned value and adds operation status with error messages if applicable);
extension methods to effortlessly form the desired response.
It's built around IDomainResult interface that has 3 properties:
IReadOnlyCollection<string> Errors { get; } // Collection of error messages if any
bool IsSuccess { get; } // Flag, whether the current status is successful or not
DomainOperationStatus Status { get; } // Current status of the domain operation: Success, Failed, NotFound, Unauthorized, etc.
And IDomainResult<T> interface that also adds
// Value returned by the domain operation
T Value { get; }
It has 50+ static extension methods to return a successful or unsuccessful result from the domain method with one of the following types:
Returned type
Returned type wrapped in Task
IDomainResult
Task<IDomainResult>
IDomainResult<T>
Task<IDomainResult<T>>
(T, IDomainResult)
Task<(T, IDomainResult)>
Examples:
// Successful result with no value
IDomainResult res = IDomainResult.Success(); // res.Status is 'Success'
// Successful result with an int
(value, state) = IDomainResult.Success(10); // value = 10; state.Status is 'Success'
// The same but wrapped in a task
var res = IDomainResult.SuccessTask(10); // res is Task<(int, IDomainResult)>
// Implicit convertion
IDomainResult<int> res = 10; // res.Value = 10; res.Status is 'Success'
// Error message
IDomainResult res = IDomainResult.Failed("Ahh!"); // res.Status is 'Failed' and res.Errors = new []{ "Ahh!" }
// Error when expected an int
(value, state) = IDomainResult.Failed<int>("Ahh!"); // value = 0, state.Status is 'Failed' and state.Errors = new []{ "Ahh!" }
// 'Not Found' acts like the errors
(value, state) = IDomainResult.NotFound<int>(); // value = 0, state.Status is 'NotFound'
Task<(int val, IDomainResult state)> res = IDomainResult.NotFoundTask<int>(); // value = 0, state.Status is 'NotFound'
// 'Unauthorized' response
(value, state) = IDomainResult.Unauthorized<int>(); // value = 0, state.Status is 'Unauthorized'
Notes:
The Task suffix on the extension methods indicates that the returned type is wrapped in a Task (e.g. SuccessTask(), FailedTask(), NotFoundTask(), UnauthorizedTask()).
The Failed() and NotFound() methods take as input parameters: string, string[]. Failed() can also take ValidationResult.
'DomainResult' package. Conversion to ActionResult
Converts a IDomainResult-based object to various ActionResult-based types providing 20+ static extension methods.
Returned type
Returned type wrapped in Task
Extension methods
IActionResult
Task<IActionResult>
ToActionResult() ToCustomActionResult()
ActionResult<T>
Task<ActionResult<T>>
ToActionResultOfT() ToCustomActionResultOfT()
Note: DomainResult package has dependency on Microsoft.AspNetCore.* namespace and DomainResult.Common package.
The mapping rules are built around IDomainResult.Status:
IDomainResult.Status
Returned ActionResult-based type
Success
If no value is returned then 204 NoContent, otherwise - 200 OK Supports custom codes (e.g. 201 Created)
NotFound
HTTP code 404 NotFound (default)
Failed
HTTP code 400 (default) or can be configured to 422 or any other code
Unauthorized
HTTP code 403 Forbidden (default)
Examples:
// Returns `IActionResult` with HTTP code `204 NoContent` on success
IDomainResult.ToActionResult();
// The same as above, but returns `Task<IActionResult>` with no need in 'await'
Task<IDomainResult>.ToActionResult();
// Returns `IActionResult` with HTTP code `200 Ok` along with the value
IDomainResult<T>.ToActionResult();
(T, IDomainResult).ToActionResult();
// As above, but returns `Task<IActionResult>` with no need in 'await'
Task<IDomainResult<T>>.ToActionResult();
Task<(T, IDomainResult)>.ToActionResult();
// Returns `ActionResult<T>` with HTTP code `200 Ok` along with the value
IDomainResult<T>.ToActionResultOfT();
(T, IDomainResult).ToActionResultOfT();
// As above, but returns `Task<ActionResult<T>>` with no need in 'await'
Task<IDomainResult<T>>.ToActionResultOfT();
Task<(T, IDomainResult)>.ToActionResultOfT();
Custom Problem Details output
There is a way to tune the Problem Details output case-by-case.
Custom ActionResult response for 2xx HTTP codes
When returning a standard 200 or 204 HTTP code is not enough, there are extension methods to knock yourself out - ToCustomActionResult() and ToCustomActionResultOfT.
Example of returning 201 Created along with a location header field pointing to the created resource (as per RFC7231):
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
public ActionResult<int> CreateItem(CreateItemDto dto)
{
// Service method for creating an item and returning its ID.
// Can return any of the IDomainResult types (e.g. (int, IDomainResult, IDomainResult<int>, Task<...>, etc).
var result = _service.CreateItem(dto);
// Custom conversion of the successful response only. For others, it returns standard 4xx HTTP codes
return result.ToCustomActionResultOfT(
// On success returns '201 Created' with a link to '/{id}' route in HTTP headers
val => CreatedAtAction(nameof(GetById), new { id = val }, val)
);
}
// Returns an entity by ID
[HttpGet("{id}")]
public IActionResult GetById([FromRoute] int id)
{
...
}
It works with any of extensions in Microsoft.AspNetCore.Mvc.ControllerBase. Here are some:
The default HTTP codes for statuses Failed, NotFound and Unauthorized are defined in public static properties of ActionResultConventions with default values:
// The HTTP code to return for client request error
int ErrorHttpCode { get; set; } = 400;
// The 'title' property of the returned JSON on HTTP code 400
string ErrorProblemDetailsTitle { get; set; } = "Bad Request";
// The HTTP code to return when a record not found
int NotFoundHttpCode { get; set; } = 404;
// The 'title' property of the returned JSON on HTTP code 404
string NotFoundProblemDetailsTitle { get; set; }= "Not Found";
// The HTTP code to return when access to a record is forbidden
int UnauthorizedHttpCode { get; set; } = 403;
// The 'title' property of the returned JSON on HTTP code 403
string UnauthorizedProblemDetailsTitle { get; set; }= "Unauthorized access";
Feel free to change them (hmm... remember they're static, with all the pros and cons). The reasons you may want it:
Localisation of the titles
Favour 422 HTTP code in stead of 400 (see opinions here and here).
The extension methods also support custom response in case of the IDomainResult.Status being Failed, NotFound or Unauthorized:
[HttpGet("[action]")]
[ProducesResponseType(StatusCodes.Status422UnprocessableEntity)]
public Task<ActionResult<int>> GetFailedWithCustomStatusAndMessage()
{
var res = _service.GetFailedWithNoMessage();
return res.ToActionResultOfT(
(problemDetails, state) =>
{
if (state.Errors?.Any() == true)
return;
problemDetails.Status = 422; // Replace the default 400 code
problemDetails.Title = "D'oh!"; // Replace the default 'Bad Request' title
problemDetails.Detail = "I wish devs put more efforts into it..."; // Custom message
});
}
Alternative solutions
The problem solved here is not unique, so how does DomainResult stand out?
Why not FluentResults?
FluentResults is a great tool for indicating success or failure in the returned object. But there are different objectives:
FluentResults provides a generalised container for returning results and potential errors;
DomainResult is focused on a more specialised case when the Domain Logic is consumed by Web API.
Hence, DomainResult provides out-of-the-box:
Specialised extension methods (like IDomainResult.NotFound() that in FluentResult would be indistinctive from other errors)
Supports various ways of conversions to ActionResult (returning Problem Details in case of error), functionality that is not available in FluentResults and quite weak in the other NuGets extending FluentResults.
