Overview

La librería CodeDesignPlus.Net.Microservice.Commons proporciona un conjunto de herramientas y abstracciones diseñadas para simplificar y estandarizar la configuración y el manejo de aspectos transversales en microservicios, tanto para APIs REST como para servicios gRPC. Su objetivo principal es promover la consistencia y reducir la duplicación de código en proyectos que implementan esta arquitectura.

Propósito y alcance

Esta librería se centra en encapsular configuraciones y funcionalidades comunes que son necesarias en microservicios, facilitando la gestión de excepciones, la validación de datos, la integración con frameworks de mensajería y la documentación de APIs. Su alcance abarca aspectos de la infraestructura de los microservicios, no de la lógica de negocio específica.

Principales características

Manejo de excepciones: Proporciona mecanismos centralizados para la gestión de excepciones tanto en APIs REST como en gRPC.
Validación de datos: Facilita la integración con FluentValidation para la validación de modelos y comandos.
Integración con MediatR: Ofrece un pipeline de validación para comandos de MediatR, asegurando que los datos sean válidos antes de ejecutar la lógica de negocio.
Configuración de Swagger: Simplifica la configuración de Swagger para la documentación de APIs REST.
Intercepción de errores en gRPC: Implementa un interceptor para el manejo centralizado de errores en servicios gRPC.

Casos de uso típicos

Proyectos que implementan microservicios con APIs REST.
Proyectos que utilizan gRPC para la comunicación entre microservicios.
Sistemas que requieren un manejo centralizado y consistente de excepciones.
Aplicaciones que se benefician de la validación de datos utilizando FluentValidation.
Proyectos que usan MediatR para la gestión de comandos y queries.
Necesidad de documentación API usando Swagger.

Componentes Principales

EntryPoints/gRpc/Interceptors/ErrorInterceptor.cs: Interceptor gRPC que maneja excepciones no controladas que ocurren durante la ejecución de un servicio gRPC, convirtiéndolas en respuestas gRPC adecuadas.
EntryPoints/Rest/Middlewares/ExceptionMiddleware.cs: Middleware de ASP.NET Core que captura excepciones no controladas en APIs REST, transformándolas en respuestas HTTP con el código y mensaje adecuado.
EntryPoints/Rest/Swagger/SwaggerExtensions.cs: Clase de extensión que facilita la configuración de Swagger para la documentación de APIs REST, incluyendo la definición de esquemas de autenticación y opciones de personalización.
FluentValidation/FluentExtensions.cs: Métodos de extensión para la integración con FluentValidation, facilitando la configuración y el uso de validadores.
MediatR/MediatRExtensions.cs: Métodos de extensión para configurar el pipeline de MediatR en la aplicación.
MediatR/ValidationPipeline.cs: Pipeline de MediatR que intercepta comandos y queries para validarlos utilizando FluentValidation antes de que lleguen a su respectivo handler.

Directorysrc
- DirectoryCodeDesignPlus.Net.Microservice.Commons
  - DirectoryEntryPoints
    DirectorygRpc
    DirectoryInterceptors
    ErrorInterceptor.cs
    DirectoryRest
    DirectoryMiddlewares
    ExceptionMiddlware.cs
    DirectorySwagger
    SwaggerExtensions.cs
  - DirectoryFluentValidation
    FluentExtensions.cs
  - DirectoryMediatR
    MediatRExtensions.cs
    ValidationPipeline.cs

Primeros Pasos

En esta sección, aprenderás a instalar y configurar la librería CodeDesignPlus.Net.Microservice.Commons en tu proyecto de .NET. Además, explorarás los servicios, métodos de extensión y componentes principales que proporciona la librería para simplificar la configuración y el manejo de aspectos transversales en tus microservicios.

Requisitos previos

.NET 8 o superior.
Conocimiento básico de ASP.NET Core o gRPC.
Familiaridad con el patrón CQRS y/o MediatR (opcional).
Conocimiento de FluentValidation (opcional).

Instalación

Para instalar la librería CodeDesignPlus.Net.Microservice.Commons, puedes utilizar el administrador de paquetes NuGet o la CLI de .NET. A continuación, se muestra un ejemplo de cómo instalar la librería utilizando la CLI de .NET:

dotnet add package CodeDesignPlus.Net.Microservice.Commons

Install-Package CodeDesignPlus.Net.Microservice.Commons

<PackageReference Include="CodeDesignPlus.Net.Microservice.Commons" Version="1.0.0" />

Ejemplo rápido

La solución CodeDesignPlus.Net.Microservice.Commons.Sample muestra cómo configurar y utilizar la librería CodeDesignPlus.Net.Microservice.Commons en una aplicación .NET Core. A continución, se muestra un ejemplo de cómo configurar y utilizar la librería en tu proyecto:

Rest

Este es un ejemplo de cómo configurar una API REST con la librería CodeDesignPlus.Net.Microservice.Commons:

using CodeDesignPlus.Net.Microservice.Commons.EntryPoints.Rest.Middlewares;
using CodeDesignPlus.Net.Microservice.Commons.EntryPoints.Rest.Swagger;
using CodeDesignPlus.Net.Microservice.Commons.FluentValidation;
using CodeDesignPlus.Net.Microservice.Commons.MediatR;
using CodeDesignPlus.Net.Microservice.Rest.Sample;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddControllers();
builder.Services.AddCoreSwagger<Program>(builder.Configuration);

builder.Services.AddFluentValidation();
builder.Services.AddMediatR<Startup>();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseCoreSwagger();
}

app.UseMiddleware<ExceptionMiddleware>();
app.UseHttpsRedirection();

app.MapControllers();

app.Run();

