Creando una aplicación .NET completa con Lino: guía paso a paso

Instalación y configuración de Lino CLI

El primer paso para empezar a trabajar con el Lino CLI es instalar la herramienta en su entorno de desarrollo. Se distribuye como una dotnet global tool, lo que significa que estará disponible para cualquier proyecto .NET en su computadora. Antes de instalar, confirme que el SDK de .NET requerido por los templates actuales esté disponible, que la terminal pueda ejecutar dotnet y que el directorio de herramientas globales de .NET esté en el PATH.

Paso 1: instalación

Para instalar (o actualizar) Lino CLI, ejecute el siguiente comando en la terminal:

dotnet tool install --global Tolitech.Lino

Notas importantes:

• Si ya hay una versión instalada, puede usar dotnet tool update --global Tolitech.Lino para actualizar.
• Verifique que el directorio de herramientas globales de .NET esté en el PATH del sistema para que el comando lino funcione correctamente.

Paso 2: configurar el idioma

Después de la instalación, se recomienda configurar el idioma (o cultura) que CLI utilizará en mensajes, prompts y logs:

lino preferences culture set

Se le pedirá que elija entre los idiomas disponibles. Esta configuración garantiza que todas las instrucciones y mensajes aparezcan de forma coherente en el idioma deseado. Esta preferencia cambia los mensajes, prompts y orientaciones localizadas del CLI; no renombra entidades, servicios, módulos o términos de negocio generados en el proyecto.

Paso 3: Autenticación y registro

Para acceder a todos los recursos de Lino, incluidos templates avanzados, la publicación de imágenes Docker y las integraciones con servicios externos, es necesario estar autenticado.

- Si aún no posee registro, regístrese con el comando:

lino user register

- Si ya tiene registro, haga login con:

lino auth login

Lo que sucede: el CLI almacena un token de autenticación localmente, lo que le permite ejecutar comandos que requieren acceso a recursos protegidos sin tener que iniciar sesión en cada uso. Mantenga este token privado y evite compartir el mismo perfil de usuario entre diferentes desarrolladores, agentes de CI o máquinas.

Paso 4: Verificación

Para confirmar que la instalación y la autenticación fueron exitosas, ejecute:

lino --version

Si el comando devuelve la versión instalada, está listo para comenzar a usar el Lino CLI en sus proyectos.

Crear el proyecto MyApp

En este paso, crearemos la estructura inicial del proyecto utilizando el Lino CLI. Este proyecto servirá como base para demostrar la creación de servicios, módulos, front-end y toda la integración de eventos. Un proyecto Lino no es solo una carpeta con una solución: define convenciones para límites de servicios, bibliotecas compartidas, host Aspire, marco de interfaz, pruebas, administración de paquetes, analizadores y configuraciones que los siguientes Commands reutilizan.

Paso 1: ejecutar el comando crear

Para crear un nuevo proyecto, ejecute el siguiente comando en la terminal:

lino project new

CLI lo guiará paso a paso, solicitándole información como:

• Nombre del proyecto: usaremos MyApp, pero puedes elegir el nombre que quieras;
• Características adicionales: analizadores de código, almacenamiento en caché distribuido, soporte de eventos asincrónicos, etc.

Paso 2: configurar funciones esenciales

Para este proyecto, recomendamos habilitar las siguientes funciones desde el principio:

• Analizadores de código: garantizar que el código siga buenas prácticas y estándares consistentes, evitando errores comunes de implementación;
• Caché distribuido: mejora el rendimiento de la aplicación en escenarios con múltiples servicios, evitando Queries innecesarias a la base de datos;
• Comunicación asincrónica: Permite el uso de eventos y colas para la integración entre servicios, asegurando escalabilidad y desacoplamiento.

Es importante habilitar todas estas opciones en este proyecto, ya que crearemos múltiples servicios que se comunicarán a través de eventos de integración. Esto le permitirá comprender cómo estructurar sistemas modulares y distribuidos utilizando Lino.

Paso 3: estructura generada

Después de ejecutar el comando y configurar los recursos, CLI generará la estructura inicial del proyecto. Incluirá:

• Carpetas de servicios y módulos;
• Templates para front-end (si corresponde);
• Configuraciones iniciales de caché, eventos e integraciones;
• Archivos de solución (.slnx) y proyecto (.csproj) listos para su compilación.

Ahora tu proyecto Mi aplicación está listo para recibir los servicios, módulos, entidades y front-end que configuraremos en los próximos pasos. Antes de continuar, abra la solución generada y ejecute dotnet build para confirmar que las referencias, los source generators, los templates, los archivos de proyecto y la configuración inicial son coherentes.

