Créer une application .NET complète avec Lino : guide étape par étape

Installation et configuration de Lino CLI

La première étape pour commencer à travailler avec le Lino CLI consiste à installer l’outil dans votre environnement de développement. Il est distribué sous forme de outil mondial dotnet, ce qui signifie qu'il sera disponible pour n'importe quel projet.NET sur votre ordinateur. Avant l'installation, confirmez que le SDK.NET requis par les modèles actuels est disponible et que le terminal peut s'exécuter dotnet et que le répertoire global des outils.NET se trouve dans le PATH.

Étape 1 : Installation

Pour installer (ou mettre à jour) Lino CLI, exécutez la commande suivante dans le terminal :

dotnet tool install --global Tolitech.Lino

Remarques importantes :

• Si une version est déjà installée, vous pouvez utiliser dotnet tool update --global Tolitech.Lino à mettre à jour.
• Vérifiez que le répertoire des outils globaux.NET se trouve dans le PATH du système afin que la commande lino fonctionner correctement.

Étape 2 : Configurer la langue

Après l'installation, il est recommandé de configurer la langue (ou la culture) que CLI utilisera dans les messages, les invites et les journaux :

lino preferences culture set

Il vous sera demandé de choisir parmi les langues disponibles. Ce paramètre garantit que toutes les instructions et invites apparaissent de manière cohérente dans la langue souhaitée. Cette préférence modifie les messages, invites et conseils localisés de CLI ; il ne renomme pas les entités, services, modules ou termes métier générés dans le projet.

Étape 3: Authentification et enregistrement

Pour accéder à toutes les fonctionnalités de Lino, y compris les modèles avancés, la publication d'images Docker et les intégrations avec des services externes, vous devez être authentifié.

- Si vous n'êtes pas encore inscrit, inscrivez-vous avec la commande :

lino user register

- Si vous êtes déjà inscrit, connectez-vous avec:

lino auth login

Ce qui se produit: CLI stocke localement un jeton d'authentification, vous permettant d'exécuter des Commands nécessitant un accès à des ressources protégées sans avoir à vous connecter à chaque fois que vous l'utilisez. Gardez ce jeton privé et évitez de partager le même profil utilisateur entre différents développeurs, agents CI ou machines.

Étape 4 : Vérification

Pour confirmer que l'installation et l'authentification ont réussi, exécutez :

lino --version

Si la commande renvoie la version installée, vous êtes prêt à commencer à utiliser le Lino CLI dans vos projets.

Création du projet MyApp

Dans cette étape, nous créerons la structure initiale du projet en utilisant le Lino CLI. Ce projet servira de base pour démontrer la création de services, de modules, le front-end et l'intégration de tous les événements. Un projet Lino n'est pas seulement un dossier avec une solution : il définit les conventions pour les limites des services, les bibliothèques partagées, l'hôte Aspire, le framework frontend, les tests, la gestion des packages, les analyseurs et les configurations que les Commands suivantes réutilisent.

Étape 1 : Exécuter la commande de création

Pour créer un nouveau projet, exécutez la commande ci-dessous dans le terminal :

lino project new

CLI vous guidera étape par étape, en vous demandant des informations telles que :

• Nom du projet : nous utiliserons MyApp, mais vous pouvez choisir le nom de votre choix ;
• Fonctionnalités supplémentaires : analyseurs de code, mise en cache distribuée, prise en charge des événements asynchrones, etc.

Étape 2 : configuration des fonctionnalités essentielles

Pour ce projet, nous vous recommandons d'activer les fonctionnalités suivantes dès le début :

• Analyseurs de code : garantir que le code suit de bonnes pratiques et des normes cohérentes, évitant ainsi les erreurs de mise en œuvre courantes ;
• Cache distribué : améliore les performances des applications dans des scénarios avec plusieurs services, en évitant les Queries de base de données inutiles ;
• Communication asynchrone : permet l'utilisation d'événements et de files d'attente pour l'intégration entre les services, garantissant ainsi l'évolutivité et le découplage.

Il est important d'activer toutes ces options dans ce projet, car nous créerons plusieurs services qui communiqueront via des événements d'intégration. Cela vous permettra de comprendre comment structurer des systèmes modulaires et distribués à l'aide de Lino.

Étape 3 : Structure générée

Après avoir exécuté la commande et configuré les ressources, CLI générera la structure initiale du projet. Il comprendra:

• Dossiers de services et de modules ;
• Modèles frontaux (le cas échéant) ;
• Paramètres de cache initiaux, événements et intégrations ;
• Fichiers de solution (.slnx) et de projet (.csproj) prêts à être compilés.

Maintenant votre projet Mon application est prêt à recevoir les services, modules, entités et front-end que nous configurerons dans les prochaines étapes. Avant de continuer, ouvrez la solution générée et exécutez dotnet build pour confirmer que les références, les générateurs de sources, les modèles, les fichiers de projet et la configuration initiale sont cohérents.

Ajout de l'application web Backoffice

Un système complet nécessite généralement au moins une application Web pour faire fonctionner le domaine. Dans ce guide, l'application s'appelle Backoffice et représente une interface interne permettant aux administrateurs, aux gestionnaires ou aux utilisateurs opérationnels de surveiller les produits, les catégories, les stocks, les ventes et d'autres informations du système.

L'application Web ne remplace pas les services de domaine. Il fait office de point d'entrée visuel pour consommer des API, déclencher des Commands, consulter des Queries et afficher des écrans cohérents avec les règles déjà modélisées dans les services.

Étape 1 : Exécuter la commande de création

Pour ajouter une nouvelle application web au projet, utilisez :

lino web-app new

L'alias lino webapp new est également disponible pour faciliter la saisie. Pendant l'exécution, indiquez un nom clair pour l'application web ; dans cet exemple, nous utiliserons Backoffice.

lino web-app new --name Backoffice

Étape 2 : Comprendre la structure générée

À la fin du processus, Lino crée la structure initiale de la Web App dans src/WebApps/<WebAppName>. Pour une application Blazor, la structure peut inclure des projets server/client, des ressources partagées, des fichiers de localisation, des clients pour consommer les APIs et des conventions qui seront ensuite utilisées par lino page new.

• Dossiers pour les pages, les composants, les mises en page, les services et les ressources d'application ;
• Clients HTTP et contrats requis pour consommer les API exposés par les services du projet ;
• Ressources de localisation et modèles initiaux utilisés par l'expérience Web ;
• Projets client/serveur lorsque le type d'application nécessite cette séparation ;
• Conventions de routage, de navigation et d'intégration qui seront réutilisées dans la génération des pages ;
• Points d'intégration avec authentification et autorisation lorsque la fonctionnalité d'authentification est ajoutée au projet.

Étape 3 : Quand créer l’application Web dans le flux

Si vous savez déjà que le système aura une interface Blazor, créez la Web App dès le début, après la création du projet. Ainsi, les services, modules, entités, APIs et pages générés ensuite seront déjà alignés avec l'application web qui les consommera.

Ce flux est particulièrement utile parce que les services créés par la suite génèrent aussi des projets typés Api.Contracts et Api.Client, consommés par le projet Blazor. Avec la Web App présente dès le départ, il devient plus simple de valider le parcours complet : domaine, API, contrats, HttpClient et écran.

Remarques importantes

• Le Backoffice doit consommer les données via les API générés, en maintenant la logique métier dans les services et modules appropriés.
• Avant d'exposer les pages d'administration, vérifiez l'authentification, l'autorisation, les rôles, les autorisations et les stratégies d'accès.
• Vous pouvez créer plusieurs applications Web, par exemple un Backoffice interne et un Site public, lorsque les audiences, les autorisations, les déploiements ou les responsabilités sont différents.
• Évitez de mélanger les flux publics et administratifs dans une même Web App lorsque cela rend difficile la sécurité, la navigation, le déploiement ou l'appropriation des équipes.

Une fois l'application web créée, le guide peut passer aux services et modules qui fourniront les données et les règles métier consommées par cette interface.

Création de services et de modules

Dans cette étape, nous allons construire les services et modules qui composeront l’application. L'objectif est de créer une architecture modulaire et évolutive, permettant aux différents domaines du système, tels que les produits, les catégories, les stocks, les ventes et les médias, d'évoluer de manière indépendante, en maintenant la cohésion et en facilitant la maintenance. Les services définissent les limites de déploiement et de persistance ; Les modules organisent les domaines d'activité au sein d'un service modulaire. Avant de créer des fichiers, évaluez quelles parties du domaine nécessitent leur propre base de données, une version indépendante, un accord d'intégration ou une propriété distincte.

Étape 1: Définir les services

Dans un premier temps, nous créerons les services suivants, chacun avec des responsabilités bien définies:

• Catalog (modulaire) – responsable de la gestion des produits, des catégories et des prix ;
• Sales – responsable du traitement des ventes et des Commands ;
• Action – responsable de la gestion des stocks et des mouvements ;
• Security – responsable de l’authentification, de l’autorisation et de la gestion des utilisateurs.

Pour créer les services de l'exemple, exécutez une commande pour chaque service. Dans le wizard de Catalog, choisissez l'architecture modulaire ; pour les autres, choisissez l'architecture adaptée à une frontière simple.

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

Pendant l'exécution de la commande, le CLI demandera :

• Nom du service : par exemple, Catalog ;
• Nom d'affichage et style architectural : choisissez une architecture simple pour les frontières compactes, ou modulaire lorsque le service possède des zones cohésives indépendantes ;
• Base de données : choisissez la technologie qui convient le mieux à votre projet (SQL Server, PostgreSQL, etc.) ;

Étape 2 : Création de modules dans les services

Tous les services n'ont pas besoin d'être modulaires. Dans notre projet, seul le service Catalog aura des modules, afin de séparer des responsabilités comme le merchandising et la tarification.

Nous définissons les modules suivants pour le service Catalog :

• Merchandising – gestion des produits et des catégories ;
• Pricing – gestion des prix, des promotions et de l'historique des changements.

Pour créer les modules de Catalog, exécutez :

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

Vous pouvez créer autant de modules que vous le souhaitez au sein du service modulaire Catalog. De plus, en fonction de leur complexité, certains modules pourraient devenir des services indépendants à l'avenir. La séparation présentée ici est uniquement à des fins didactiques et sert d'exemple d'organisation modulaire. Ne vous contentez pas d'utiliser des modules pour créer des dossiers ; utilisez-les lorsqu'ils protègent un domaine d'activité avec ses propres entités, cas d'utilisation, API, migrations et événements.

Structure finale du projet

Après avoir créé les services et les modules, votre solution doit avoir une structure similaire à la suivante :

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/

Explication de la structure :

• Services/: contient tous les services système, chacun isolé avec sa propre logique métier, sa propre infrastructure et son hébergement ;
• Modules/: dossiers au sein de services modulaires, permettant d'organiser des fonctionnalités spécifiques et de maintenir un code cohérent ;
• WebApps/: frontends associés au système, déjà intégrés aux services ;
• Shared/: bibliothèques et ressources partagées entre services et frontends ;
• tests/: tests unitaires et d'intégration organisés par service et module.

Grâce à cette structure modulaire, chaque équipe ou développeur peut travailler indépendamment sur différentes parties du système, facilitant ainsi l'évolutivité, la maintenance et les tests. Après avoir créé les services et les modules, exécutez dotnet build pour confirmer que les projets sont correctement attachés à la solution, hébergez Aspire, les projets partagés et le cadre de test.

Ajout d'authentification et d'autorisation

L'authentification et l'autorisation sont des éléments essentiels de tout système moderne. L'authentification prouve qui est l'utilisateur ; l'autorisation définit ce que cet utilisateur peut effectuer. Dans Lino CLI, la feature d'auth génère la base nécessaire pour les utilisateurs, les rôles, les autorisations, les jetons, les politiques d'accès et l'intégration avec les API.

Étape 1 : Exécuter la commande d'authentification

Pour ajouter des fonctionnalités d'authentification et d'autorisation, utilisez la commande :

lino feature auth add

CLI vous guidera à travers les étapes suivantes :

• Choix du service ou du module: vous devez indiquer où les artefacts d'authentification seront installés. Dans notre exemple de projet, nous utilisons le service Security, qui centralise toute la logique de sécurité du système ;
• Paramètres supplémentaires : création de tableaux d'utilisateurs, de rôles, d'autorisations, de jetons et configuration des politiques d'accès ;
• Durée de vie du jeton : définition de l'expiration du access token et du refresh token conformément à la politique de sécurité du produit ;
• Type d'identifiant utilisateur : choisir le type utilisé par le modèle utilisateur et les contrats générés.

Étape 2 : Structure générée

Après avoir exécuté la commande, le service Security contiendra des fichiers et des dossiers tels que :

• Domaine/Entités : agrégats, entités et règles pour les utilisateurs, les rôles, les autorisations et les jetons ;
• Infrastructure/Persistance : configurations de bases de données, mappages Entity Framework et migrations pour les tables de sécurité ;
• Application: Commands, Queries, Handlers, services d'authentification, génération de jetons, validation des informations d'identification et vérifications des autorisations ;
• API/Hôte : points de terminaison pour la connexion, la déconnexion, l'enregistrement, le refresh token et les opérations protégées ;
• Intégration avec l'application Web : prise en charge des flux authentifiés lorsqu'une application Web est présente.

