Structurer le projet

Créer la fondation de la solution

La commande lino project new crée la fondation technique d'une nouvelle solution .NET. Exécutez-la dans un répertoire vide après avoir installé et authentifié la CLI.

lino project new --name 

L'argument représente le nom réel de la solution. Ce nom entre dans la composition des namespaces, assemblies, chemins, configurations, artefacts et références entre composants ; choisissez donc un nom court, stable et représentatif.

L'assistant interactif demande des décisions qui affectent la structure et le comportement de runtime de toute la solution :

• Namespace du projet : identité technique racine utilisée par les projets générés.
• Nom d'affichage : nom convivial utilisé dans les métadonnées générées et les points visibles par l'utilisateur.
• Langage et stack : actuellement C# avec .NET 10 et Aspire.
• Analyseurs de code : activent des packages et règles partagés pour maintenir cohérence et qualité dès le bootstrap.
• CQRS : prépare la couche d'application à séparer commands et queries, avec orchestration par la bibliothèque de mediator sélectionnée.
• Classes de base dans la solution : contrôle si des abstractions communes seront générées localement dans la solution.
• Cache distribué : définit si Microsoft.Extensions.Caching.Hybrid utilisera seulement la mémoire locale de l'instance ou aussi une couche distribuée avec Redis configurée par Aspire.
• Communication asynchrone : active RabbitMQ avec MassTransit et les blocs de messagerie/outbox utilisés par les événements d'intégration.
• Langue des données : langue utilisée pour décrire les métadonnées de domaine pendant la génération.
• Cultures prises en charge par l'application : ressources de localisation générées pour les textes d'UI, validations, erreurs et réponses d'API.
• Culture par défaut : langue principale utilisée lorsque l'application a besoin d'un fallback.

Après confirmation, Lino génère une solution organisée pour la croissance. Un projet minimal démarre avec Aspire, des couches partagées et les tests de la zone Shared :

/
├── .slnx
├── Directory.Build.props
├── Directory.Packages.props
├── src/
│   ├── Aspire/
│   │   ├── AppHost/
│   │   │   └── .AppHost.csproj
│   │   └── ServiceDefaults/
│   │       └── .ServiceDefaults.csproj
│   └── Services/
│       └── Shared/
│           ├── Api/
│           │   └── .Shared.Api.csproj
│           ├── Application/
│           │   └── .Shared.Application.csproj
│           ├── Domain/
│           │   └── .Shared.Domain.csproj
│           ├── Infrastructure/
│           │   └── .Shared.Infrastructure.csproj
│           ├── Infrastructure.Persistence/
│           │   └── .Shared.Infrastructure.Persistence.csproj
│           └── Integration.Events/          (quand la messagerie existe)
│               └── .Shared.Integration.Events.csproj
└── tests/
    └── Services/
        └── Shared/
            └── UnitTests/
                ├── Domain/
                │   └── .Shared.Domain.UnitTests.csproj
                └── Application/
                    └── .Shared.Application.UnitTests.csproj

Le rôle des projets Shared

Shared contient le code de plateforme partagé par la solution. Ce n'est pas un service métier. Utilisez cet espace pour les abstractions transversales, les erreurs communes, l'infrastructure de localisation, les contrats de base de l'application, les helpers de persistance, les extensions d'API, l'intégration avec l'host, l'observabilité et les utilitaires techniques réutilisables.

Évitez de placer des règles métier dans Shared. Si une règle appartient à une capacité spécifique de l'application, elle doit rester dans le service ou le module qui possède cette responsabilité. L'objectif de Shared est de réduire la répétition technique, pas de devenir un raccourci pour coupler différents domaines.

Aspire et décisions d'infrastructure

AppHost compose la solution et ses ressources de runtime. Lorsque Redis, RabbitMQ, SQL Server, PostgreSQL, Redis Insight, des services, WebApps ou workers sont ajoutés, Aspire devient le point d'orchestration local. Cela simplifie l'exécution, la découverte de services, les logs, métriques, traces et la visualisation des ressources pendant le développement.

ServiceDefaults centralise des patterns d'hosting tels que service discovery, health checks, résilience, logging, métriques, tracing et intégration OpenTelemetry. Au lieu que chaque service configure cela isolément, la solution démarre avec un point commun de composition.

Analyseurs de code

Les analyseurs de code statique inspectent le code pendant le développement et rendent les problèmes visibles avant l'exécution : incohérences de style, patterns fragiles, opportunités de refactoring, bugs possibles et alertes de sécurité.