Agregar configuración en appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Core": {
    "Business": "CodeDesignPlus",
    "AppName": "sample-rest",
    "Version": "v1",
    "Description": "Sample of CodeDesignPlus.Net.Core",
    "Contact": {
      "Name": "CodeDesignPlus",
      "Email": "custom@outlook.com"
    }
  }
}

Creamos la clase Startup que se utiliza para configurar los servicios personalizados y obtener una referencia al ensamblado de la aplicación.

namespace CodeDesignPlus.Net.Microservice.Rest.Sample;

/// <summary>
/// Class that allows to initialize the services of the application.
/// </summary>
public class Startup : CodeDesignPlus.Net.Core.Abstractions.IStartup
{
    /// <summary>
    /// Method that allows to initialize the services of the application.
    /// </summary>
    /// <param name="services">The collection of services.</param>
    /// <param name="configuration">The configuration of the application.</param>
    public void Initialize(IServiceCollection services, IConfiguration configuration)
    {

    }
}

Creamos un controlador de ejemplo con métodos vacios y documentados para probar la configuración de Swagger.

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;

namespace CodeDesignPlus.Net.Microservice.Rest.Sample.Controllers
{
    /// <summary>
    /// Controller to manage the users.
    /// </summary>
    [Route("api/[controller]")]
    [ApiController]
    public class UserController : ControllerBase
    {
        /// <summary>
        /// Gets all users.
        /// </summary>
        /// <returns>A list of users.</returns>
        [HttpGet]
        public IActionResult Get()
        {
            return Ok();
        }

        /// <summary>
        /// Gets a user by ID.
        /// </summary>
        /// <param name="id">The user ID.</param>
        /// <returns>The user with the specified ID.</returns>
        [HttpGet("{id}")]
        public IActionResult Get(int id)
        {
            return Ok();
        }

        /// <summary>
        /// Creates a new user.
        /// </summary>
        /// <returns>The result of the creation operation.</returns>
        [HttpPost]
        public IActionResult Post()
        {
            return Ok();
        }

        /// <summary>
        /// Updates an existing user.
        /// </summary>
        /// <param name="id">The user ID.</param>
        /// <returns>The result of the update operation.</returns>
        [HttpPut("{id}")]
        public IActionResult Put(int id)
        {
            return Ok();
        }

        /// <summary>
        /// Deletes a user by ID.
        /// </summary>
        /// <param name="id">The user ID.</param>
        /// <returns>The result of the deletion operation.</returns>
        [HttpDelete("{id}")]
        public IActionResult Delete(int id)
        {
            return Ok();
        }
    }
}

Registramos los servicios:

///...
// Add Swagger
builder.Services.AddCoreSwagger<Program>(builder.Configuration);

// Add FluentValidation
builder.Services.AddFluentValidation();

// Add MediatR
builder.Services.AddMediatR<Startup>();

// Add Middleware
app.UseMiddleware<ExceptionMiddleware>();

gRPC

Este es un ejemplo de cómo configurar un servicio gRPC con la librería CodeDesignPlus.Net.Microservice.Commons:

using CodeDesignPlus.Net.Microservice.Commons.EntryPoints.gRpc.Interceptors;
using CodeDesignPlus.Net.Microservice.gRPC.Sample.Services;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddGrpc(x => {
    x.Interceptors.Add<ErrorInterceptor>();
});


builder.Services.AddGrpcReflection();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapGrpcReflectionService();
}

// Configure the HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");

app.Run();

Agregar configuración en appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http2"
    }
  },
  "Core": {
    "Business": "CodeDesignPlus",
    "AppName": "sample-grpc",
    "Version": "v1",
    "Description": "Sample of CodeDesignPlus.Net.Core",
    "Contact": {
      "Name": "CodeDesignPlus",
      "Email": "custom@outlook.com"
    }
  }
}

Creamos el archivo greet.proto que define el servicio gRPC.

syntax = "proto3";

option csharp_namespace = "CodeDesignPlus.Net.Microservice.Sample";

package greet;

// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply);
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings.
message HelloReply {
  string message = 1;
}

Creamos el servicio GreeterService que implementa el servicio gRPC definido en greet.proto.

using Grpc.Core;
using CodeDesignPlus.Net.Microservice.Sample;

namespace CodeDesignPlus.Net.Microservice.gRPC.Sample.Services;

public class GreeterService : Greeter.GreeterBase
{
    private readonly ILogger<GreeterService> _logger;
    public GreeterService(ILogger<GreeterService> logger)
    {
        _logger = logger;
    }

    public override Task<HelloReply> SayHello(HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

Registramos los servicios:

///...
builder.Services.AddGrpc(x => {
    // Add Error Interceptor
    x.Interceptors.Add<ErrorInterceptor>();
});

Métodos de extensión

La librería CodeDesignPlus.Net.Microservice.Commons proporciona una serie de métodos de extensión que facilitan la configuración y el uso de sus funcionalidades en aplicaciones .NET. A continuación, se describen los métodos de extensión más comunes y su propósito:

AddSwagger

Configura los servicios de Swagger con una configuración predeterminada.

Explora la clase SwaggerExtensions

AddFluentValidation

Configura FluentValidation para su uso en la aplicación.

Explora la clase FluentExtensions

AddMediatR

Configura MediatR y agrega el pipeline de validación a la aplicación.

Explora la clase MediatRExtensions

Conclusiones

La librería CodeDesignPlus.Net.Microservice.Commons facilita la construcción de microservicios robustos y consistentes al proporcionar abstracciones y configuraciones comunes. Su enfoque en el manejo de excepciones, la validación de datos y la documentación de APIs mejora la calidad del código y la productividad del desarrollo.