Agregar la aplicación web Backoffice

Un sistema completo normalmente necesita al menos una aplicación web para operar el dominio. En esta guía, la aplicación se llama Backoffice y representa una interfaz interna para administradores, gerentes o usuarios operativos para monitorear productos, categorías, existencias, ventas y otra información del sistema.

La aplicación web no reemplaza los servicios de dominio. Actúa como un punto de entrada visual para consumir APIs, activar Commands, consultar Queries y exponer pantallas coherentes con las reglas ya modeladas en los servicios.

Paso 1: ejecutar el comando crear

Para agregar una nueva aplicación web al proyecto, use:

lino web-app new

El alias lino webapp new también está disponible para facilitar la escritura. Durante la ejecución, indique un nombre claro para la aplicación web; en este ejemplo, usaremos Backoffice.

lino web-app new --name Backoffice

Paso 2: comprender la estructura generada

Al final del proceso, Lino crea la estructura inicial de la Web App en src/WebApps/<WebAppName>. Para una aplicación Blazor, la estructura puede incluir proyectos server/client, recursos compartidos, archivos de localización, clients para consumir APIs y convenciones que serán utilizadas posteriormente por lino page new.

• Carpetas para páginas, componentes, diseños, servicios y recursos de aplicaciones;
• Clientes HTTP y contratos requeridos para consumir API expuestos por los servicios del proyecto;
• Resources de localización y templates iniciales usados por la experiencia web;
• Proyectos cliente/servidor cuando el tipo de aplicación requiera esta separación;
• Convenciones de ruta, navegación e integración que serán reutilizadas en la generación de páginas;
• Puntos de integración con autenticación y autorización cuando se agrega la funcionalidad de auth al proyecto.

Paso 3: Cuándo crear la aplicación web en el flujo

Si ya sabe que el sistema tendrá una interfaz Blazor, cree la Web App al principio, después de crear el proyecto. Así, los servicios, módulos, entidades, APIs y páginas generados después ya quedan alineados con la aplicación web que los consumirá.

Este flujo es especialmente útil porque los servicios creados posteriormente también generan proyectos tipados de Api.Contracts y Api.Client, consumidos por el proyecto Blazor. Con la Web App presente desde el inicio, resulta más simple validar el camino completo: dominio, API, contratos, HttpClient y pantalla.

Notas importantes

• Backoffice debe consumir los datos por medio de las APIs generadas, manteniendo la lógica de negocio en los servicios y módulos correctos.
• Antes de exponer páginas administrativas, revise la autenticación, autorización, roles, permisos y políticas de acceso.
• Puede crear múltiples aplicaciones web, por ejemplo un Backoffice interno y un Site público, cuando los públicos, permisos, deploys o responsabilidades sean diferentes.
• Evite mezclar flujos públicos y administrativos en la misma aplicación web cuando esto dificulte la seguridad, la navegación, la implementación o la propiedad del equipo.

Con la aplicación web creada, la guía puede pasar a los servicios y módulos que proporcionarán los datos y reglas de negocio que consume esta interfaz.

Creación de servicios y módulos.

En este paso, construiremos los servicios y módulos que conformarán la aplicación. El objetivo es crear una arquitectura modular y escalable, permitiendo que diferentes áreas del sistema, como productos, categorías, inventario, ventas y medios, evolucionen de forma independiente, manteniendo la cohesión y facilitando el mantenimiento. Los servicios definen los límites de deploy y persistencia; los módulos organizan áreas de negocio dentro de un servicio modular. Antes de crear archivos, evalúe qué partes del dominio necesitan base de datos propia, release independiente, contrato de integración u ownership separado.

Paso 1: Definir los servicios

Inicialmente, crearemos los siguientes servicios, cada uno con responsabilidades bien definidas:

• Catalog (modular) – responsable de gestionar productos, categorías y precios;
• Sales – responsable de procesar ventas y pedidos;
• Stock – responsable de la gestión de stocks y movimientos;
• Security – responsable de la autenticación, autorización y gestión de usuarios.

Para crear los servicios del ejemplo, ejecute un comando por cada servicio. En el wizard de Catalog, elija arquitectura modular; en los demás, elija la arquitectura adecuada para una frontera simple.

lino service new --name Catalog
lino service new --name Sales
lino service new --name Stock
lino service new --name Security

Durante la ejecución del comando, el CLI solicitará:

• Nombre del servicio: por ejemplo, Catalog;
• Nombre para mostrar y estilo arquitectónico: elija una arquitectura simple para fronteras compactas o modular cuando el servicio tenga áreas cohesivas independientes;
• Base de datos: elija la tecnología que mejor se adapte a su proyecto (SQL Server, PostgreSQL, etc.);

Paso 2: Creando módulos dentro de servicios

No todos los servicios necesitan ser modulares. En nuestro proyecto, solo el servicio Catalog tendrá módulos, para separar responsabilidades como merchandising y precios.

Definimos los siguientes módulos para el servicio Catalog:

• Merchandising – gestión de productos y categorías;
• Pricing – gestión de precios, promociones e historial de cambios.

Para crear los módulos de Catalog, ejecute:

lino module new --service Catalog --name Merchandising
lino module new --service Catalog --name Pricing

Puedes crear tantos módulos como quieras dentro del servicio modular Catalog. Además, dependiendo de la complejidad, algunos módulos podrían convertirse en servicios independientes en el futuro. La separación que aquí se presenta es sólo para fines didácticos y sirve como ejemplo de organización modular. No use módulos solo para crear carpetas; úselos cuando protejan un área de negocio con entidades propias, casos de uso, APIs, migrations y eventos.

Estructura final del proyecto

Después de crear los servicios y módulos, su solución debería tener una estructura similar a la siguiente:

MyApp/
└── src/
    ├── Aspire/
    ├── Integrations/
    ├── Services/
    │   ├── Catalog/
    │   │   ├── Modules/
    │   │   │   ├── Merchandising/
    │   │   │   └── Pricing/
    │   │   ├── MyApp.Catalog.Host
    │   │   └── MyApp.Catalog.Infrastructure
    │   ├── Sales/
    │   ├── Security/
    │   ├── Shared/
    │   └── Stock/
    └── WebApps/
        ├── Backoffice/
        │   ├── Services/
        │   │   ├── Catalog/
        │   │   ├── Sales/
        │   │   ├── Security/
        │   │   └── Stock/
        │   ├── MyApp.WebApp.Backoffice
        │   └── MyApp.WebApp.Backoffice.Client
        └── Shared/
            └── MyApp.WebApp.Shared
└── tests/
    └── Services/
        ├── Catalog/
        │   ├── Merchandising/
        │   └── Pricing/
        ├── Sales/
        ├── Security/
        ├── Shared/
        └── Stock/

Explicación de la estructura:

• Services/: contiene todos los servicios del sistema, cada uno aislado con su propia lógica empresarial, infraestructura y alojamiento;
• Modules/: carpetas dentro de servicios modulares, que le permiten organizar funcionalidades específicas y mantener un código coherente;
• WebApps/: frontends asociados al sistema, ya integrados con los servicios;
• Shared/: bibliotecas y recursos compartidos entre servicios y frontends;
• tests/: pruebas unitarias y de integración organizadas por servicio y módulo.

Con esta estructura modular, cada equipo o desarrollador puede trabajar de forma independiente en diferentes partes del sistema, facilitando la escalabilidad, el mantenimiento y las pruebas. Después de crear servicios y módulos, ejecute dotnet build para confirmar que los proyectos están conectados correctamente a la solución, el host Aspire, los proyectos compartidos y la estructura de pruebas.

Agregar autenticación y autorización

La autenticación y la autorización son elementos esenciales de cualquier sistema moderno. La autenticación comprueba quién es el usuario; la autorización define qué puede ejecutar ese usuario. En Lino CLI, la funcionalidad de auth genera la base necesaria para usuarios, roles, permisos, tokens, políticas de acceso e integración con APIs.

Paso 1: ejecutar el comando de autenticación

Para agregar recursos de autenticación y autorización, use el comando:

lino feature auth add

CLI lo guiará a través de los siguientes pasos:

• Elección de servicio o módulo: debe indicar dónde se instalarán los artefactos de autenticación. En nuestro proyecto de ejemplo, utilizamos el servicio Security, que centraliza toda la lógica de seguridad del sistema;
• Configuraciones adicionales: creación de tablas de usuarios, roles, permisos, tokens y configuración de políticas de acceso;
• Vida útil del token: definición de vencimiento para el access token y el refresh token de acuerdo con la política de seguridad del producto;
• Tipo de identificador de usuario: elegir el tipo utilizado por el modelo de usuario y los contratos generados.

Paso 2: estructura generada

Después de ejecutar el comando, el servicio Security contendrá archivos y carpetas como:

• Domain/Entities: agregados, entidades y reglas para usuarios, roles, permisos y tokens;
• Infrastructure/Persistence: configuraciones de base de datos, mapeos de Entity Framework y migrations para tablas de seguridad;
• Application: Commands, Queries, Handlers, servicios de autenticación, generación de tokens, validación de credenciales y comprobaciones de permisos;
• API/Host: endpoints para login, logout, registro, refresh token y operaciones protegidas;
• Integración con la aplicación web: soporte para flujos autenticados cuando una aplicación web está presente.

Con esto, su aplicación tendrá una autenticación sólida y un control de acceso granular, lista para admitir múltiples usuarios y diferentes niveles de permisos. Aun así, el código generado debe tratarse como una base sólida, no como la revisión de seguridad final. Antes de producción, revise la vida útil de los tokens, el diseño de permisos, la política de contraseñas, HTTPS, secrets, rate limiting, logs y las configuraciones de deploy.

Agregar Background Jobs

En sistemas distribuidos y modulares, como el que estamos construyendo con Lino CLI, no todos los servicios se comunican directamente entre sí. Para garantizar la coherencia y confiabilidad en el intercambio de información, utilizamos eventos de integración. Sin embargo, para procesar estos eventos de manera eficiente y asincrónica, necesitamos Background Jobs.

Lino utiliza el estándar Outbox Pattern para garantizar que todos los mensajes generados por los servicios se registren de manera confiable antes de ser enviados. Con esto logramos:

• Evitar pérdida de eventos en caso de fallas o reinicios del servicio;
• Garantizar que el mismo mensaje se envíe solo una vez;
• Permitir el reprocesamiento de mensajes en caso de falla en la entrega;
• Separar el procesamiento de eventos de la lógica principal de la aplicación, mejorando el rendimiento y la escalabilidad.

Paso 1: ejecutar el comando

Para agregar soporte para Background Jobs a su proyecto, ejecute el comando:

lino feature background-job add

CLI le pedirá que seleccione el servicio donde se instalará el Background Job. Generalmente elegirás el servicio que centralice la producción del evento, como por ejemplo Catalog o Sales. En las opciones actuales, el asistente también puede solicitar el módulo, la biblioteca de jobs, si se deben procesar los eventos de Outbox, la programación y el tamaño del lote. El flujo de los templates actuales usa Hangfire para la ejecución recurrente de los jobs.

Paso 2: Configurar la ejecución

Durante la configuración, podrá definir:

• Intervalo de control: determina la frecuencia con la que el Background Job comprobará la tabla Outbox para mensajes nuevos. Un intervalo demasiado corto puede aumentar el uso de recursos, mientras que un intervalo demasiado largo puede retrasar la entrega de eventos;
• Lote de registros procesados ​​a la vez: controla cuántos eventos se leerán y enviarán por ejecución. Los lotes más grandes pueden aumentar el rendimiento, pero requieren más memoria y procesamiento;
• Política de retries: en caso de error al enviar mensajes, puede configurar cuántas veces el job intentará reenviarlos.

Estos parámetros dependen del tamaño de su sistema, la capacidad de la máquina y el volumen esperado de eventos.

Paso 3: estructura generada

Después de la configuración, el proyecto tendrá un Background Job listo para procesar mensajes de las tablas Outbox en cada servicio.

1. El caso de uso cambia el dominio y registra un dominio o evento de integración.
2. La unidad de trabajo guarda los datos de negocio y los mensajes de Outbox en la misma transacción.
3. Hangfire ejecuta jobs recurrentes que leen mensajes pendientes en lotes.
4. Los mensajes se publican en el motor de integración configurado, como RabbitMQ, cuando la comunicación asincrónica está habilitada.
5. Los mensajes completados, fallidos, antiguos o atascados pueden manejarse mediante la lógica y la configuración generadas para el job.

Esto garantiza que todos los eventos de integración se procesen de manera confiable y eficiente, lo que permite que múltiples servicios y módulos se comuniquen de forma asincrónica, sin afectar el rendimiento del sistema principal. La regla operativa más importante es mantener claros los límites transaccionales: los eventos que deben enviarse a través de Outbox deben crearse en el mismo flujo transaccional que el cambio de negocio que representan.

Crear entidades y enumeraciones

En esta sección, detallaremos el diseño de las entidades, enumeraciones y Value Objects de la aplicación, mostrando en qué servicios y módulos se creará cada elemento.

1. Crear la entidad Category

Para crear la entidad Category en el servicio Catalog y en el módulo Merchandising, ejecute:

lino entity new --service Catalog --module Merchandising --name Category