DEV Community: Andres Lozada Mosto

Midiendo el rendimiento de nuestro código con BenchmarkDotNet - MemoryDiagnoser

Andres Lozada Mosto — Sun, 16 Jul 2023 16:52:08 +0000

En el primer artículo de esta serie introducimos el concepto de Benchmark y como crear un test de rendimiento en C#. Es el momento de entender como analizar la utilización de la memoria y del GC de .Net.

Utilización de MemoryDiagnoser

En este caso vamos a utilizar un Benchmark diferente al que utilizamos anteriormente para que nos permita ver cuanta memoria es utilizada y cuantas veces se ejecuta el GC.

Para ver éstas métricas es necesario agregar el atributo [MemoryAnaliser] a nuestra clase.

BenchmarkRunner.Run(typeof(StringVsSpan));

[MemoryDiagnoser]
public class StringVsSpan
{
    private string[] ListOfStrings { get; set; }

    [Benchmark]
    public string concatStrings_concat()
    {
        var retValue = string.Empty;
        for (int i = 0; i < ListOfStrings.Length; i++)
            retValue += ListOfStrings[i];

        return retValue;
    }

    [Benchmark]
    public string concatStrings_StringBuilder()
    {
        var sb = new StringBuilder();
        for(int i = 0; i < ListOfStrings.Length; i++)
            sb.Append(ListOfStrings[i]);

        return sb.ToString();
    }

    [Benchmark]
    public string concatStrings_Join()
    {
        return String.Join("", ListOfStrings);
    }

    [GlobalSetup]
    public void Startup()
    {
        var faker = new Faker("en");
        ListOfStrings = faker.Lorem.Paragraphs(50, "\n\n").Split("\n\n");
    }
}

Lo ejecutamos ..

... y obtenemos el siguiente resultado

Se ven 2 nuevas columnas, Gen0 y Allocation

Allocation
Es la cantidad de memoria en el Heap utilizada para correr la función que estamos probando por cada iteración

Gen0/Gen1/Gen2
En donde Gen0 es la ejecución del GC donde recolecta objetos de corta duración y se ejecuta de forma mas periódica. En este caso no tenemos Gen1 ni Gen2, pero estas ejecuciones del GC recolectan objetos mas "pesados" y que tienen un ciclo de vida más largos.

En nuestro resultado podemos concluir que la manera más eficiente de concatenar strings (dentro de las alternativas que se evaluaron) es utilizando String.Join porque genera menos ejecuciones del GC de primer nivel y utiliza menos alocación de memoria en el Heap.

Conclusión

Agregando el análisis de memoria a nuestros tests de benchmark podemos identificar como se comporta, en manera general, diferentes estrategias para obtener un mismo resultado y darnos major información para elegir una y otra.

Midiendo el rendimiento de nuestro código con BenchmarkDotNet

Andres Lozada Mosto — Sun, 16 Jul 2023 15:34:56 +0000

Un Benchmark (en Software) es un proceso que nos permite medir el rendimiento de un software, componente, algoritmo o bloque de código y verificar si cumple con los requerimientos establecidos de por ejemplo, uso de memoria o tiempos de ejecución.

Este tipo de pruebas nos permite incluso comparar 2 componentes, 2 versiones de un mismo componente o diferentes algoritmos y verificar cual tiene mejor rendimiento.

Introducción a BenchmarkDotNet

BenchmarkDotNet es la librería de .Net mas aceptada por la comunidad siendo utilizada por varios proyectos de Microsoft.

BenchmarkDotNet nos permite generar pruebas de Benchmark y ejecutarlas con la misma simplicidad de ejecución que las de testing unitario.

Entre las funcionalidades que podemos encontrar se encuentran:

Ejecución de multiples Benchmark
Setup/Cleanup entre ejecuciones
Parametrización (al igual que por ejemplo XUnit/NUnit)
Benchamark sobre diferentes plataformas/runtimes: NetFramework, Dotnet, WebAssembly, x86/x64, Mono, AOT
Diagnosers: de memoria, JIT, Disasembly entre otros
Exporters: CSV, HTML, RPlot, JSON, Markdown, etc
Generación de trace files para su posterior análisis en PerfView/Visual Studio Profiler/SpeedScope
Entre otros

Creando nuestro primer Benchmark

Nuestro Benchmark debe esta encapsulado en una clase y por cada función atómica de código a analizar le debemos agregar el atributo [Benchmark] para que la librería pueda auto-descubrir los bloques de código a ejecutar.

Usaremos Bogus para generar Fake data y el atributo [GlobalSetup]para generar una función de inicialización donde inicializamos lo que necesitamos. Ésta función se ejecutará una única vez y no afectará las métricas.

Vamos al ejemplo básico

using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;
using Bogus;

BenchmarkRunner.Run(typeof(BenchmarkFor));

public class BenchmarkFor
{
    private const int __amountOfItems = 1000;
    private string[] ListOfStrings { get; set; }

    [Benchmark(Baseline = true)]
    public int[] ForClassic()
    {
        var retValues = new int[__amountOfItems];
        for (var i = 0; i < ListOfStrings.Length; i++) 
            retValues[i] = ListOfStrings[i].Length;
        return retValues;
    }

    [Benchmark]
    public int[] ForWithLinQ() => ListOfStrings.Select(x => x.Length).ToArray();

    [GlobalSetup]
    public void Startup()
    {
        var faker = new Faker("en");
        ListOfStrings = Enumerable.Range(0, __amountOfItems)
            .Select(x => faker.Lorem.Word())
            .ToArray();
    }
}

Hay que prestar atención que cuando se realizan estas pruebas el entorno donde se ejecutan es muy importante porque puede afectar los tiempos de gran manera. Es recomendable ejecutar el proceso desde la consola (para no attachar el debugger), compilar en modo release y no tener otros procesos corriendo en la notebook y si se puede ejecutar en un entorno aislado (ej en una instancia en cloud), mucho mejor.

Ahora sí, lo ejecutamos...

... y luego de esperar un ratito (si, tarda y genera mucho log por pantalla) obtenemos la siguiente información

Lo más importante es el último recuadro en donde vemos los tiempos promedio que tardo cada función que marcamos como [Benchmark], siendo la primera, 2x veces más rápida que la opción que utiliza Linq. En la misma, el resto de las columnas muestran la desviación estándar, la mediana y el ratio.

Algo importante a considerar en algunos casos es el Histograma que muestra para cada función. En ellos podemos ver como se distribuyeron los tiempos de las sucesivas ejecuciones y ante ciertos casos no ayudará a encontrar puntos de mejora.

Por último, se muestra la sección de Outliers que nos indica cuantos casos fueron eliminados de la muestra porque estuvieron muy por fuera del rango del resto de los casos (ya sea que estuvieron muy por debajo o muy por arriba).

Conclusión

Conocer como realizar un Benchmark de nuestro código es una habilidad muy útil para tenerla dentro de nuestro toolbox de herramientas como desarrollador y nos va a ser de mucha ayuda cuando queramos medir la performance de nuestro código.

Creando un API en Net Core - Creando un cliente para nuestro API

Andres Lozada Mosto — Fri, 09 Apr 2021 22:28:26 +0000

En el artículo anterior vimos como agregar Swagger y Open API junto con la librería Swashbuckle en nuestros proyectos de APIs. Es el momento de ver las opciones que tenemos para generar clientes que consuman nuestro API desde diferentes lenguajes de programación.

En primer lugar veremos como generar el archivo JSON con la especificación de Open API de nuestro API de forma que lo podamos guardar físicamente para su uso posterior, ya sea para generar los clientes como para utilizarlo en cualquier otro tool de APIs.

Luego, con la ayuda de NSwagStudio vamos a crear clientes en lenguajes Typescript y C# junto con un pequeño ejemplo de como utilizarlos.

Por último, vamos a generar generar clientes en otros lenguajes como Java, NodeJS y Python.

Les parece interesante? Vamos? 💪

Generando Open API JSON

La librería Swashbuckle nos provee de una UI desde donde podemos obtener, entre otras grandes funcionalidades, el archivo JSON con la documentación de Open API. Esta forma no es la más útil si estamos trabajando en un entorno de integración continua y nuestros "Clientes" se generan de manera automática.

Por suerte Swashbuckle nos provee un tool que nos ayuda a generar de una manera muy simple y totalmente compatible con entornos de CI.

Para ello, debemos instalar el Global Tool posicionándonos en la carpeta del proyecto del API desde la línea de comandos y escribir lo siguiente.

dotnet tool install --version 6.1.1 Swashbuckle.AspNetCore.Cli

(Recomiendo antes de realizar su instalación revisar la versión más nueva o bien la correspondiente a la que se debe utilizar de acuerdo a la versión de Net Core utilizada).