Lorsque vous activez les analyseurs dans lino project new, la solution démarre déjà avec des packages comme StyleCop.Analyzers, SonarAnalyzer.CSharp et Roslynator.Analyzers configurés de manière centralisée. Cela évite que chaque projet doive décider seul des règles à suivre.

• Amélioration de la qualité : garde le code lisible, cohérent et aligné avec les standards de la solution.
• Prévention des erreurs : signale les problèmes tôt, avant qu'ils n'atteignent les tests manuels ou la production.
• Standardisation : réduit les différences de style entre services, modules et équipes.
• Refactoring assisté : met en évidence des simplifications et modernisations possibles dans le code C#.

Cache distribué, cache hybride et Redis

Lino prépare la solution à utiliser Microsoft.Extensions.Caching.Hybrid, la bibliothèque Microsoft qui centralise les opérations de cache via HybridCache. Cette abstraction permet aux handlers, services d'application et composants d'infrastructure de stocker des résultats de requêtes, permissions, configurations ou données de support sans disperser les détails d'implémentation du cache dans le code.

Lorsque vous n'activez pas le cache distribué à la création du projet, HybridCache reste disponible, mais fonctionne uniquement avec la mémoire locale de l'instance en cours d'exécution. Ce mode est simple et suffisant pour les scénarios locaux, les petits environnements ou les applications avec une seule réplique, mais chaque processus conserve son propre cache et les données ne sont pas partagées entre instances.

Lorsque vous activez le cache distribué, Lino ajoute Redis aux ressources Aspire et configure l'infrastructure pour utiliser une couche de cache partagée. Avec Redis, plusieurs instances du même service peuvent interroger la même couche, ce qui réduit les lectures répétées en base de données, APIs internes ou intégrations et prépare le projet à la mise à l'échelle horizontale.

• Performance : réduit le temps de réponse pour les lectures répétées et les opérations de support.
• Scalabilité : permet à différentes instances de partager des données en cache.
• Disponibilité : découple une partie de la charge de lecture de la base de données principale.
• Coût opérationnel : diminue le traitement répétitif dans les requêtes et intégrations à fort volume.

Cette décision est prise dans lino project new parce qu'elle modifie la fondation de l'environnement : ressources de l'AppHost, secrets locaux, packages, configuration d'infrastructure et topologie d'exécution affichée dans le dashboard Aspire.

Communication asynchrone

La communication asynchrone permet aux services, modules et composants de réagir à des faits du système sans bloquer le flux principal de l'opération. Elle est particulièrement utile lorsque le producteur ne doit pas dépendre de la disponibilité immédiate du consommateur ou lorsqu'une action doit déclencher des effets ultérieurs, comme des notifications, projections, intégrations externes ou synchronisations entre contextes.

Lorsque vous activez la communication asynchrone, Lino ajoute RabbitMQ à Aspire et configure MassTransit avec les blocs de messagerie et outbox utilisés par les événements d'intégration. Ainsi, les événements publiés par des services ou modules sont représentés par des contrats explicites dans Integration.Events et peuvent être traités avec plus de résilience.

• Performance : permet au cas d'utilisation principal de continuer sans attendre que tous les consommateurs aient terminé.
• Scalabilité : distribue le traitement entre consommateurs et files, en absorbant les pics avec plus de contrôle.
• Résilience : permet le retraitement et réduit la perte de messages lorsqu'elle est combinée avec outbox.
• Découplage : évite la dépendance directe entre producteur et consommateur lorsqu'une réponse immédiate n'est pas nécessaire.

Utilisez des événements d'intégration lorsqu'un échec du consommateur ne doit pas annuler la transaction du producteur. Lorsque le consommateur doit répondre immédiatement pour compléter le cas d'utilisation, préférez une intégration synchrone explicite et traitez disponibilité, timeout et fallback comme faisant partie du contrat.

Localisation et cultures

Lorsque des cultures sont sélectionnées, Lino génère des ressources afin que messages, validations, labels, erreurs et textes d'UI puissent être localisés dès le début. Cela évite de traiter l'internationalisation comme un correctif tardif, une fois les chaînes déjà dispersées dans les endpoints, handlers et composants.

Valider la fondation et passer aux services

Après la génération, restaurez les dépendances, compilez la solution et exécutez l'host Aspire :

dotnet restore .slnx
dotnet build .slnx
dotnet run --project src/Aspire/AppHost/.AppHost.csproj

À ce stade, la solution reste une fondation. Ouvrez le projet dans l'éditeur, révisez les ressources créées par Aspire, confirmez les décisions de cache, messagerie, localisation et qualité du code, puis passez aux services qui représenteront les capacités métier de l'application.

