Skip to main content

MinimalHelpers.Routing.Analyzers by Maroc Minerva

Nuget / site data​

Nuget GitHub last commit GitHub Repo stars

Details​

Info​

info

Name: MinimalHelpers.Routing.Analyzers

A library that provides a Source Generator for automatic endpoints registration in Minimal API projects

Author: Maroc Minerva

NuGet: https://www.nuget.org/packages/MinimalHelpers.Routing.Analyzers/

You can find more details at https://github.com/marcominerva/MinimalHelpers

Source : https://github.com/marcominerva/MinimalHelpers

Original Readme​

note

Minimal APIs Helpers

Lint Code Base License: MIT

A collection of helpers libraries for Minimal API projects.

MinimalHelpers.Routing​

Nuget Nuget

A library that provides Routing helpers for Minimal API projects for automatic endpoints registration using Reflection.

Installation​

The library is available on NuGet. Just search for MinimalHelpers.Routing in the Package Manager GUI or run the following command in the .NET CLI:

dotnet add package MinimalHelpers.Routing

Usage​

Create a class to hold your route handlers registration and make it implementing the IEndpointRouteHandlerBuilder interface:

.NET 6.0

public class PeopleEndpoints : MinimalHelpers.Routing.IEndpointRouteHandlerBuilder
{
    public void MapEndpoints(IEndpointRouteBuilder endpoints)
    {
        endpoints.MapGet("/api/people", GetList);
        endpoints.MapGet("/api/people/{id:guid}", Get);
        endpoints.MapPost("/api/people", Insert);
        endpoints.MapPut("/api/people/{id:guid}", Update);
        endpoints.MapDelete("/api/people/{id:guid}", Delete);
    }

    // ...
}

.NET 7.0 or higher

public class PeopleEndpoints : MinimalHelpers.Routing.IEndpointRouteHandlerBuilder
{
    public static void MapEndpoints(IEndpointRouteBuilder endpoints)
    {
        endpoints.MapGet("/api/people", GetList);
        endpoints.MapGet("/api/people/{id:guid}", Get);
        endpoints.MapPost("/api/people", Insert);
        endpoints.MapPut("/api/people/{id:guid}", Update);
        endpoints.MapDelete("/api/people/{id:guid}", Delete);
    }

    // ...
}

Note Starting from .NET 7.0, the IEndpointRouteHandlerBuilder interface exposes the MapEndpoints method as static abstract, so it can be called without creating an instance of the handler.

Call the MapEndpoints() extension method on the WebApplication object inside Program.cs before the Run() method invocation:

// using MinimalHelpers.Routing;
app.MapEndpoints();

app.Run();

By default, MapEndpoints() will scan the calling Assembly to search for classes that implement the IEndpointRouteHandlerBuilder interface. If your route handlers are defined in another Assembly, you have two alternatives:

  • Use the MapEndpoints() overload that takes the Assembly to scan as argument
  • Use the MapEndpointsFromAssemblyContaining of T() extension method and specify a type that is contained in the Assembly you want to scan

You can also explicitly decide what types (among the ones that implement the IRouteEndpointHandlerBuilder interface) you want to actually map, passing a predicate to the MapEndpoints method:

app.MapEndpoints(type =>
{
    if (type.Name.StartsWith("Products"))
    {
        return false;
    }

    return true;
});

Note These methods rely on Reflection to scan the Assembly and find the classes that implement the IEndpointRouteHandlerBuilder interface. This can have a performance impact, especially in large projects. If you have performance issues, consider using the explicit registration method. Moreover, this solution is incompatibile with Native AOT.

If you're working with .NET 7.0 or higher, the reccommended approach is to use the MinimalHelpers.Routing.Analyzers package, that provides a Source Generator for endpoints registration, as described later.

MinimalHelpers.Routing.Analyzers (.NET 7.0 or higher)​

Nuget Nuget

A library that provides a Source Generator for automatic endpoints registration in Minimal API projects.

Installation​

The library is available on NuGet. Just search for MinimalHelpers.Routing in the Package Manager GUI or run the following command in the .NET CLI:

dotnet add package MinimalHelpers.Routing.Analyzers

Usage​

Create a class to hold your route handlers registration and make it implementing the IEndpointRouteHandlerBuilder interface:

public class PeopleEndpoints : IEndpointRouteHandlerBuilder
{
    public static void MapEndpoints(IEndpointRouteBuilder endpoints)
    {
        endpoints.MapGet("/api/people", GetList);
        endpoints.MapGet("/api/people/{id:guid}", Get);
        endpoints.MapPost("/api/people", Insert);
        endpoints.MapPut("/api/people/{id:guid}", Update);
        endpoints.MapDelete("/api/people/{id:guid}", Delete);
    }