Una vez realizado el paso anterior podremos generar el archivo de la siguiente manera:

dotnet swagger tofile --output [output] [startupassembly] [swaggerdoc]

Donde

[output]: Es el Path donde queremos guardar el archivo generado
[startupassembly]: Es el Path donde se ubica la DLL con el archivo de startup.cs del proyecto
[swaggerdoc] Es el nombre que le dimos al documento Swagger cuando lo incluimos en el startup.cs (c.SwaggerDoc("MyFirstNetCoreRESTAPI" <--- es este nombre).

En nuestro API de ejemplo el comando queda de la siguiente forma:

dotnet swagger tofile --output openapispec.json .\bin\Debug\net5.0\MyFirstNetCoreWebAPI.WebAPI.dll MyFirstNetCoreRESTAPI

Podemos ver el output del comando

Primer paso completo, ya tenemos el archivo con la especificación de Open API generado.

NSwagStudio

NSwagStudio es una herramienta de NSwag para la creación de clientes en lenguajes CSharp y TypeScript (con opción a exportar listo para usar desde Angular, React, etc) de un API a partir de un archivo en formato Open API .

Este programa nos permitirá guardar la configuración de la generación de los API en un archivo .nswag para poder utilizarlos todas las veces que sean necesarias.

Podemos seleccionar desde donde queremos obtener la información del API, ya sea desde un archivo físico, una URL, binarios, etc e indicar el Runtime de .Net Core o .Net Framework.

La configuración para la creación del API provee una gran cantidad de opciones la cual podremos ver en otro artículo.

En nuestro proyecto de API ejemplo (que pueden descargar desde Github) creamos 2 nuevos proyectos.

MyFirstNetCoreWebAPI.WebAPI.Client: El cual es un proyecto de librería donde colocamos el archivo .swag y donde se va a generar el archivo con el código del cliente
MyFirstNetCoreWebAPI.ConsoleClient: Es un proyecto de Consola para probar el cliente del API.

A gusto personal, prefiero que cada controller del API tenga su propia Interfaz e implementación donde su constructor reciba como parámetro una instancia de HTTPClient. De esta manera podemos configurar el HTTPClient de la manera que nosotros queramos, como por ejemplo agregarle un token de autenticación, políticas de retry (con Polly) y cualquier otra cosa que necesitemos de forma desacoplada del cliente.

La próxima vez que se actualice un endpoint del API simplemente es necesario darle doble click al archivo .nswag y generar nuevamente los archivos. Fácil no? 💪

Con esta configuración tenemos un cliente de nuestro API en una librería compartida que podremos utilizar desde cualquier proyecto de la solución o subirla a un repositorio de Nuget para ser compartida entre diferentes proyectos.

Lo mismo podemos hacer para los clientes de TypeScript.

NSwagStudio + CLI

NSwagStudio nos permite generar los clientes ejecutando por línea de comando programa a partir de un archivo .nswag de la siguiente manera:

nswag run /runtime:Net50

Este comando, claro, lo debemos ejecutar sobre la misma ubicación donde se encuentre el archivo .nswag y en la documentación podemos ver todas las opciones que podemos pasarle.

Esta opción nos puede ser útil para entornos de CI o bien para agregarlo al PostBuild del MSBuild.

NSwagStudio + MSBuild

La generación de los clientes también podemos agregarla como un Task del MSBuild.

En mi caso particular no es la opción que mas me gusta pero se que a muchos les es muy útil.

Pueden ver toda la documentación aquí

NSwagStudio + Otras alternativas

En entornos de CI podemos instalar NSwagStudio por medio de Chocolatey y ejecutarlo por medio del CLI tal como vimos antes, pero la restricción que tenemos es que no queda tan "standard" para un Pipeline de Build.

La opción en estos casos podemos utilizar otras altenativas

NodeJS

Podemos utilizar el npm package oficial para instalarlo en el CI, Docker o desde donde sea necesario y ejecutarlo desde allí

Docker

Otra opción es utilizar Docker, ya se para integrarlo en un stage del docker que compila la aplicación en el Pipeline o en un paso separado. En este caso tenemos dos opciones, o bien utilizar la versión de NodeJS como vimos recién o utilizar el ejecutable sobre NetCore.

En el proyecto MyFirstNetCoreWebAPI.ConsoleClient tenemos ahora un Dockerfile, un archivo ClientGenerator-docker-net.nswag específico para ejecutarse dentro de Docker y un archivo de Json de OpenAPI con la especificación del API que creamos en pasos previos.

El ejemplo del Dockerfile es muy simple y sirve de base para que armen uno propio basado en sus necesidades.

El detalle de cada paso que realiza el Dockerfile esta explicado en el mismo archivo.

Veamos como lo ejecutamos

// creamos la imagen
docker build -t myfirstapi/nswag .

// corremos un container con la imagen
docker run -v ${pwd}:/resultado myfirstapi/nswag

Como pueden ver, en este último paso montamos el directorio actual en la carpeta "resultado". Si no vieron el Dockerfile les cuento que el entrypoint realiza la exportación de los archivos de los clientes a esta carpeta que tenemos montada y de esta manera sacamos los archivos generados fuera del container.

Si quieren revisar como quedan los archivos, pueden ejecutar este comando para navegar el container.

docker run -it --entrypoint /bin/bash -v ${pwd}:/resultado myfirstapi/nswag

OpenAPi Tools

La sección anterior vimos como generamos clientes para TypeScript y CSharp, pero que pasa si necesitamos para otros lenguajes como Java o Python? La respuesta es el generador oficial de Open API

Pueden revisar la cantidad infinita de generadores desde su web https://openapi-generator.tech/ y lo mejor es que pueden utilizar la versión de NodeJS o bien proveen un Docker para no tener que configurar nada y tenerlo funcionando de forma inmediata.

La verdad que iba a poner unos ejemplos, pero ya se hace muy largo el artículo. Dejen unos comentarios si quieren que el próximo artículo lo veamos 😁.

Creando un API en Net Core - OpenAPI & Swagger

Andres Lozada Mosto — Fri, 26 Feb 2021 03:24:44 +0000

Hi there! 👋

Llegó una nueva parte de esta guía de creación de APIs en NetCore.

En este artículo veremos cómo incluir OpenAPI en nuestro proyecto.

Si quieren ver el resultado final ejecutándose, pueden bajarlo del github

Vamos?

¿Qué es OpenAPI?

OpenAPI (que ya fue mencionada en nuestro segundo artículo) es un estándar que predefine como describir o documentar nuestro API.

Dejando detalles de lado, OpenAPI define debe existir un archivo en formato JSON o YAML en donde se definan todos lo recursos del API, acciones que se le pueden realizar, información que se debe enviar a cada endpoint y que se puede recibir, etc.

En definitiva, regula todo el aspecto de como escribir ese archivo y por consiguiente, define la forma de documentar nuestro API para que otro equipo/persona sepa cómo utilizarlo.

¿Qué es Swagger?

Swagger es un proyecto open source que implementa el estándar. El proyecto fue cedido a la Open API Initiative y desde ese momento se transforman en sinónimos.

Hay que diferenciar que uno es el estándar y el otro (Swagger) es una implementación y creación del UI en base al archivo JSON/YAML generado.

Alternativas

En cuanto a especificaciones, tenemos a RAML.

Para reemplazar el UI, tenemos alternativas en donde se destaca Redoc.

En este link podemos ver un listado de opciones al UI de Swagger.

Agregar OpenAPI y Swagger UI a nuestro API

En mundo de .Net Core hay 2 librerías principales, Swashbuckle y NSwag. En este caso vamos a utilizar Swashbuckle que es la que desde .Net 5 viene incluida por defecto en el template de APIs

Librerías

Agregamos el siguiente paquete de Nuget

$> dotnet add package Swashbuckle.AspNetCore

Configurando el Startup.cs

Debemos agregar unas líneas en las funciones ConfigurationServices

services.AddSwaggerGen();

Y en Configure

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

Customizaciones

SwaggerUIPodemos agregar información a la documentación, agregar nuestros propios archivos _css y javascript para personalizar la pantalla.

Documentación de XMLDocs

Podemos utilizar nuestra documentación de código por medio de XML Docs para mostrar información en el UI.

Primero debemos indicarle al proyecto que genere el archivo XML con los comentarios de las funciones

<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Luego le decimos a Swagger que cargue el archivo

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { 
        Title = "My First Net Core REST API",
        Version = "v1"
    });

    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

Logo customizado

Podemos agregar customizaciones a la UI para que se adapte a la gráfica de nuestra empresa. Para eso podemos agregar archivos CSS, Javascript o bien utilizar un HTML completo personalizado.