Créer et gérer des services

Un service est une limite de runtime et d'ownership. Dans Lino, les services peuvent représenter des APIs indépendantes dans un système distribué ou des zones métier plus larges dans une solution qui peut évoluer progressivement.

Après avoir créé la fondation du projet, ajoutez des services avec :

lino service new

L'assistant de service demande :

• Namespace du service : nom technique utilisé dans les dossiers, projets et namespaces.
• Nom d'affichage : nom convivial du service.
• Type de service : choisissez entre simple et modulaire.
• Provider de base de données : choisissez SQL Server ou PostgreSQL pour la base de données du service.
• Style d'architecture : actuellement Clean Architecture pour les services simples.
• Strongly Typed IDs : dans les services simples, définit si les identifiants seront générés comme types dédiés.

Types de service

Service simple : structure plus directe pour une capacité métier avec une frontière claire. C'est un bon choix pour une API ciblée, un microservice ou une zone assez petite pour évoluer comme une unité.

Service modulaire : structure indiquée pour les systèmes plus grands, les monolithes modulaires ou les runtimes qui doivent héberger plusieurs capacités indépendantes. Les modules améliorent l'organisation et la scalabilité du modèle, mais exigent plus de discipline de dépendance.

Quel que soit le type, chaque service possède sa propre base de données. Dans les services simples, la décision sur Strongly Typed IDs se prend au niveau du service ; dans les services modulaires, elle se prend par module.

Service simple

Un service simple place ses couches directement dans src/Services/. Utilisez cette structure lorsque la capacité métier possède une limite claire et n'a pas besoin de plusieurs modules isolés dans le même runtime. Elle fonctionne bien pour une API ciblée, un microservice ou une zone de domaine assez petite pour évoluer comme une unité.

src/Services//
├── Domain/
│   └── ..Domain.csproj
├── Application/
│   └── ..Application.csproj
├── Infrastructure.Persistence/
│   └── ..Infrastructure.Persistence.csproj
├── Infrastructure/
│   └── ..Infrastructure.csproj
├── Api/
│   └── ..Api.csproj
├── Integration.Events/              (quand la messagerie existe)
│   └── ..Integration.Events.csproj
├── Api.Contracts/                   (quand la consommation HTTP typée existe)
│   └── ..Api.Contracts.csproj
└── Api.Client/                      (quand la consommation HTTP typée existe)
    └── ..Api.Client.csproj
tests/Services//
├── UnitTests/
│   ├── Domain/
│   │   └── ..Domain.UnitTests.csproj
│   └── Application/
│       └── ..Application.UnitTests.csproj
└── IntegrationTests/
    └── ..IntegrationTests.csproj

Les couches ont des responsabilités distinctes : Domain protège les règles métier et invariants ; Application orchestre les cas d'utilisation ; Infrastructure.Persistence contient Entity Framework Core, repositories, Unit of Work et migrations ; Infrastructure contient les intégrations techniques ; et Api adapte HTTP aux cas d'utilisation.

Les projets Api.Contracts et Api.Client apparaissent lorsqu'il existe une consommation HTTP typée, surtout dans les solutions avec Web App Blazor. Le premier concentre requests, responses, DTOs, types publics et interfaces de client partagées ; le second fournit l'implémentation HTTP de ces interfaces, avec HttpClient, afin que Blazor consomme les APIs générées sans dupliquer les contrats.

Le projet Integration.Events apparaît lorsque la solution a la messagerie activée. Il contient les événements d'intégration publiés et consommés par d'autres modules, services ou systèmes, généralement avec l'infrastructure de messagerie et outbox.

Service modulaire

Un service modulaire est indiqué pour les monolithes modulaires ou pour un runtime qui héberge plusieurs bounded contexts. Le service lui-même possède l'host, l'infrastructure commune et le provider de base de données ; les règles métier vivent dans les modules.

src/Services//
├── Host/
│   └── ..Host.csproj
├── Infrastructure/
│   └── ..Infrastructure.csproj
└── Modules/
tests/Services//
└── Modules/

Le Host compose les modules, configurations, endpoints et l'infrastructure partagée de ce service. Il ne doit pas contenir de règles métier. Le projet Infrastructure au niveau du service fournit le support technique de composition partagé par les modules.

Lorsqu'un module est ajouté, les projets Domain, Application, Infrastructure.Persistence, Infrastructure et Api apparaissent dans Modules/, en préservant la frontière interne. Les projets Api.Contracts, Api.Client et Integration.Events suivent les mêmes conditions : consommation HTTP typée pour Blazor/API clients et messagerie activée pour les événements d'intégration.