    // ...
}

Note You only need to use the MinimalHelpers.Routing.Analyzers package. With this Source Generator, the IEndpointRouteHandlerBuilder interface is auto-generated.

Call the MapEndpoints() extension method on the WebApplication object inside Program.cs before the Run() method invocation:

app.MapEndpoints();

app.Run();

Note The MapEndpoints method is generated by the Source Generator.

MinimalHelpers.OpenApi​

Nuget Nuget

A library that provides OpenApi helpers for Minimal API projects.

Installation​

The library is available on NuGet. Just search for MinimalHelpers.OpenApi in the Package Manager GUI or run the following command in the .NET CLI:

dotnet add package MinimalHelpers.OpenApi

Usage​

Extension methods for OpenApi

This library provides some extensions methods that simplify the OpenAPI configuration in Minimal API projects. For example, it is possible to customize the description of a response using its status code:

endpoints.MapPost("login", LoginAsync)
    .AllowAnonymous()
    .WithValidation<LoginRequest>()
    .Produces<LoginResponse>(StatusCodes.Status200OK)
    .Produces<LoginResponse>(StatusCodes.Status206PartialContent)
    .Produces(StatusCodes.Status403Forbidden)
    .ProducesValidationProblem()
    .WithOpenApi(operation =>
    {
        operation.Summary = "Performs the login of a user";

        operation.Response(StatusCodes.Status200OK).Description = "Login successful";
        operation.Response(StatusCodes.Status206PartialContent).Description = "The user is logged in, but the password has expired and must be changed";
        operation.Response(StatusCodes.Status400BadRequest).Description = "Incorrect username and/or password";
        operation.Response(StatusCodes.Status403Forbidden).Description = "The user was blocked due to too many failed logins";

        return operation;
    });

Extension methods for RouteHandlerBuilder

Often we have endpoints with multiple 4xx return values, each of which produces a ProblemDetails response:

endpoints.MapGet("/api/people/{id:guid}", Get)
   .ProducesProblem(StatusCodes.Status400BadRequest)
   .ProducesProblem(StatusCodes.Status401Unauthorized)
   .ProducesProblem(StatusCodes.Status403Forbidden)
   .ProducesProblem(StatusCodes.Status404NotFound);

To avoid multiple calls to ProducesProblem, we can use the ProducesDefaultProblem extension method provided by the library:

endpoints.MapGet("/api/people/{id:guid}", Get)
   .ProducesDefaultProblem(StatusCodes.Status400BadRequest, StatusCodes.Status401Unauthorized,
       StatusCodes.Status403Forbidden, StatusCodes.Status404NotFound);

MinimalHelpers.Validation​

Nuget Nuget

A library that provides an Endpoint filter for Minimal API projects to perform validation with Data Annotations, using the MiniValidation library.

Installation​

The library is available on NuGet. Just search for MinimalHelpers.Validation in the Package Manager GUI or run the following command in the .NET CLI:

dotnet add package MinimalHelpers.Validation

Usage​

Decorates a class with attributes to define the validation rules:

using System.ComponentModel.DataAnnotations;

public class Person
{
    [Required]
    [MaxLength(20)]
    public string? FirstName { get; set; }

    [Required]
    [MaxLength(20)]
    public string? LastName { get; set; }

    [MaxLength(50)]
    public string? City { get; set; }
}

Add the WithValidation of T() extension method to enable the validation filter:

using MinimalHelpers.Validation;

app.MapPost("/api/people", (Person person) =>
    {
        // ...
    })
    .WithValidation<Person>();

If the validation fails, the response will be a 400 Bad Request with a ValidationProblemDetails object containing the validation errors, for example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred",
  "status": 400,
  "instance": "/api/people",
  "traceId": "00-009c0162ba678cae2ee391815dbbb59d-0a3a5b0c16d053e6-00",
  "errors": {
    "FirstName": [
      "The field FirstName must be a string or array type with a maximum length of '20'."
    ],
    "LastName": [
      "The LastName field is required."
    ]
  }
}

If you want to customize validation, you can use the ConfigureValidation extension method:

using MinimalHelpers.Validation;

builder.Services.ConfigureValidation(options =>
{
    // If you want to get errors as a list instead of a dictionary.
    options.ErrorResponseFormat = ErrorResponseFormat.List;

    // The default is "One or more validation errors occurred"
    options.ValidationErrorTitleMessageFactory =
        (context, errors) => $"There was {errors.Values.Sum(v => v.Length)} error(s)";
});