Para los cambios básicos (cambio de logo y color del header) solo necesitaremos agregar un CSS nuevo de la siguiente manera

app.UseStaticFiles();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "MyFirstNetCoreWebAPI.WebAPI v1");
    c.InjectStylesheet("/swagger-ui/swagger-custom.css");
});

y el archivo css dentro de una nueva carpeta que llamaremos wwwroot

.swagger-ui .topbar {
    background-color: #1abc9c;
}

.topbar-wrapper a img[alt="Swagger UI"] {
    display: none;
}

.topbar-wrapper a {
    display: block;
    -moz-box-sizing: border-box;
    box-sizing: border-box;
    background: url(apilogo.png) no-repeat;
    width: 300px; /* Width of new image */
    height: 86px; /* Height of new image */
    padding-left: 180px; /* Equal to width of new image */
}


.topbar-wrapper .select-label span {
    color: #212121;
}

El previo css nos provee este bonito resultado.

Información de licencia y autoría

Otra cosa que podemos agregar e importante cuando la API es pública es la información de Autoría y Licencia.

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { 
        Title = "My First Net Core REST API",
        Version = "v1",
        Description = "A simple example ASP.NET Core Web API by Andrés Lozada Mosto, You can find this tutorial here: https://dev.to/andreslozadamosto/creando-un-api-en-net-core-5-intro-2nc2",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Andres Lozada Mosto",
            Email = string.Empty,
            Url = new Uri("https://github.com/andreslozadamosto"),
        },
        License = new OpenApiLicense
        {
            Name = "Use under MIT licence",
            Url = new Uri("https://choosealicense.com/licenses/mit/"),
        }
    });
});

Definiendo datos requeridos

Podemos utilizar los atributos como [required] para indicar cuáles datos son requeridos por el objeto recibido como parámetro

Tipo de salida

Algo muy importante es indicar al público target que utilizará nuestro API el formato en que recibirá las respuestas. Esto se realiza indicando el MIME TYPE devuelto por el Action del Controller.

[Produces("application/json")]

Este atributo lo podemos utilizar a nivel de Clase como de Action Method.

Como veremos en artículos posteriores, cuando se llama a un API desde un frontend en javascript éste le puede indicar que formato de tipo de respuesta le gustaría recibirf_JSON_, XML, otro). Net Core provee soporte a esta funcionalidad y se pueden registrar cualquier tipo de formarteadores de salida. Pero este tema lo veremos en mayor profundidad en próximos artículos.

Códigos de HTTP de respuesta [ProducesResponseType]

Otra información muy relevante por los usuarios de nuestra API es conocer cuales son los códigos HTTP de respuesta que podemos obtener al realizar un request.

Para documentar esto utilizamos el siguiente atributo a nivel de Action Method

[ProducesResponseType(StatusCodes.Status400BadRequest)]
[ProducesResponseType(StatusCodes.Status409Conflict)]
[ProducesResponseType(StatusCodes.Status201Created)]

El enum StatusCodes tiene enumerados para todos los diferentes códigos de respuesta HTTP.

En el UI queda desglosado las diferentes posibles respuestas

Extra

Hay un mundo de librerías que podemos utilizar junto con Open API tales como generadores de librerías cliente (para consumir nuestro API desde cualquier lenguaje), generadores de server stubs, chequeo de seguridad entre otros.

Esta web https://openapi.tools nos provee un gran listado de herramientas organizadas por tema.

Creando un API en Net Core - Mi primer API

Andres Lozada Mosto — Wed, 03 Feb 2021 21:42:28 +0000

Llegó el tan ansiado momento de meter mano en el código. Durante este artículo vamos a crear nuestro primer API e implementar algunas de las cosas que vimos en los artículos anteriores.

Pueden clonarse el proyecto desde github.

Creando nuestro primer proyecto

Si estamos utilizando un IDE como Visual Studio o Rider simplemente vamos a la opción de crear un nuevo proyecto, seleccionamos el tipo de proyecto Web API y seguimos las instrucciones. Con esta acción se generará un nuevo proyecto utilizando como base el template que viene integrado en Net Core y seleccionará la versión de Net Core más nueva que se encuentre instalada en el sistema (recomiendo utilizar la última, Net Core 5).

En cambio si estamos usando la línea de comandos y un editor como VS Code para programar, debemos seguir estos pasos para crear la estructura del proyecto

// creamos la carpeta de la solución
$> mkdir MyFirstNetCoreWebAPI

// creamos el archivo de solución
$> dotnet new sln --name MyFirstNetCoreWebAPI

// creamos la carpeta de código
$> mkdir src
$> cd src

// creamos el proyecto de web api
$> dotnet new webapi --name MyFirstNetCoreWebAPI.WebAPI

// agregamos el proyecto a la solución
$> cd ..
$> dotnet sln .\MyFirstNetCoreWebAPI.sln add .\src\MyFirstNetCoreWebAPI.WebAPI\MyFirstNetCoreWebAPI.WebAPI.csproj

Si nos gusta trabajar con la consola y/o queremos utilizar un IDE liviano como VS Code talvez convenga instalar el generador de dotnet que nos ayudará a crear los elementos necesarios (mas allá de los plugins de VS Code).

$> dotnet tool install -g dotnet-aspnet-codegenerator

## Agregamos el paquete al proyecto
$> dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design

Ya sea que creemos desde donde creemos el proyecto, luego éste puede utilizarse desde cualquier IDE.

Con el proyecto creado, borramos las 2 clases que se crean de forma automática: WeatherForecast.cs y WeatherForecastController.cs. Es código del template que se agrega únicamente como referencia pero que nosotros no vamos a utilizar.

La estructura base que les debe quedar es la siguiente:

Para los que son nuevos en Net Core vamos a repasar qué es cada cosa:

Program.cs: es el archivo que crea y levanta el Host donde se va a ejecutar el web api
Startup.cs: es la clase de inicialización de la aplicación. En ella se realiza la configuración del servicio/app/web como por ejemplo la configuración de seguridad, de logging, de OpenAPI/Swagger, motor de inyección de dependencias (IOC), etc
appsettings.json: es un archivo de configuración externo y variable por ambiente
Controllers: esta carpeta estarán los controllers que son los puntos de entrada de las URIs/endpoints del API.

Nuestro primer recurso

Para nuestro ejemplo vamos a utilizar el recurso usuarios en donde vamos a poder listar los usuarios existentes, consultar por un usuario en particular y agregar un nuevo usuario.

Lo primero que debemos realizar es crear una clase controller que se llame UsersController ya sea con el IDE o con el generador de código.

$> dotnet aspnet-codegenerator controller -api -async -name UsersController -outDir Controllers

Si ahora vemos el file system o el explorador del IDE vemos que se creó un archivo con la estructura básica de un Controller de Web API.

Dentro del controller comenzamos a agregar la lógica necesaria.

Listado de todos los usuarios

[HttpGet()]
public ActionResult<List<UserDto>> GetAllUsers() 
    => Ok(_userRepository
        .GetAll()
        .Select(x => UserDto.FromModel(x)).ToList());

Obtener un usuario en particular

[HttpGet("{name}")]
public ActionResult<UserDto> GetUser(string name)
{
    var user = _userRepository.Get(name);
    if (user == null)
        return Problem(
            "User not found",
            HttpContext.Request.Path,
            StatusCodes.Status404NotFound,
            "Bad parameters");

    return Ok(UserDto.FromModel(user));
}

Crear un nuevo usuario

[HttpPost()]
public ActionResult<UserDto> AddUser([FromBody] UserDto newUserToCreate)
{
    if (string.IsNullOrEmpty(newUserToCreate.Name))
        return BadRequest(new ProblemDetails()
        {
            Title = "Bad parameters",
            Detail = "The name of the new user cannot be empty or null",
            Instance = HttpContext.Request.Path
        });

    var userAlreadyExists = _userRepository.Exists(newUserToCreate.Name);
    if (userAlreadyExists)
        return Conflict(new ProblemDetails()
        {
            Detail = "User already exists",
            Title = "Bad parameters",
            Instance = HttpContext.Request.Path
        });

    var newUser = new User(newUserToCreate.Name);

    _userRepository.Add(newUser);

    return Created($"/users/{newUserToCreate.Name}", UserDto.FromModel(newUser));
}

Es un ejemplo simple y bastante trivial de una *API, pero podemos ver varios de lo visto en los artículos anteriores:

URI de recurso: el recurso usuario tiene su URI de acceso http://domain.com/api/users. Esto lo provee el Atributte [Route("api/[controller]")] que se encuentra al inicio de la clase.
HTTP Verbs: cada acción sobre el recurso está asociado al verbo HTTP correcto. Los que son de consulta utilizamos GET y el que es de creación POST.
Safe: las acciones sobre el recurso utilizando el verbo GET no genera efectos secundarios sobre el recurso
Idempotencia: Los Get siempre devuelven la misma información ante múltiples peticiones iguales.
Códigos de respuesta: Utilizamos los correctos para cada caso, 200 para request satisfactorio devolviendo los datos solicitados, 201 para cuando se crea un nuevo recurso, 404 para cuando no es encontrado el recurso solicitado y 400 si los datos que vinieron en el request tienen algún problema.
Open API: el scaffold del template ya viene con la implementación básica de OpenAPI/Swagger por lo que la documentación está disponible al ejecutar la aplicación.

Aquí podemos ver la clase completa

[Route("api/[controller]")]
[ApiController]
public class UsersController : ControllerBase
{
    private readonly IUserRepository _userRepository;

    public UsersController(IUserRepository userRepository)
    {
        _userRepository = userRepository;
    }

    [HttpGet()]
    public ActionResult<List<UserDto>> GetAllUsers() 
        => Ok(_userRepository
            .GetAll()
            .Select(x => UserDto.FromModel(x)).ToList());

    [HttpGet("{name}")]
    public ActionResult<UserDto> GetUser(string name)
    {
        var user = _userRepository.Get(name);
        if (user == null)
            return Problem(
                "User not found",
                HttpContext.Request.Path,
                StatusCodes.Status404NotFound,
                "Bad parameters");

        return Ok(UserDto.FromModel(user));
    }

    [HttpPost()]
    public ActionResult<UserDto> AddUser([FromBody] UserDto newUserToCreate)
    {
        if (string.IsNullOrEmpty(newUserToCreate.Name))
            return BadRequest(new ProblemDetails()
            {
                Title = "Bad parameters",
                Detail = "The name of the new user cannot be empty or null",
                Instance = HttpContext.Request.Path
            });

        var userAlreadyExists = _userRepository.Exists(newUserToCreate.Name);
        if (userAlreadyExists)
            return Conflict(new ProblemDetails()
            {
                Detail = "User already exists",
                Title = "Bad parameters",
                Instance = HttpContext.Request.Path
            });

        var newUser = new User(newUserToCreate.Name);

        _userRepository.Add(newUser);

        return Created($"/users/{newUserToCreate.Name}", UserDto.FromModel(newUser));
    }
}

Problem Details