Ownership de base de données

Chaque service possède sa propre base de données. Dans une solution avec plusieurs services, un service peut utiliser PostgreSQL tandis qu'un autre utilise SQL Server. Cette décision peut varier selon les besoins du domaine, la performance, l'exploitation, la maturité de l'équipe ou l'intégration avec l'infrastructure existante.

Dans un service modulaire, la base appartient au service en tant que runtime, mais les modules sont isolés par schema, projets de persistance et migrations propres. Un module ne doit pas consulter directement les tables d'un autre module, même lorsque les tables se trouvent dans la même base physique.

Choisir entre simple et modulaire

Choisissez la plus petite structure qui protège la limite. Un service simple suffit lorsqu'il existe une seule frontière de domaine. Un service modulaire a du sens lorsque plusieurs capacités doivent partager runtime, deploy ou transaction, tout en conservant modèles, persistance, APIs et tests séparés.

Style d'architecture

Les services générés par Lino suivent Clean Architecture afin de séparer les règles métier des détails techniques. La couche de domaine n'a pas besoin de connaître HTTP, Entity Framework Core, la messagerie, l'UI ou les providers externes ; ces préoccupations restent aux bords de l'application.

• Découplage : les règles centrales ne dépendent pas de frameworks ni de mécanismes de livraison.
• Maintenabilité : les changements d'infrastructure tendent à rester isolés des règles métier.
• Testabilité : les cas d'utilisation et le domaine peuvent être testés avec moins de dépendances externes.
• Évolution : les détails techniques peuvent être remplacés avec moins d'impact sur le noyau du service.

Clean Architecture et Strongly Typed IDs

Les services générés suivent Clean Architecture afin que le code métier ne dépende pas de HTTP, EF Core, la messagerie, l'UI ou les détails d'infrastructure. Cette séparation rend les tests plus directs, réduit le couplage et permet de remplacer les détails techniques sans réécrire les règles centrales.

Strongly Typed IDs augmente la sécurité en empêchant les mélanges accidentels d'identifiants. Au lieu d'accepter n'importe quel Guid, long ou int, le domaine peut travailler avec un type propre à chaque entité ou agrégat, généralement au format Id. Cela évite de passer l'identifiant d'une entité là où un autre était attendu et rend les signatures plus expressives dans commands, queries, entités, handlers et mappings.

• Sécurité de type : empêche de mélanger accidentellement les identifiants d'entités différentes.
• Clarté : rend les signatures et contrats plus expressifs que des types primitifs isolés.
• Refactoring : concentre les changements de format ou de sérialisation dans le type d'ID correspondant.
• Réduction des erreurs : rend les usages incorrects visibles à la compilation chaque fois que possible.

Intégration entre services

Lorsqu'un service doit réagir à un autre, préférez les événements d'intégration, les intégrations HTTP explicites ou les données répliquées consciemment. L'accès direct à la base d'un autre service crée un couplage structurel, complique les migrations et rend les deploys indépendants plus risqués.

Prochaines étapes pour les services modulaires

Après avoir créé un service modulaire, l'étape suivante consiste à ajouter des modules avec lino module new. Chaque module doit représenter sa propre capacité métier, avec domaine, application, persistance, API, tests et intégrations qui préservent la limite interne du service.

Créer et gérer des modules

Les modules existent uniquement à l'intérieur de services modulaires. Un module représente une limite métier dans le même runtime : il possède son propre modèle de domaine, ses cas d'utilisation, sa persistance, sa surface d'API, ses événements d'intégration, ses tests et son schema de base de données.

Utilisez des modules lorsque le service doit héberger plus d'une capacité métier sans mélanger entités, règles, migrations et contrats. Dans un monolithe modulaire, tout peut s'exécuter dans le même processus, mais les limites internes restent importantes : l'isolation réelle relève du contrôle des dépendances, pas seulement de la séparation des dossiers.

lino module new --service 

Pendant la création, l'assistant demande :

• Service : le service modulaire qui hébergera le module. Lino n'autorise pas la création de modules dans des services simples, car ils ne possèdent pas la structure nécessaire à l'isolation interne.
• Namespace du module : le nom technique utilisé dans les dossiers, namespaces, assemblies et projets.
• Nom d'affichage : le nom convivial du module dans les emplacements destinés à la lecture humaine.
• Strongly Typed IDs : définit si les identifiants générés dans le module utiliseront des types dédiés, généralement au format Id.

Après confirmation, Lino ajoute le module dans le service sans faire disparaître la limite architecturale :