You can use the ValidationErrorTitleMessageFactory, for example, if you want to localized the title property of the response using a RESX file.

MinimalHelpers.FluentValidation​

Nuget Nuget

A library that provides an Endpoint filter for Minimal API projects to perform validation using FluentValidation.

Installation​

The library is available on NuGet. Just search for MinimalHelpers.FluentValidation in the Package Manager GUI or run the following command in the .NET CLI:

dotnet add package MinimalHelpers.FluentValidation

Usage​

Create a class that extends AbstractValidator of T and define the validation rules:

using FluentValidation;

public record class Product(string Name, string Description, double UnitPrice);

public class ProductValidator : AbstractValidator<Product>
{
    public ProductValidator()
    {
        RuleFor(p => p.Name).NotEmpty().MaximumLength(50).EmailAddress();
        RuleFor(p => p.Description).MaximumLength(500);
        RuleFor(p => p.UnitPrice).GreaterThan(0);
    }
}

Register validators in the Service Collection:

using FluentValidation;

// Assuming the validators are in the same assembly as the Program class
builder.Services.AddValidatorsFromAssemblyContaining<Program>();

Add the WithValidation of T() extension method to enable the validation filter:

using MinimalHelpers.FluentValidation;

app.MapPost("/api/products", (Product product) =>
    {
        // ...
    })
    .WithValidation<Product>();

If the validation fails, the response will be a 400 Bad Request with a ValidationProblemDetails object containing the validation errors, for example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred",
  "status": 400,
  "instance": "/api/products",
  "traceId": "00-f4ced0ae470424dd04cbcebe5f232dc5-bbdcc59f310ebfb8-00",
  "errors": {
    "Name": [
      "'Name' cannot be empty."
    ],
    "UnitPrice": [
      "'Unit Price' must be grater than '0'."
    ]
  }
}

If you want to customize validation, you can use the ConfigureValidation extension method:

using MinimalHelpers.Validation;

builder.Services.ConfigureValidation(options =>
{
    // If you want to get errors as a list instead of a dictionary.
    options.ErrorResponseFormat = ErrorResponseFormat.List;

    // The default is "One or more validation errors occurred"
    options.ValidationErrorTitleMessageFactory =
        (context, errors) => $"There was {errors.Values.Sum(v => v.Length)} error(s)";
});

You can use the ValidationErrorTitleMessageFactory, for example, if you want to localized the title property of the response using a RESX file.

Contribute

The project is constantly evolving. Contributions are welcome. Feel free to file issues and pull requests on the repo and we'll address them as we can.

About​

note

Controller like API registering

How to use​

Example ( source csproj, source files )​

This is the CSharp Project that references MinimalHelpers.Routing.Analyzers

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="8.0.4" />
    <PackageReference Include="MinimalHelpers.Routing.Analyzers" Version="1.0.13" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0" />
  </ItemGroup>
    <PropertyGroup>
        <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
        <CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)\GX</CompilerGeneratedFilesOutputPath>
    </PropertyGroup>
</Project>

Generated Files​

Those are taken from $(BaseIntermediateOutputPath)\GX

// <auto-generated />
namespace Microsoft.AspNetCore.Routing;

#nullable enable annotations
#nullable disable warnings

/// <summary>
/// Provides extension methods for <see cref="IEndpointRouteBuilder" /> to add route handlers.
/// </summary>
public static class EndpointRouteBuilderExtensions
{
    /// <summary>
    /// Automatically registers all the route endpoints defined in classes that implement the <see cref="IEndpointRouteHandlerBuilder "/> interface.
    /// </summary>
    /// <param name="endpoints">The <see cref="IEndpointRouteBuilder" /> to add routes to.</param>
    public static IEndpointRouteBuilder MapEndpoints(this IEndpointRouteBuilder endpoints)
    {            
        global::APIDemo.PersonAPI.MapEndpoints(endpoints);

        return endpoints;
    }
}

Usefull​

Download Example (.NET C# )​

tip

Download Example project MinimalHelpers.Routing.Analyzers

Share MinimalHelpers.Routing.Analyzers​

https://ignatandrei.github.io/RSCG_Examples/v2/docs/MinimalHelpers.Routing.Analyzers

In the same category (API) - 8 other generators​

Microsoft.Extensions.Configuration.Binder​

MinimalApiBuilder​

MinimalApis.Discovery​

RDG​

Refit​

RSCG_WebAPIExports​

SafeRouting​

SkinnyControllersCommon​