En el API otra cosa que podemos ver es la utilización del estándar de ProblemDetails` para notificar el error producido en la ejecución del request.

Esta manera de comunicar que fue lo sucedido en el API estamos convalidando el principio de Interfaz uniforme que mencionamos anteriormente.

Lo que define este estándar es como un HTTP API debe informar lo sucedido en la aplicación cuando se devuelve un código de error 3xx, 4xx o 5xx.

Por suerte para nosotros Net Core resuelve este tema de manera automática para las excepciones no controladas, parámetros vacíos y demás controles que realiza internamente antes de ejecutar nuestro código del controller, quedando de nuestro lado implementarlo en nuestros métodos.

En el ejemplo del Controller, vemos que hay 2 maneras de implementarlo, una es llamando al método Problems y el 2do es llamado al método del HTTP Status que queremos retornar y pasándole como parámetro una instancia de la clase ProblemDetails. Ambos métodos son igualmente válidos.

Del código también se desprende que no devolvemos directamente el objeto User sino que lo mapeamos a una clase UserDto. Esto es así porque por lo general obtendremos el usuario de una base de datos por medio de Entidades de Negocio. Nunca es una buena práctica devolver una Entidad de Negocio al Frontend, sino devolver un objeto que defina un contrato entre el API y el cliente que realiza el request sin que esté acoplado al negocio.

Felicitaciones!!! 🎉🎉

Ya tenemos nuestro primer API desarrollado. En las próximas entregas iremos agregando poder a nuestro API.

No se olviden de bajar el código de Github y de dejar en los comentarios si quieren que veamos algo en particular en los próximos artículos de la serie.

Creando un API en Net Core - REST API

Andres Lozada Mosto — Tue, 02 Feb 2021 05:01:18 +0000

En el primer artículo de la serie vimos que es un API y cuales son los tipos que hay.

En el presente, vamos a enfocarnos sobre que es un API REST y como podemos diseñarlas.

API REST

Durante la última década (y mucho más también) las API REST fueron el estándar de facto para desarrollar APIs.

REST (REpresentational State Transfer) es un estilo de arquitectura de sistemas distribuidos y no un estándar como lo es SOAP. Esta es la razón por la que no existe una guía estandarizada para su implementación; lo que si hay son principios o limitaciones que definen si un API es REST o no.

Roy Fielding fue la persona que introdujo este concepto por primera vez en su tesis “Architectural Styles and the Design of Network-based Software Architectures” donde define las siguientes restricciones que se deben cumplir para que una arquitectura sea considerada REST:

Arquitectura cliente-servidor (client-server architecture): dos aplicaciones actuando una como cliente la cual solicita recursos a un servidor el cual devuelve una respuesta ante la solicitud del cliente.
Sin estado (stateless): El servidor no guarda un estado entre diferentes solicitudes (request) de un cliente, o sea, cada solicitud es independiente del resto y debe auto-contener la información suficiente para regenerar el estado en cada request.
Cache: debe ser posible almacenar en un caché la respuesta del servidor y poder devolverla en las subsiguientes peticiones (que requieran el mismo recurso) sin necesidad de que llegue el request al servidor nuevamente.
Interfaz uniforme (uniform interface): Incluye cuatro aspectos, identificación de recursos, gestión de recursos a través de representaciones, comunicaciones auto-descriptivas e hipermedia como el motor del estado de la aplicación (HATEOAS).
Sistema de capas (layered system): La solicitud al server puede pasar por diferentes capas donde se puede agregar funcionalidades adicionales como caché, seguridad, balanceo de carga, auditoría, logging, etc.
Código bajo demanda (code on demand): Es un feature opcional y no es necesario que las APIs lo implementen. Esta funcionalidad permite que el server devuelva al cliente código ejecutable

Las APIs que implementan REST se las conoce como API RESTful.

En el último tiempo surgieron especificaciones que intentan darle un marco estandarizado a las API REST. Entre ellas OpenAPI es la más popular. Otra especificación en auge es el RAML.

Diseño de un API REST

Cuando diseñamos un API REST, más allá de la implementación propia del lenguaje de programación que utilicemos, debemos tener en cuenta lo siguiente:

Los principios analizados anteriormente
Las API REST trabajan con "recursos" y no con "servicios/funciones" como en RPC/SOAP y que cada recurso debe poder accederse por un URI en propio (endpoint)
Debemos hacer uso correcto de las bondades del protocolo HTTP, tales como los verbos (GET, POST, PUT, etc), los códigos de estado (404, 500, 200, etc) y las cabeceras (headers).

Por ejemplo, tomemos el recurso Usuario llamado Andres, debe tener asociada una URI http://domain.com/users/andres y para su obtención se utiliza el método GET, para su creación POST.

Otro ejemplo es la información de una reunión http://domain.com/meetings/2354.

Tanto el recurso “andres” como el recurso “meeting 2354” siempre refieren al mismo recurso y es esperable que ante subsecuentes solicitudes siempre devuelva la misma información (la cual se puede cachear).

Ejemplos no validos:

Verbos HTTP (HTTP verbs)

El protocolo HTTP define un conjunto de acciones a realizar sobre un recurso tales como su creación, su borrado o actualización.
Estas acciones (HTTP verbs) juegan un rol importante en el constraint de Uniform Interface que vimos anteriormente.

Verbo HTTP	Operación	Descripción
GET	Read	Solicita uno o una colección de recursos
POST	Create	Crea un recurso con la información enviada en el cuerpo (body) del request
PUT	Update/Replace	Actualiza un recurso preexistente o lo reemplaza. Podría también crearlo
PATCH	Update/Modify	Similar a PUT, se utiliza para actualizar de manera parcial un recurso
DELETE	Delete	Elimina un recurso
HEAD	Read	Similar a GET, pero el server solo retorna los encabezados (headers) y no el cuerpo (body) de la respuesta
OPTIONS	ASK	El servidor retorna el listado de verbos HTTP permitidos para el recurso
TRACE	ALL	Solicita al servidor que agregue en la respuesta los datos recibidos para depuración

Los verbos GET, HEAD, OPTIONS y TRACE son considerados seguros por definición por lo que no deben generar un impacto en el/los recursos indicados en la petición (ni generar por ejemplo transacciones que generen un cambio de estado en el servidor) más allá de agregar logging, update de caché, entre otros recursos aledaños pero nunca sobre el recurso indicado en el URI.

Por otro lado, muchos de estos verbos HTTP tienden a ser idempotentes (aunque no es una restricción si es esperable). Los verbos PUT, DELETE, GET, HEAD, OPTIONS y TRACE deben devolver siempre la misma información ante subsecuentes requests. No así para el verbo POST donde cada request igual puede generar efectos secundarios tal vez no deseados.

Código de estados (HTTP Status codes)

Los datos que retorna el servidor a partir de un request siempre son acompañados por un código de estado de HTTP que indica el resultado del request.

HTTP define un conjunto predefinidos que se agrupan en:

1xx: los códigos dentro de este rango son informativos
2xx: los encontrados en este rango indican que la solicitud fue exitosa
3xx: este grupo de códigos indican que se debe hacer o hubo una redirección
4xx: los códigos dentro de este grupo indican diferentes errores del cliente
5xx: estos códigos indican que se produjo un error en el servidor

Muchos de estos códigos son devueltos por la infraestructura o por el framework que utilicemos para crear nuestra API, mientras que nosotros como devs vamos a utilizar otros (y en algunos casos los mismos) para indicar que sucedió con la solicitud que estamos tratando.

Los códigos más utilizados son:

200 (OK): solicitud exitosa y retorno del recurso
201 (Created): recurso creado exitosamente y retorna el URI al recurso
401 (Unauthorized): sin autorización para el recurso
403 (Forbidden):
404 (Not Found): recurso no encontrado/inexistente
409 (Conflict): conflicto en la creación/update del recurso
500 (Internal Server Error): error no manejado en el código de la aplicación, por ejemplo una excepción sin un catch.

No comments sobre esta imagen 🤣

Encabezados (HTTP Headers)

Los Headers es información adicional que se intercambia entre el cliente y el servidor (Request/Response). Por ejemplo:

Información sobre los datos enviados en el Request/Response
Información de Autenticación
Información sobre Caching
Información sobre Cookies

Algunos Headers tienen dirección cliente al servidor (ej: Authentication), otros tienen significado del servidor al cliente (ej: Location) y por último algunos se utilizan indistintamente (ej: _Content-Length).

Entre los mas comunes podemos mencionar

Header	Descripción
Authorization	Método e información para la autenticación en el servidor del recurso
Cache-Control	Método de cache para el recurso
Accept	Informa sobre el formato aceptado por el cliente
Accept-Language	Lenguaje esperado por el cliente para los datos que recibe del server
Cookie	Cookies recibidas por el server
Origin	Indica desde donde se origino el request
Content-Length	Tamaño del payload
Content-Type	Indica el Media Type del payload

Bien ya aprendimos algo sobre las API REST es hora de comenzar a meter mano un algo de código, somos devs, no?

Bueno, preparate un 🧉/☕ + 🥐🍩 que en el próximo vamos directo a tirar magia 💪

Creando un API en Net Core - Intro

Andres Lozada Mosto — Tue, 02 Feb 2021 04:59:53 +0000

Hace tiempo que no publicaba nada y me pareció una buena idea repasar a que estamos llamando API y más precisamente a un API REST. Cuáles son las consideraciones que debemos tener en cuenta al momento de crearla y finalmente cuáles son las herramientas que Net Core nos provee para desarrollarla.

El objetivo principal de este grupo de artículos es para los desarrolladores que recién están dando sus primeros pasos puedan comprender de una manera simple y directa que es un API y cómo hacer una implementación completa utilizando Net Core. Desarrolladores más experimentados pueden tomar esto como una guía/checklist o mejor aún ayudarme con posibles olvidos, correcciones o lo que deseen aportar para ayudar a los que recién comienzan 💪🤙

¿Qué es un API?

Antes de comenzar a tirar código como bien techies que somos sentemos una base sobre lo que entendemos que es un API.

API: Interfaz de programación de aplicaciones o bien en inglés Application programming interface.

Ya solo con el nombre nos está dando una pista, es un interfaz para interactuar con componentes de un software sin necesidad de conocer su implementación concreta. Entonces, es una abstracción para el desarrollador que utiliza el API. Toda API provee un contrato donde estipula la forma en que se la puede utilizar.

¿Dónde podemos ver ejemplos de APIs?

Hay muchos ejemplos de APIs, veamos algunos:

Net Core y C# proveen un API con el cual desarrollamos las aplicaciones
Google Maps nos provee un API con el cual podemos insertar su mapa en nuestra aplicación
Hay APIs web públicas para por ejemplo obtener el clima de una ciudad o realizar conversiones de moneda e integrarlas en nuestras aplicaciones
Amazon, eBay o Mercado Libre proveen un API público de búsqueda para su catálogo
Los sistemas operativos proveen APIs para que sus componentes internos puedan interactuar
Kubernetes provee un API para su administración

Como se puede ver, hay muchos tipos de APIs. Algunas son internas (como por ejemplo las del SOs o Net Core) y otras son para consumirlas remotamente (por ejemplo el API de clima). Son estas últimas las que nos vamos a estar enfocando en estos artículos y son las que comúnmente los desarrolladores les llamamos API en el sentido amplio de la palabra.

Pregunta para conversar en los comentarios: El tablero del auto ¿es el API del vehículo hacia el conductor? 🤔

APIs Remotas

Hablamos que lo que nos interesa son las APIs remotas, excelente. Una API remota requiere que 2 puntos no conectados de manera directa necesiten comunicarse y el medio utilizado es la red (Internet). El caso más visible es el de Gmail donde el Frontend que se ejecuta en el browser local de nuestra PC llama a una API remota localizada en los servidores en Google para buscar los emails. Se puede extender a comunicación entre sistemas y aplicaciones de cualquier índole diferentes que pertenezcan o no a una misma empresa.

Lo más común o la norma general es que la comunicación que mencionamos en el párrafo anterior (o llamadas a las APIs) se realice por medio del protocolo HTTP/HTTPs y podemos dividirlos de la siguiente manera:

RPC (Remote Procedure Call), es la ejecución de una función de un proceso en una máquina de la red interna o de internet. Por lo general su forma de comunicación es binaria y existe desde antes del auge de Internet. Como variantes aparecieron XML-RPC y JSON-RPC. En los últimos años tomó mucho auge GRPC que convierte RPC a web nativo.
SOAP (Simple Object Access Protocol), donde la comunicación está predefinida por medio de XML estándar y es la base de las arquitecturas SOA
REST (REpresentational State Transfer), donde la comunicación se basa en HTTP y utiliza todos sus features para generar las APIs

Estas últimas, en específico, son las que nos vamos a enfocar. Cuando los devs hablan de APIs generalizamos la palabra a este tipo de API.

Pregunta para conversar en los comentarios: Cuando usamos el control remoto de la TV y cambiamos de canal. ¿Estamos llamando a una API remota? 🤔

Este artículo solo fue la introducción al mundo de las API.

Te invito a dejar tu comentario sobre las preguntas que aparecieron a lo largo del artículo y vamos conversando entre todos 😀💪

Moq and how creating Mocks with Linq

Andres Lozada Mosto — Thu, 22 Oct 2020 14:17:26 +0000

There is a not so known feature in Moq library and is the possibility to create our Mocks with Linq.

Benefit to use Linq to create our mocks:

Remove boilerplate code
Removing Setup()call for each member we want configurate
Remove calling .Object when we use the object mocked
We still able to Verify our mocks

So, let’s see an example 😎

Simple & hierarchy/recursive properties

var id = 32;
var username = "Andres";
var street = "14th Street NW";

var userModel = Mock.Of<IUserModel>(user =>
    user.Id == id &&
    user.Username == username &&
    user.Address.Street == street
);

Methods with any parameter matching

var userModel = Mock.Of<IUserModel>();
var userList = Fixture
    .Build<UserModel>()
    .With(x => x.Address, Fixture.Create<Address>())
    .CreateMany(10).ToList<IUserModel>();

var repository = Mock.Of<IRepository>(x =>
    x.Add(It.IsAny<IUserModel>()) == true &&
    x.Add(userModel) == false &&
    x.ActiveUsers() == userList
);

Verify methods

var userAdded = repository.Add(Mock.Of<IUserModel>());

var mock = Mock.Get(repository);

mock.Verify(user => user.Add(It.IsAny<IUserModel>()), Times.Once);

What do you think? will you start using Linq to write your Mocks?

Fell free to share your thoughts on the comments 😎 💪

Moq vs NSubstitute - Who is the winner?

Andres Lozada Mosto — Fri, 16 Oct 2020 16:31:32 +0000

In this article will compare two of most important mocking libraries for .Net (.Net Core and .Net Framework) NSubstitute and Moq.

What will we compare?

Simplicity
Readability
Behaviours

The fight begins 💪

Mock creation

Moq

var mock = new Mock<IRepository>();

NSubstitute

var mock = Substitute.For<IRepository>();

Moq uses a more representative notation. Anyone, just reading that line can know that we are creating a mock object.

Winner: Moq

Mocking properties

Moq

// Simple properties
mock.Setup(foo => foo.Users).Returns(userList);

// Hierarchy
mockUser.Setup(foo => foo.Address.Street).Returns(street);

NSubstitute

// Simple properties
mock.Users.Returns(userList);

// Hierarchy
mockUser.Address.Street.Returns(street);

NSubstitue has a simpler interface to set up the returns.

Winner: NSubstitue

Mocking methods

Moq

// Without parameters
mock.Setup(x => x.ActiveUsers()).Returns(userList);

// Matching by value
mock.Setup(x => x.SearchById(1)).Returns(user);

// Matching by any value of the parameter type
mock.Setup(x => x.SearchById(It.IsAny<int>())).Returns(user);

// Matching by custom logic
mock.Setup(x => x.SearchById(It.Is<int>(i => i < 10))).Returns(user);

NSubstitute

// Without parameters
mock.ActiveUsers().Returns(userList);

// Matching by value
mock.SearchById(1).Returns(user);

// Matching by any value of the parameter type
mock.SearchById(Arg.Any<int>()).Returns(user);

// Matching by custom logic
mock.SearchById(Arg.Is<int>(i => i < 10)).Returns(user);

Same here, NSubstitute has a simpler interface to set up the returns of the methods mocked.

Winner: NSubstitue

Matching arguments

Moq

// - It.IsAny<int>())
// - It.IsInRange(0, 10, Range.Inclusive) 
// - It.IsIn(Enumerable.Range(1, 5))
// - It.IsNotIn(Enumerable.Range(1, 5))
// - It.IsNotNull<string>())
// - It.IsRegex("abc"))
// - It.Is<int>(i => i < 10))
// - mock.Setup(x => x.Search(IsLarge())) //< custom

NSubstitute

// - Arg.Any<int>())
// - Arg.Is<int>(i => i < 10))

Moq provide us a lot more built-in options for matching arguments

Winner: Moq

Capturing parameter

Moq

mock.Setup(x => x.Add(It.IsAny<IUserModel>())).Returns((IUserModel user) => user.Username == "Andres");

NSubstitute

mock.Add(Arg.Any<IUserModel>()).Returns(x => { return ((IUserModel)x[0]).Username == "Andres"; });

With Moq, it is easier to get the arguments values before returning the mocked value and process them as needed.

Winner: Moq

Multiple matching

Moq

mock.Setup(x => x.SearchById(It.IsAny<int>())).Returns((int i) => userList.Skip(1).Take(1).First());
mock.Setup(x => x.SearchById(2)).Returns((int i) => userList.First());

NSubstitute

mock.SearchById(Arg.Any<int>()).Returns(userList.Skip(1).Take(1).First());
mock.SearchById(2).Returns(userList.First());

Both of them allow us to add as many match expressions that we need. If there is a conflict they will take the last expression that matches.

Winner: Tie

Callabacks

Moq

mock.Setup(x => x.SearchById(1))
                .Callback((int x) => parameterValue = x)
                .Returns(userList.First());

// Methods without return
mock.Setup(x => x.Save()).Callback(() => name = "aa");

// before and after
mock.Setup(x => x.SearchById(2))
                .Callback<int>(x => parameterValue = x)
                .Returns(userList.First())
                .Callback<int>(x => name = "andres");

NSubstitute

mock.SearchById(1)
                .ReturnsForAnyArgs(x =>
                {
                    parameterValue = (int)x[0];
                    return userList.First();
                });

// Methods without return
mock.When(x => x.Save())
                .Do(x => name = "aa");


// before and after
mock.SearchById(2)
               .ReturnsForAnyArgs(x =>
               {
                   parameterValue = (int)x[0];
                   return userList.First();
               })
               .AndDoes(x => name = "andres");

In this case Moq* provides a more readable experience adding a function called “Callback” on the chain call.

Winner: Moq

Multi-returns

Moq

mock.SetupSequence(x => x.Users)
                .Returns(users1)
                .Returns(users2)
                .Returns(users3);

NSubstitute

mock.Search(Arg.Any<string>()).Returns(users1, users2, users3);

Here both libraries are very similar right?.

Winner: Tie

Throwing Exceptions

Moq

mock.Setup(x => x.Save()).Throws<Exception>();
mock.Setup(x => x.Save()).Throws(new Exception("msj"));

NSubstitute

mock.ActiveUsers().Returns(x => { throw new Exception(); });
mock.When(x => x.Save())
                .Do(x => { throw new Exception("msj"); });

Moq is easier to recognize that the function will throw an exception.

Winner: Moq

Verify

Moq

// Setter
mock.VerifySet(x => x.Users = users);

// Getter
mock.VerifyGet(x => x.Users);

// Methods with matchting
mock.Verify(x => x.Search(It.IsAny<string>()));
mock.Verify(x => x.Search("aaa"), Times.Never());

// Occurrences
// - Times.Never
// - Times.Once
// - Times.AtLeastOnce
// - Times.AtMost(2)
// - Times.Exactly(2)

NSubstitute

// Setter
mock.Received().Users;

// Getter
mock.Received().Users = users;

// Methods with matchting
mock.Received().Search("aa");
mock.DidNotReceive().Search("aaa");
mock.Received(2).Search("bb");

// Occurrences
// Nop

NSubsitute has a simple way to verify that a method was called but Moq has more options to test how many times the method was executed.

Winner: Moq

Matching Generic Type Arguments

Moq

mock.Setup(m => m.AddUser(It.IsAny<It.IsSubtype<IUserModel>>())).Returns(true);
mock.Setup(m => m.AddUser(It.IsAny<UserModel2>())).Returns(false);

NSubstitute

mock.AddUser<IUserModel>(Arg.Any<IUserModel>()).Returns(true);
mock.AddUser<IUserModel>(Arg.Any<UserModel2>()).Returns(false);

Again, both provide an easy way to mock Generic Methods

Winner: tie

Well, how is it going? Who is winning?
Let’s see the current score

Syntax	Moq	NSubstitute
Mock creation	✅
Mocking properties		✅
Mocking methods		✅
Matching arguments	✅
Multiple matching	tie	tie
Callabacks	✅
Multi-returns	tie	tie
Throwing Exceptions	✅
Verify	✅
Matching Generic Type Arguments	tie	tie

Moq is the winner!! 😀 🎉

I really prefer Moq and I try to use it always but both are excellent options to use. Us, as developers, we should be able to work with both.

You can download the examples from my Github
https://github.com/andreslozadamosto/net-thoughts/tree/master/libraries/testing/MoqVsNSubstitute/MockingLibrariesExamples

Are you with me?
Do you prefer NSubstitue?
I forget to compare any behaviour?

Share your comments 🤙👇

Kafka + Docker + Net Core 101 - Part 1

Andres Lozada Mosto — Mon, 21 Sep 2020 15:38:15 +0000

If you are here, you know what we are talking about and you want to get your hands dirty as soon as possible, so this post is for you 😀.

If you are not familiar with Kafka or you are not sure about what it's used for, you can visit these links.

Apache Kafka in Depth. In the era of Big Data, lots and lots… | by Sonu Sharma | Medium

Sonu Sharma ・ Jul 24, 2019 ・ 9 min read
Medium

Kafka For Beginners. What is Kafka? | by Rinu Gour | Medium

Rinu Gour ・ Sep 12, 2018 ・ 9 min read
Medium

Ok, we already know what Kafka can be used for, so let's try to run it locally, test basic commands, and create a basic app to publish events and another one to use them using Net Core.

Kafka + Docker

In order to set up our environment, we create a Docker Compose file where we will instantiate a Zookeeper service and a Kafka service (you can then set up additional ones and build the clusters).

The base images we are going to use are the ones from our Confluence friends.
This is not the only option, you can also use the images from Bitmani|Zookeeper, Bitmani|Kafka, Spotify or Wurstmeister.

Our docker-compose file results as follows:

version: '2'
services:
    zookeeper:
        image: confluentinc/cp-zookeeper:latest
        environment:
            ZOOKEEPER_CLIENT_PORT: 2181
            ZOOKEEPER_TICK_TIME: 2000
    kafka:
        image: confluentinc/cp-kafka:latest
        depends_on:
            - zookeeper
        ports:
            - 9092:9092
        environment:
            KAFKA_BROKER_ID: 1
            KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
            KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:29092,PLAINTEXT_HOST://127.0.0.1:9092
            KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
            KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
            KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1

Important: To access Kafka from outside of the container, you must replace the localhost at ADVERTISED with the Docker-Machine IP.

Setting up the environment with Docker Tools (Windows)

Once a docker compose file is created we can set our environment.

Let's open the docker console and create a new Docker Machine running this command:

docker-machine create --driver virtualbox confluent

We are going to use the VirtualBox driver to create the host virtual machine and we will call it confluent (we can use any name, however)

If we use Linux or Windows Professional onwards, we can skip this option and go straight to the docker-compose up. However, for those who use Windows 10 Home or older versions with Docker Toolbox, this is a step that we must do to have it running the same way.

Let's check that Docker Machine has been created.

docker-machine ls

We should see something like this:

Next, we have to go to the docker machine that we have just created so that the commands can be executed on it (otherwise it will be done on the default)

eval $(docker-machine env confluent)

We get the IP so we will be able to connect from C# and use it through the environment variable KAFKA_ADVERTISED_LISTENERS from the docker compose file.

docker-machine ip confluent

Finally, we run docker-compose in the folder where the file yaml was saved.

docker-compose up -d

We check that Kafka and Zookeeper are up and running.

docker container ps

Setting up the environment on Linux or Docker for Windows

We simply run Docker Compose

docker-compose up -d

If you are using WSL, you can get the IP in this way:

wsl ip -a

With this tiny configuration, we get Kafka ready to the first testings, let's go!

Let's have fun with Kafka

By default, Kafka comes with scripts to create topics, publish/read messages, etc. During this part we will see how to work with them.

Create a new topic

docker container exec <kafka-container-id> kafka-topics \
--create \
--topic foo \
--partitions 1 \
--replication-factor 1 \
--if-not-exists \
--zookeeper zookeeper:2181

We create a new Topic in Kafka with a replication factor of 1 and with only one partition. If we wanted to increase these values we should build up other Kafka instances.
The parameter --if-not-exists indicates that the topic will be created if it doesn't previously exist.

List the topics

docker container exec <kafka-container-id> kafka-topics \
--list \
--zookeeper zookeeper:2181

This command will list only the names of the Topics we have already created.

See a topic’s description

docker container exec <kafka-container-id> kafka-topics \
--describe \
--topic foo \
--zookeeper zookeeper:2181

It shows relevant information about the topic.

Publish a message to the topic

In this case it is better to open your Kafka’s container console, and execute the Producer from there.

docker container exec -it <kafka-container-id> /bin/bash

Now we execute the Publisher.

kafka-console-producer \
--request-required-acks 1 \
--broker-list <docker-machine-ip>:9092 \
--topic foo

Then, for each line we write (separated by a line break), a message will be sent (we use [CTRL+C] to exit the command and Exit to exit the container).

Read from a topic

docker container exec <kafka-container-id> kafka-console-consumer \
--bootstrap-server <docker-machine-ip>:9092 \
--topic foo \
--zookeeper  zookeeper:2181

These are the basics to get started and run the first tests. Each command has multiple parameters worth investigating in order to make the most of it.

For further details, you can check the official docs.

C# knows Kafka

We already have Kafka executing on our PC, now let’s take a look at how to publish and read messages from a Topic.

Producer

We create a console application, and we use the following code to replace the code you will find in Docker-Machine.

We compile and execute, indicating the name of the topic we want to send messages to. The application keeps waiting for our input. Each message should be written in a different line.

dotnet build
.
.
.
dotnet run foo

Consumer

For the Consumer, we create a new console application and we replace the IP value for the IP value of the Docker-Machine we are using.

We compile and run, indicating which Topic we want to listen to.

dotnet build
.
.
.
dotnet run foo

While executing both programs and displaying one console next to the other, we can see that, whenever we publish a message, the listening console displays it.

You can download the source code from here.

Kafka tools

The universe of Kafka tools is immense, and in these lists you can find lots of resources:

There are several tools for using Kafka via UI instead of the command line:

There are other choices out there…

Among the ones I tried, Conduktor seems complete enough, despite the free version having some limitations. The good thing is that it includes integration to connect to Confluent and Aiven, in order to use their Kafka SaaS platforms.

Closing up

Kafka is a monster that provides us with a whole new universe of possibilities to extend our architecture in unthinkable ways, but we should not be afraid to get started.

We have seen that with little work (thanks to the people who created Docker images) we can setup everything we need to have Kafka up and running on Docker on our PC, and how easy it is to communicate with it from C#.

In the future releases of this series of articles we will take a look to how can we continue digging further into it.

🧉 + 🥐🥐 = Happy coder 💻

Pursuit of happiness - oh my Windows terminal

Andres Lozada Mosto — Mon, 21 Sep 2020 15:03:21 +0000

What do you think if I tell you that your PowerShell can look like this? It's pretty right? 😍 🤩

After reading this post, you'll get this beautiful console that you'll love to work with. And not only on PowerShell, but on WSL and Azure Cloud Shell too!! 🥳 🤟

Terminal alternatives

There are more options than the Windows Command Line (CMD) or Windows PowerShell. While they are mostly emulators that run on the terminal, they add good features and look better than the default consoles.

Alternatives over there:

CMDer
ConEmu
Windows Terminal
Hyper
Alacritty
Terminator (running over WSL)
Fluent Terminal I just found it and looks great

I like to keep my dev environment simple so my choice is the new Windows Terminal using PowerShell Core.

Why Windows Terminal? Microsoft listened to the community and created a totally brand new terminal which is really easy to use, have a lot of cool features like tabs, panes and it can run PowerShell, CMD, Git bash, Linux bash, Azure Cloud Shell as well as any other.

The Windows terminal is relatively new. Previously I worked for many years with ConEmu and I can say that it is a very good option too

I encourage you to test all these alternatives and find which one fit best with you.

This article is based on Windows Terminal, but the configuration can be applied to the other tools as well.

Installation

Let's see what we need to install to convert our boring terminal to an awesome one.

Posh-Git (git extension)
Oh-My-Posh (themes)
Get-ChildItemColor (colorized sub-commands)
Power Fonts (techie fonts)

Many of these should be installed using PowerShell with admin rights.

Well, let's start 💪 💻

Changing the ExecutionPolicy

NOTE: this steps should be executed on PowerShell and PowerShell Core if you want to have the same theme on both.

So, we open the PowerShell as Admin and change the ExecutionPolicy to RemoteSigned



Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Confirm

When you are done, you can go back to the previous configuration by updating the ExecutionPolicy with scope Process.

Installing what we need



PowerShellGet\Install-Module posh-git -Scope CurrentUser -Force
Install-Module oh-my-posh -Scope CurrentUser
Install-Module -AllowClobber Get-ChildItemColor

If you are using PowerShell Core you have to install PSReadLine.



Install-Module -Name PSReadLine -Scope CurrentUser -Force -SkipPublisherCheck

To allow Power Fonts on our system we should clone the Github repository and run.



.\install.ps1

Tip: the repo has a lot of fonts, so in my case I deleted all of them except the one called Meslo Dotted.

Allowing all this stuff

In order to have all the modules installed every time we open the terminal, first we need to update our profile file.



code $profile

And add these lines to it



# Modules import
Import-Module posh-git
Import-Module oh-my-posh
Import-Module Get-ChildItemColor

# Theme to use
Set-Theme Agnoster

Now, we need to tell Windows Terminal to use our selected font. To do so, open the Settings file

We search for the "profile" property and update it with the following.



…..   
"profiles": {
   "defaults": {
     "fontFace": "Meslo LG M DZ for Powerline",
     "fontSize": 8,
     "colorScheme" : "One Half Dark"
  },
   "list": [
    {
       // Make changes here to the powershell.exe profile
       "guid": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
       "name": "Windows PowerShell",
       "commandline": "powershell.exe",
       "hidden": false
    }
    .....

If you are using ConEmu o CMDER go to the Settings Fonts and select the Font previously installed.

NOTE: This changes will be reflected on the Visual Studio Code Terminal too 😉

Extending this to WSL

The magic of WSL is that we can use many flavours of Linux directly on Windows, removing any need of double-boot or VMs. Even so, its bash is still boring! so let's see how we can have the same here.

The natural option is to install PowerShell Core on the distro and set it as default bash, in order to follow the same steps as previously.

But, we are on Linux, where there are many alternatives and a good one is ZSH.

Installation

First we'll update our Linux version



sudo apt-get update
sudo apt-get upgrade

Now we can install everything we need



sudo apt-get install git
sudo apt-get install zsh

We make ZSH our default



chsh -s /bin/zsh

Update the .bashrc file by adding this at the beginning of it.



if test -t 1; then
exec zsh
Fi

Install Oh-My-Zsh



sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

We select the theme from the ./zshrc file.



code $HOME/.zshrc

Search for “ZSH_THEME” property and change it for one you like



ZSH_THEME="norm"

The last step is to install the plugin zsh-dircolors-solarized by cloning the repo



git clone --recursive git://github.com/joel-porquet/zsh-dircolors-solarized $ZSH_CUSTOM/plugins/zsh-dircolors-solarized

Then go back to the .zshrc file and grant permissions to the pluging



plugins=(zsh-dircolors-solarized)

Finally select the theme for the plugin



setupsolarized dircolors.ansi-dark

The result…

Extending this to Azure Cloud Shell

I didn't try to set up all these things on Azure Cloud Shell, but it's based on Linux - so you can install ZSH and set it up as we did! Here it's explained (https://www.danielstechblog.io/setting-up-zsh-with-oh-my-zsh-in-azure-cloud-shell/)[https://www.danielstechblog.io/setting-up-zsh-with-oh-my-zsh-in-azure-cloud-shell/]

🧉 + 🥐🥐 = Happy coder 💻

Kafka + Docker + Net Core 101 - parte 1

Andres Lozada Mosto — Wed, 10 Jun 2020 21:33:52 +0000

Updates

20/07/2020: Actualizado para May 2020 Windows Update y Docker Desktop sobre WSL2.

Si llegaste hasta este lugar es que ya sabes de lo que estamos hablando y quieres meter manos en el código de forma inmediata entonces esta serie de artículos es para vos 😀

Si aún no tienes bien en claro qué es Kafka y para que se lo puede usar puedes pasarte por estos lados:

Apache Kafka in Depth. In the era of Big Data, lots and lots… | by Sonu Sharma | Medium

Sonu Sharma ・ Jul 24, 2019 ・ 9 min read
Medium

Kafka For Beginners. What is Kafka? | by Rinu Gour | Medium

Rinu Gour ・ Sep 12, 2018 ・ 9 min read
Medium

Bueno, ahora ya sabemos para que podemos usar Kafka tratemos de correrlo localmente en nuestra PC, probar comandos básicos y crear una aplicación básica que publique eventos y otra que los consuma utilizando Net Core.

Kafka + Docker

Para levantar nuestro ambiente creamos un archivo de Docker Compose donde instanciaremos un servicio de Zookeeper y un servicio de Kafka (luego se pueden levantar mas y armar los clusters).

Las imágenes base que vamos a utilizar son las de los amigos de Confluence. No son las únicas, también podemos usar las de Bitmani|Zookeeper, Bitmani|Kafka, Spotify o Wurstmeister.

Nuestro docker-compose file nos queda de esta forma:

version: '2'
services:
    zookeeper:
        image: confluentinc/cp-zookeeper:latest
        environment:
            ZOOKEEPER_CLIENT_PORT: 2181
            ZOOKEEPER_TICK_TIME: 2000
    kafka:
        image: confluentinc/cp-kafka:latest
        depends_on:
            - zookeeper
        ports:
            - 9092:9092
        environment:
            KAFKA_BROKER_ID: 1
            KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
            KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:29092,PLAINTEXT_HOST://127.0.0.1:9092
            KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
            KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
            KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1

Imporatante: Para acceder a Kafka desde fuera del container se debe reeamplazar localhost en ADVERTISED por el IP del Docker-Machine.

Levantando el ambiente con Docker Tools (windows)

Abrimos la consola de docker y creamos una nueva Docker Machine ejecutando el siguiente comando

docker-machine create --driver virtualbox confluent

Indicamos que vamos a utilizar el driver de VirtualBox para crear la máquina virtual del host y la llamaremos confluent (podemos usar cualquier nombre)

Si usamos Linux o Windows Profesional en adelante, podemos saltarnos esta opción e ir directamente al docker-compose up, pero para quienes usamos Windows 10 Home o versiones mas antiguas con Docker Toolbox es un paso que necesitamos hacer para tener una experiencia similar.

Revisamos que se haya creado

docker-machine ls

Debemos ver algo similar a esto

Lo siguiente a realizar es entrar a la docker machine que acabamos de crear para que los comandos se ejecuten sobre ella (sino se haría sobre la default)

eval $(docker-machine env confluent)

Obtenemos el IP para luego poder conectarnos desde C# y para usarla en la variable de entorno KAFKA_ADVERTISED_LISTENERS del archivo de docker compose

docker-machine ip confluent

Por último, corremos docker-compose en la carpeta donde hayamos puesto el archivo yaml

docker-compose up -d

Verificamos que se encuentren Kafka y Zookeeper levantados

docker container ps

Levantando el ambiente en Linux o con Docker for Windows

Simplemente corremos Docker Compose

docker-compose up -d

Si estas usando WSL puedes obtener el IP de la siguiente forma

wsl ip -a

Con esta mínima configuración tenemos Kafka listo para las primeras pruebas, let's go! 💪😀

Divirtámonos con Kafka

Por default, Kafka viene con scrips para crear topics, publicar/leer mensajes, etc. Durante esta parte, vamos a ver como trabajar con ellos

Crear un topic nuevo

docker container exec <kafka-container-id> kafka-topics \
--create \
--topic foo \
--partitions 1 \
--replication-factor 1 \
--if-not-exists \
--zookeeper zookeeper:2181

Creamos un nuevo Topic en Kafka con una factor de replicación de 1 y con una sola partición. Si quisiéramos aumentar estos valores debemos levantar otras instancias de Kafka.
El parámetro --if-not-exists indica que el topic se creará si no existe previamente.

Listar los topics

docker container exec <kafka-container-id> kafka-topics \
--list \
--zookeeper zookeeper:2181

Este comando va a listar únicamente los nombres de los Topics que tenemos creados

Ver la descripción de un topic

docker container exec <kafka-container-id> kafka-topics \
--describe \
--topic foo \
--zookeeper zookeeper:2181

Nos muestra información relevante del Topic

Publicar un mensaje al topic

En este caso es mejor ingresar a la consola del container de Kafka y ejecutar el Producer desde allí

docker container exec -it <kafka-container-id> /bin/bash

Ahora ejecutamos el Publisher

kafka-console-producer \
--request-required-acks 1 \
--broker-list <docker-machine-ip>:9092 \
--topic foo

Luego por cada línea que escribamos (separadas por un [Enter]) se enviará un mensaje (usamos [ctrl+c] para salir del comando y exit para salir del container).

Leer de un topic

docker container exec <kafka-container-id> kafka-console-consumer \
--bootstrap-server <docker-machine-ip>:9092 \
--topic foo \
--zookeeper  zookeeper:2181

Estos son los básicos para comenzar y hacer las primeras pruebas. Cada uno tiene múltiples parámetros a investigar y sacar mayor provecho.
Para un major detalle pueden ir a la docu oficial.

C# conoce Kafka

Ya tenemos Kafka ejecutándose en nuestro PC, ahora veremos como publicar y leer mensajes en un Topic.

Producer
Creamos una aplicación de consola y usamos el siguiente código reemplazando el por el que tiene el Docker-Machine.

Compilamos y ejecutamos indicando el nombre del topic al cual enviaremos mensajes. La aplicación queda a la espera de que escribamos mensajes uno por línea.

dotnet build
.
.
.
dotnet run foo

Consumer
Para el Consumer, creamos una nueva aplicación de consola y usamos el siguiente código reemplazando el valor de por el IP del Docker-Machine que estamos usando.

Compilamos y corremos indicando que Topic queremos escuchar

dotnet build
.
.
.
dotnet run foo

Ejecutando ambos programas en la consola una al lado de la otra, podremos ver que cuando publicamos un mensaje, éste aparece en la otra.

Pueden bajarse el código desde acá

Kafka tools

El universo de Tools de Kafka es inmenso y en estos listados se puede encontrar de todo:

Hay varias herramientas para manejar Kafka por medio de UI y no por comandos

Hay otros dando vueltas por ahí...

Entre los que probe, Conduktor parece bastante completo aunque la version free tiene sus limitantes. Lo bueno es que tiene integración para conectarse a Confluent y Aiven para usar sus plataformas SaaS de Kafka

Cerrando

Kafka es un monstruo que nos provee un nuevo universo de posibilidades para extender nuestras arquitecturas de maneras impensadas pero no hay que tenerle miedo para comenzar.

Vimos que con muy poco (gracias a los que crearon las imágenes de docker) se puede tener todo lo necesario para tener a Kafka corriendo sobre docker en nuestra PC y lo fácil que es comunicarse desde C#.

En las futuras entradas de esta serie de artículos iremos viendo como ir avanzando un poco más.

🧉 + 🥐🥐 = Happy coder 💻