Tooark.AspNetCore 4.3.0

Tooark.AspNetCore

Library that concentrates the ASP.NET Core specific pieces of Tooark, keeping the general-purpose packages free of the runtime requirement. Packages whose purpose is to integrate with ASP.NET Core (Tooark.Dtos, Tooark.Observability, Tooark.Securities.OpenId) declare the shared framework themselves.

🌍 Languages: 🇺🇸 English (this file) · 🇧🇷 Português

Contents

• Overview
• Installation
• Components
• Usage Examples
• Dependencies
• Contributing
• License

Overview

The Tooark.AspNetCore package provides:

• extensions for ASP.NET Core types, today the ModelStateDictionary;
• the place where the ASP.NET Core requirement was moved to, taking it out of the general-purpose packages;
• integration with the Tooark.Extensions localizer, translating the validation error keys;
• the intended home for the family's filters and middlewares.

Why the package exists. Microsoft.AspNetCore.App is not an ordinary NuGet dependency: declaring it makes the application require the ASP.NET Core runtime to be installed, and that requirement is contagious — it propagates to every package that references it, and to whoever references those.

Until v3 the requirement came from Tooark.Extensions, because of a single file. In practice, a worker service or a command-line tool that used Tooark.ValueObjects got Microsoft.AspNetCore.App in its own runtimeconfig.json and would not start on a mcr.microsoft.com/dotnet/runtime image.

From v4 on the requirement lives here. Web projects reference this package; the others do not pay for it.

🔧 Installation

dotnet add package Tooark.AspNetCore

The package does not require registration in the container: GetErrors is an extension method and works without configuration. When the filters and middlewares arrive, they will bring their own registration.

Runtime requirement: because it declares the shared framework, whoever consumes this package needs the ASP.NET Core runtime installed. In a Docker image, use mcr.microsoft.com/dotnet/aspnet instead of mcr.microsoft.com/dotnet/runtime. A web application already uses that image, so in practice nothing changes.

📦 Components

ModelState extensions

• ModelStateExtension.GetErrors(ModelStateDictionary): returns the ModelState error messages.

Walks every entry of the ModelStateDictionary and gathers the ErrorMessage of each error into a single list. A field with more than one error contributes all of its messages. The order is the ModelStateDictionary's, which enumerates by field key, not the order in which the errors were recorded.

Integration with the validations

The returned messages are what the Tooark.Attributes attributes produce: translation keys in the Key;Field format, such as Field.Required;Email. They become text through the IStringLocalizer of Tooark.Extensions, which resolves the language from the request's execution flow.

Errors generated by model binding itself — an integer receiving text, for instance — come with the framework's message, not with a key. The localizer returns that text unchanged and flags ResourceNotFound, which lets you tell the two cases apart when it matters.

Filters and middlewares

Not shipped yet. When they exist, they go in this package, under the Filters/ and Middlewares/ folders. The family only splits a package when the dependency profile differs — that is what motivated separating Tooark.Mediator.EntityFrameworkCore, which pulls Entity Framework Core, from Tooark.Mediator, which does not use it. Filters, middlewares and the extensions here share exactly the same profile, so splitting them into separate packages would reduce nothing.

Namespaces

The extensions live in Tooark.AspNetCore.Extensions.

📝 Usage Examples

Reading the ModelState errors

using Microsoft.AspNetCore.Mvc;
using Tooark.AspNetCore.Extensions;

[ApiController]
[Route("people")]
public sealed class PersonController : ControllerBase
{
  [HttpPost]
  public IActionResult Create([FromBody] CreatePersonDto dto)
  {
    if (!ModelState.IsValid)
    {
      // ["Field.Invalid;Document", "Field.Invalid;Email"]
      var errors = ModelState.GetErrors();

      return BadRequest(errors);
    }

    return Ok();
  }
}

With translated messages

The keys become text through the IStringLocalizer, which comes from Tooark.Extensions and is registered there:

using Tooark.Extensions.Injections;

builder.Services.AddTooarkExtensions();

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Localization;
using Tooark.AspNetCore.Extensions;

[ApiController]
[Route("people")]
public sealed class PersonController(IStringLocalizer localizer) : ControllerBase
{
  [HttpPost]
  public IActionResult Create([FromBody] CreatePersonDto dto)
  {
    if (!ModelState.IsValid)
    {
      // ["The Document field is invalid", "The E-mail field is invalid"]
      var errors = ModelState.GetErrors().Select(error => localizer[error].Value);

      return BadRequest(errors);
    }

    return Ok();
  }
}

The DTO validated by the Tooark.Attributes attributes:

using Tooark.Attributes;

public sealed class CreatePersonDto
{
  [EmailValidation]
  public string Email { get; set; } = null!;

  [DocumentValidation("CPF")]
  public string Cpf { get; set; } = null!;
}

The name that appears in the message is the attribute's, not the property's: that is why the Cpf field produces Field.Invalid;Document, the default of DocumentValidationAttribute. To align the two, pass the propertyName:

[DocumentValidation("CPF", propertyName: "Cpf")]
public string Cpf { get; set; } = null!;

A filter to avoid repeating the check

The same block in every endpoint calls for a filter. While the package does not ship one, it fits in a few lines:

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;
using Microsoft.Extensions.Localization;
using Tooark.AspNetCore.Extensions;

public sealed class ValidationFilter(IStringLocalizer localizer) : IActionFilter
{
  public void OnActionExecuting(ActionExecutingContext context)
  {
    if (context.ModelState.IsValid)
    {
      return;
    }

    var errors = context.ModelState.GetErrors().Select(error => localizer[error].Value);

    context.Result = new BadRequestObjectResult(errors);
  }

  public void OnActionExecuted(ActionExecutedContext context) { }
}

builder.Services.AddControllers(options => options.Filters.Add<ValidationFilter>());

📋 Dependencies

🪪 Contributing

Contributions are welcome! Feel free to open issues and pull requests in the Tooark.AspNetCore repository.

📄 License

This project is licensed under the BSD 3-Clause License. See the LICENSE file for details.