Grâce à cela, votre application disposera d'une authentification robuste et d'un contrôle d'accès granulaire, prête à prendre en charge plusieurs utilisateurs et différents niveaux d'autorisations. Néanmoins, le code généré doit être traité comme une base solide et non comme l’examen de sécurité final. Avant la production, examinez la durée de vie du jeton, la conception des autorisations, la politique de mot de passe, HTTPS, les secrets, la limitation de débit, les journaux et les configurations de déploiement.

Ajout de Background Jobs

Dans les systèmes distribués et modulaires, comme celui que nous construisons Lino CLI, tous les services ne communiquent pas directement entre eux. Pour garantir la cohérence et la fiabilité des échanges d’informations, nous utilisons des événements d’intégration. Cependant, pour traiter ces événements de manière efficace et asynchrone, nous avons besoin Background Jobs.

Lino utilise la norme Outbox Pattern pour garantir que tous les messages générés par les services sont enregistrés de manière fiable avant leur envoi. Avec cela, nous avons réalisé:

• Évitez la perte d’événements en cas de pannes ou de redémarrages de services ;
• Assurez-vous que le même message n’est envoyé qu’une seule fois ;
• Autoriser le retraitement des messages en cas d'échec de livraison ;
• Séparez le traitement des événements de la logique principale de l’application, améliorant ainsi les performances et l’évolutivité.

Étape 1 : Exécuter la commande

Pour ajouter la prise en charge des Background Jobs à votre projet, exécutez la commande :

lino feature background-job add

CLI vous demandera de sélectionner le service sur lequel le travail en arrière-plan sera installé. Généralement, vous choisirez le service qui centralise la production événementielle, comme Catalog ou Sales. Dans les options actuelles, l'assistant peut également demander le module, la bibliothèque de jobs, si les événements Outbox doivent être traités, le planning et la taille du lot. Le flux de modèle actuel utilise Hangfire pour l'exécution de tâches récurrentes.

Étape 2 : Configuration de l'exécution

Lors de la configuration, vous pourrez définir:

• Intervalle de vérification : détermine la fréquence à laquelle le travail en arrière-plan vérifiera la table Outbox pour les nouveaux messages. Un intervalle trop court peut augmenter l'utilisation des ressources, tandis qu'un intervalle trop long peut retarder la livraison des événements ;
• Lot d'enregistrements traités à la fois : contrôle le nombre d’événements qui seront lus et envoyés par exécution. Des lots plus volumineux peuvent augmenter les performances, mais nécessitent plus de mémoire et de traitement ;
• Politique de récupération : En cas d'échec de l'envoi de messages, vous pouvez configurer le nombre de tentatives de renvoi du travail.

Ces paramètres dépendent de la taille de votre système, de la capacité de la machine et du volume d'événements attendu.

Étape 3 : Structure générée

Après la configuration, le projet disposera d'un travail en arrière-plan prêt à traiter les messages des tables. Outbox dans chaque prestation.

1. Le cas d'utilisation modifie le domaine et enregistre un événement de domaine ou d'intégration.
2. L'unité de travail enregistre les données métiers et les messages de Outbox dans la même transaction.
3. Hangfire exécute des tâches récurrentes qui lisent les messages en attente par lots.
4. Les messages sont publiés sur le moteur d'intégration configuré tel que RabbitMQ lorsque la communication asynchrone est activée.
5. Les messages terminés, échoués, anciens ou bloqués peuvent être traités par la logique et la configuration générées pour la tâche.

Cela garantit que tous les événements d'intégration sont traités de manière fiable et efficace, permettant à plusieurs services et modules de communiquer de manière asynchrone, sans affecter les performances du système principal. La règle opérationnelle la plus importante est de garder la frontière transactionnelle claire: les événements qui doivent être envoyés via Outbox doivent être créés dans le même flux transactionnel que le changement métier qu'ils représentent.

Création d'entités et d'énumérations

Dans cette section, nous détaillerons la conception des entités, des énumérations et des Value Objects de l'application, en montrant dans quels services et modules chaque élément sera créé.

1. Création de l'entité Category

Pour créer l'entité Category dans le service Catalog et le module Merchandising, exécutez :

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