src/Services//
├── Host/
├── Infrastructure/
└── Modules/
    └── /
        ├── Domain/
        │   └── ...Domain.csproj
        ├── Application/
        │   └── ...Application.csproj
        ├── Infrastructure.Persistence/
        │   └── ...Infrastructure.Persistence.csproj
        ├── Infrastructure/
        │   └── ...Infrastructure.csproj
        ├── Api/
        │   └── ...Api.csproj
        ├── Integration.Events/              (quand la messagerie existe)
        │   └── ...Integration.Events.csproj
        ├── Api.Contracts/                   (quand la consommation HTTP typée existe)
        │   └── ...Api.Contracts.csproj
        └── Api.Client/                      (quand la consommation HTTP typée existe)
            └── ...Api.Client.csproj
tests/Services//Modules//
├── UnitTests/
│   ├── Domain/
│   │   └── ...Domain.UnitTests.csproj
│   └── Application/
│       └── ...Application.UnitTests.csproj
└── IntegrationTests/
    └── ...IntegrationTests.csproj

Responsabilités des artefacts générés

Structure de base de données

La base de données reste liée au service, pas au module isolément. Dans un service modulaire, chaque module est représenté par son propre schema dans la base associée, avec son propre projet de persistance et ses propres migrations. Cela offre isolation et organisation sans exiger plusieurs bases physiques pour chaque module.

Isolation et indépendance entre modules

Un module ne doit pas accéder directement au DbContext, aux entités, aux repositories ou aux services internes d'un autre module. Chaque module possède son propre modèle et sa propre persistance. Lorsqu'un autre module a besoin de données, utilisez une intégration explicite au lieu de traverser la frontière par des détails internes d'implémentation.

Cela évite qu'un changement apparemment local casse une autre zone du système. Si un module consommateur doit consulter des données qui appartiennent à un autre module, il ne doit pas dépendre de l'entité complète du module source. Il peut conserver une shadow entity avec les données minimales nécessaires à son propre cas d'utilisation, alimentée par intégration ou événement.

Avantages de ce découplage :

• Isolation : chaque module peut faire évoluer règles, persistance et tests sans traverser les détails internes d'un autre module.
• Organisation : l'application respecte les bounded contexts et rend l'ownership explicite.
• Flexibilité : les modules peuvent être ajoutés, supprimés ou refactorisés avec moins d'impact sur le reste du service.
• Facilité de test : chaque module peut être validé de manière plus indépendante, ce qui augmente la confiance dans les changements.

Communication entre modules

Utilisez des contrats explicites pour la communication. Pour les appels dans le même runtime, une intégration interne peut exposer des contrats dans Integration.Contracts et une implémentation in-process lorsqu'elle est générée. Pour les appels entre runtimes, utilisez une intégration HTTP. Pour la propagation asynchrone, publiez des événements d'intégration dans Integration.Events et utilisez l'infrastructure de messagerie/outbox lorsque la publication fait partie d'une opération transactionnelle.

Schemas, migrations et base de données

Dans un service modulaire, les modules partagent le provider de base de données du service, mais chaque module est représenté par son propre schema et par son propre projet Infrastructure.Persistence. Les migrations sont générées par module, ce qui maintient l'évolution de la base alignée avec la limite métier.

Cette séparation permet à chaque module de faire évoluer ses tables, seeds, index et foreign keys sans transformer la base du service en un modèle unique partagé par tous. Le schema est une limite technique qui renforce la limite métier, même lorsque les modules s'exécutent dans le même processus et utilisent la même base physique.

Bonnes limites de module

Créez les modules autour de capacités métier, pas autour de couches techniques. Un bon nom de module doit décrire une responsabilité reconnaissable par le domaine, comme une zone, un processus ou une capacité qui possède ses propres règles. Évitez les noms génériques comme Common, Core ou Utilities pour les règles métier, car ils masquent l'ownership et tendent à devenir des dépendances trop partagées.

• Cohésion : le module doit avoir un langage, des règles et des données qui changent ensemble.
• Autonomie : il doit être possible de tester et de faire évoluer le module sans accéder aux entités internes d'un autre module.
• Contrats clairs : les données nécessaires hors du module doivent être exposées par API, intégration, événement ou shadow entity, pas par accès direct à la base.
• Faible couplage : si deux modules doivent modifier les mêmes entités en permanence, la limite doit probablement être réévaluée.

Une fois les modules créés, les prochains sujets de la documentation montrent comment modéliser entités, Value Objects, enumerations, commands, queries, APIs, événements, intégrations et migrations à l'intérieur de ces limites.