Eine vollständige .NET-Anwendung mit Lino erstellen: Schritt-für-Schritt-Anleitung

Installieren und Konfigurieren von Lino CLI

Der erste Schritt, um mit der Arbeit zu beginnen Lino CLI besteht darin, das Tool in Ihrer Entwicklungsumgebung zu installieren. Es wird als verteilt globales Dotnet-Tool, was bedeutet, dass es für jedes.NET-Projekt auf Ihrem Computer verfügbar ist. Vergewissern Sie sich vor der Installation, dass das für die aktuellen Vorlagen erforderliche .NET SDK verfügbar ist, das Terminal dotnet ausführen kann und sich das globale .NET-Tools-Verzeichnis im PATH des Systems befindet.

Schritt 1: Installation

Um Lino CLI zu installieren (oder zu aktualisieren), führen Sie den folgenden Befehl im Terminal aus:

dotnet tool install --global Tolitech.Lino

Wichtige Hinweise:

• Wenn bereits eine Version installiert ist, können Sie diese verwenden dotnet tool update --global Tolitech.Lino zu aktualisieren.
• Stellen Sie sicher, dass sich das globale .NET-Tools-Verzeichnis im PATH des Systems befindet, damit der Befehl lino korrekt funktioniert.

Schritt 2: Sprache konfigurieren

Nach der Installation wird empfohlen, die Sprache (oder Kultur) zu konfigurieren, die CLI in Nachrichten, Eingabeaufforderungen und Protokollen verwendet:

lino preferences culture set

Sie werden aufgefordert, eine der verfügbaren Sprachen auszuwählen. Diese Einstellung stellt sicher, dass alle Anweisungen und Eingabeaufforderungen einheitlich in der gewünschten Sprache angezeigt werden. Diese Einstellung ändert CLI lokalisierte Nachrichten, Eingabeaufforderungen und Anleitungen; Entitäten, Dienste, Module oder Geschäftsbegriffe, die im Projekt generiert wurden, werden nicht umbenannt.

Schritt 3: Authentifizierung und Registrierung

Um auf alle Lino-Funktionen zuzugreifen, einschließlich erweiterter Vorlagen, Docker-Image-Veröffentlichung und Integrationen mit externen Diensten, müssen Sie authentifiziert sein.

- Wenn Sie noch nicht registriert sind, registrieren Sie sich mit dem Befehl:

lino user register

- Wenn Sie bereits registriert sind, melden Sie sich an mit:

lino auth login

Was geschieht: CLI speichert ein Authentifizierungs-token lokal, sodass Sie Commands ausführen können, die Zugriff auf geschützte Ressourcen erfordern, ohne sich bei jeder Verwendung anmelden zu müssen. Halten Sie dieses Token privat und vermeiden Sie die gemeinsame Nutzung desselben Benutzerprofils zwischen verschiedenen Entwicklern, CI-Agenten oder Maschinen.

Schritt 4: Verifizierung

Um zu bestätigen, dass Installation und Authentifizierung erfolgreich waren, führen Sie Folgendes aus:

lino --version

Wenn der Befehl die installierte Version zurückgibt, können Sie Lino CLI in Ihren Projekten verwenden.

Erstellen des MyApp-Projekts

In diesem Schritt erstellen wir die anfängliche Struktur des Projekts mithilfe von Lino CLI. Dieses Projekt dient als Grundlage für die Demonstration der Erstellung von Diensten, Modulen, Frontends und der Integration aller Ereignisse. Ein Lino-Projekt ist nicht nur ein Ordner mit einer Lösung: Es definiert Konventionen für Dienstgrenzen, gemeinsam genutzte Bibliotheken, Aspire-Host, Frontend-Framework, Tests, Paketverwaltung, Analysatoren und Konfigurationen, die die nächsten Commands wiederverwenden.

Schritt 1: Ausführen des Befehls „create“.

Um ein neues Projekt zu erstellen, führen Sie den folgenden Befehl im Terminal aus:

lino project new

CLI führt Sie Schritt für Schritt und fragt nach Informationen wie:

• Projektname: wir werden es nutzen MyApp, aber Sie können einen beliebigen Namen wählen;
• Zusätzliche Funktionen: Code-Analysatoren, verteiltes Caching, asynchrone Ereignisunterstützung usw.

Schritt 2: Wesentliche Funktionen konfigurieren

Für dieses Projekt empfehlen wir, die folgenden Funktionen von Anfang an zu aktivieren:

• Code-Analysatoren: um sicherzustellen, dass der Kodex bewährten Praktiken und einheitlichen Standards folgt und so häufige Implementierungsfehler verhindert wird;
• Verteilter Cache: verbessert die Anwendungsleistung in Szenarien mit mehreren Diensten und vermeidet unnötige Datenbankabfragen;
• Asynchrone Kommunikation: ermöglicht die Verwendung von Ereignissen und Warteschlangen für die Integration zwischen Diensten und gewährleistet so Skalierbarkeit und Entkopplung.

Es ist wichtig, alle diese Optionen in diesem Projekt zu aktivieren, da wir mehrere Dienste erstellen werden, die über Integrationsereignisse kommunizieren. Dadurch erfahren Sie, wie Sie modulare und verteilte Systeme mit Lino strukturieren.

Schritt 3: Generierte Struktur

Nach der Ausführung des Befehls und der Konfiguration der Ressourcen generiert CLI die anfängliche Projektstruktur. Es umfasst:

• Ordner „Dienste und Module“;
• Frontend-Vorlagen (falls zutreffend);
• Anfängliche Cache-Einstellungen, Ereignisse und Integrationen;
• Lösungsdateien (.slnx) und Projektdateien (.csproj) bereit zur Kompilierung.

Jetzt ist Ihr Projekt MeineApp bereit, die Dienste, Module, Entitäten und das Frontend zu empfangen, die wir in den nächsten Schritten konfigurieren werden. Bevor Sie fortfahren, öffnen Sie die generierte Lösung und führen Sie sie aus dotnet build um zu bestätigen, dass Referenzen, Source Generators, Vorlagen, Projektdateien und Erstkonfiguration kohärent sind.

Hinzufügen der Backoffice-Webanwendung

Ein Gesamtsystem benötigt typischerweise mindestens eine Webanwendung zum Betrieb der Domäne. In dieser Anleitung wird die Anwendung aufgerufen Backoffice und stellt eine interne Schnittstelle für Administratoren, Manager oder operative Benutzer zur Überwachung von Produkten, Kategorien, Beständen, Salesn und anderen Systeminformationen dar.

Die Webanwendung ersetzt keine Domänendienste. Sie fungiert als visueller Einstiegspunkt, um APIs zu nutzen, Commands auszulösen, Queries abzufragen und Bildschirme anzuzeigen, die mit den bereits in den Diensten modellierten Regeln übereinstimmen.

Schritt 1: Ausführen des Befehls „create“.

Um dem Projekt eine neue Webanwendung hinzuzufügen, verwenden Sie:

lino web-app new

Der Alias lino webapp new ist ebenfalls verfügbar, um die Eingabe zu erleichtern. Geben Sie während der Ausführung einen klaren Namen für die Webanwendung an; in diesem Beispiel verwenden wir Backoffice.

lino web-app new --name Backoffice

Schritt 2: Verstehen der generierten Struktur

Am Ende des Prozesses erstellt Lino die Anfangsstruktur der Web App unter src/WebApps/<WebAppName>. Für eine Blazor-Anwendung kann die Struktur Server-/Client-Projekte, gemeinsame Ressourcen, Lokalisierungsdateien, Clients für den Zugriff auf APIs und Konventionen enthalten, die später von lino page new verwendet werden.

• Ordner für Seiten, Komponenten, Layouts, Dienste und Anwendungsressourcen;
• HTTP-Clients und -Verträge, die für die Nutzung von APIs erforderlich sind, die von Projektdiensten bereitgestellt werden;
• Lokalisierungsressourcen und anfängliche Vorlagen, die vom Web-Erlebnis verwendet werden;
• Client/Server-Projekte, wenn die Art der Anwendung diese Trennung erfordert;
• Routen-, Navigations- und Integrationskonventionen, die bei der Seitengenerierung wiederverwendet werden;
• Integrationspunkte mit Authentifizierung und Autorisierung, wenn die Authentifizierungsfunktion zum Projekt hinzugefügt wird.

Schritt 3: Wann soll die Web-App im Flow erstellt werden?

Wenn bereits feststeht, dass das System eine Blazor-Oberfläche haben wird, erstellen Sie die Web App früh, direkt nach der Projekterstellung. So sind die später generierten Services, Module, Entitäten, APIs und Seiten bereits auf die Webanwendung ausgerichtet, die sie konsumieren wird.

Dieser Ablauf ist besonders nützlich, weil später erstellte Services auch typisierte Projekte Api.Contracts und Api.Client erzeugen, die vom Blazor-Projekt konsumiert werden. Wenn die Web App von Anfang an vorhanden ist, lässt sich der gesamte Weg einfacher validieren: Domäne, API, Contracts, HttpClient und Bildschirm.

Wichtige Hinweise

• Das Backoffice muss die Daten über die generierten APIs nutzen und dabei die Geschäftslogik in den richtigen Diensten und Modulen aufrechterhalten.
• Bevor Sie Verwaltungsseiten freigeben, überprüfen Sie Authentifizierung, Autorisierung, Rollen, Berechtigungen und Zugriffsrichtlinien.
• Sie können mehrere Webanwendungen erstellen, zum Beispiel eine Backoffice intern und a Site öffentlich, wenn Zielgruppen, Berechtigungen, Bereitstellungen oder Verantwortlichkeiten unterschiedlich sind.
• Vermeiden Sie die Vermischung öffentlicher und administrativer Abläufe in derselben Web-App, wenn dies die Sicherheit, Navigation, Bereitstellung oder Teamverantwortung erschwert.

Nachdem die Webanwendung erstellt wurde, kann der Leitfaden mit den Diensten und Modulen fortfahren, die die von dieser Schnittstelle genutzten Daten und Geschäftsregeln bereitstellen.

Erstellen von Diensten und Modulen

In diesem Schritt erstellen wir die Dienste und Module, aus denen die Anwendung besteht. Das Ziel besteht darin, eine modulare und skalierbare Architektur zu schaffen, die es verschiedenen Bereichen des Systems, wie z. B. Produkten, Kategorien, Stock, Sales und Medien, ermöglicht, sich unabhängig voneinander zu entwickeln, den Zusammenhalt aufrechtzuerhalten und die Wartung zu erleichtern. Dienste definieren Bereitstellungs- und Persistenzgrenzen; Module organisieren Geschäftsbereiche innerhalb einer modularen Dienstleistung. Bevor Sie Dateien erstellen, prüfen Sie, welche Teile der Domäne eine eigene Datenbank, eine unabhängige Freigabe, eine Integrationsvereinbarung oder einen separaten Besitz benötigen.

Schritt 1: Definieren der Dienste

Zunächst werden wir die folgenden Dienste mit jeweils klar definierten Verantwortlichkeiten erstellen:

• Catalog (modular) – verantwortlich für die Verwaltung von Produkten, Kategorien und Preisen;
• Sales – verantwortlich für die Abwicklung von Salesn und Bestellungen;
• Aktie – verantwortlich für die Verwaltung von Beständen und Bewegungen;
• Security – verantwortlich für Authentifizierung, Autorisierung und Benutzerverwaltung.

Um die Services des Beispiels zu erstellen, führen Sie für jeden Service einen Befehl aus. Wählen Sie im Wizard von Catalog die modulare Architektur; für die übrigen wählen Sie die passende Architektur für eine einfache Grenze.

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

Während der Befehlsausführung fragt die CLI nach:

• Service-Name: zum Beispiel Catalog;
• Anzeigename und Architekturstil: wählen Sie eine einfache Architektur für kompakte Grenzen oder modular, wenn der Service unabhängige kohäsive Bereiche besitzt;
• Datenbank: wählen Sie die Technologie, die am besten zu Ihrem Projekt passt (SQL Server, PostgreSQL usw.);

Schritt 2: Module innerhalb von Services erstellen

Nicht alle Services müssen modular sein. In unserem Projekt hat nur der Service Catalog Module, um Verantwortlichkeiten wie Merchandising und Pricing zu trennen.

Für den Service Catalog definieren wir die folgenden Module:

• Merchandising – Verwaltung von Produkten und Kategorien;
• Pricing – Verwaltung von Preisen, Aktionen und Änderungshistorie.

Um die Module von Catalog zu erstellen, führen Sie aus:

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

Sie können innerhalb des modularen Dienstes beliebig viele Module erstellen Catalog. Darüber hinaus könnten je nach Komplexität einige Module in Zukunft zu eigenständigen Diensten werden. Die hier dargestellte Aufteilung dient lediglich didaktischen Zwecken und dient als Beispiel für eine modulare Organisation. Verwenden Sie Module nicht nur zum Erstellen von Ordnern. Verwenden Sie sie, wenn sie einen Geschäftsbereich mit eigenen Entitäten, Anwendungsfällen, APIs, Migrationen und Ereignissen schützen.

Endgültige Projektstruktur

Nach dem Erstellen der Dienste und Module sollte Ihre Lösung eine Struktur ähnlich der folgenden haben:

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/

Strukturerklärung:

• Services/: enthält alle Systemdienste, jeder isoliert mit eigener Geschäftslogik, Infrastruktur und Hosting;
• Modules/: Ordner innerhalb modularer Dienste, die es Ihnen ermöglichen, spezifische Funktionalitäten zu organisieren und zusammenhängenden Code zu pflegen;
• WebApps/: Mit dem System verbundene Frontends, bereits in Dienste integriert;
• Shared/: Bibliotheken und Ressourcen, die von Diensten und Frontends gemeinsam genutzt werden;
• tests/: Unit- und Integrationstests, organisiert nach Dienst und Modul.

Mit dieser modularen Struktur kann jedes Team oder jeder Entwickler unabhängig an verschiedenen Teilen des Systems arbeiten, was Skalierbarkeit, Wartung und Tests erleichtert. Nachdem Sie Dienste und Module erstellt haben, führen Sie sie aus dotnet build Um zu bestätigen, dass Projekte korrekt an die Lösung angehängt sind, hosten Sie Aspire, freigegebene Projekte und das Test-Framework.

Authentifizierung und Autorisierung hinzufügen

Authentifizierung und Autorisierung sind wesentliche Elemente jedes modernen Systems. Durch die Authentifizierung wird nachgewiesen, wer der Benutzer ist. Die Berechtigung definiert, was dieser Benutzer ausführen kann. In Lino CLI generiert die Authentifizierungsfunktion generiert die erforderliche Basis für Benutzer, Rollen, Berechtigungen, Token, Zugriffsrichtlinien und die Integration mit APIs.

Schritt 1: Ausführen des Authentifizierungsbefehls

Um Authentifizierungs- und Autorisierungsfunktionen hinzuzufügen, verwenden Sie den folgenden Befehl:

lino feature auth add

CLI führt Sie durch die folgenden Schritte:

• Wahl der Leistung oder des Moduls: Sie müssen angeben, wo die Authentifizierungsartefakte installiert werden. In unserem Beispielprojekt nutzen wir den Dienst Security, der die gesamte Sicherheitslogik des Systems zentralisiert;
• Zusätzliche Einstellungen: Erstellung von Tabellen mit Benutzern, Rollen, Berechtigungen, Token und Konfiguration von Zugriffsrichtlinien;
• Token-Lebensdauer: Definition des Ablaufs für access token und refresh token gemäß der Sicherheitsrichtlinie des Produkts;
• Typ der Benutzerkennung: Auswahl des Typs, der vom Benutzermodell und den generierten Verträgen verwendet wird.

Schritt 2: Generierte Struktur

Nach Ausführung des Befehls enthält der Dienst Security Dateien und Ordner wie:

• Domäne/Entitäten: Aggregate, Entitäten und Regeln für Benutzer, Rollen, Berechtigungen und Token;
• Infrastruktur/Persistenz: Datenbankkonfigurationen, Entity Framework-Zuordnungen und Migrationen für Security-Tabellen;
• Anwendung: Commands, Queries, Handlers, Authentifizierungsdienste, Token-Generierung, Anmeldeinformationsvalidierung und Berechtigungsprüfungen;
• API/Host: Endpunkte für Anmeldung, Abmeldung, Registrierung, refresh token und geschützte Vorgänge;
• Integration mit Web-App: Unterstützung für authentifizierte Abläufe, wenn eine Webanwendung vorhanden ist.

Damit verfügt Ihre Anwendung über eine robuste Authentifizierung und eine detaillierte Zugriffskontrolle, die mehrere Benutzer und unterschiedliche Berechtigungsebenen unterstützen kann. Dennoch sollte der generierte Code als solide Grundlage und nicht als abschließende Sicherheitsüberprüfung betrachtet werden. Überprüfen Sie vor der Produktion die Token-Lebensdauer, das Berechtigungsdesign, die Passwortrichtlinie, HTTPS, Geheimnisse, Ratenbegrenzung, Protokolle und Bereitstellungskonfigurationen.

Background Jobs hinzufügen

In verteilten und modularen Systemen, wie dem, mit dem wir bauen Lino CLIAllerdings kommunizieren nicht alle Dienste direkt miteinander. Um Konsistenz und Zuverlässigkeit beim Informationsaustausch zu gewährleisten, nutzen wir Integrationsereignisse. Um diese Ereignisse jedoch effizient und asynchron zu verarbeiten, benötigen wir Background Jobs.

Lino verwendet den Standard Outbox Pattern um sicherzustellen, dass alle von den Diensten generierten Nachrichten vor dem Versand zuverlässig aufgezeichnet werden. Damit haben wir Folgendes erreicht:

• Vermeiden Sie den Verlust von Ereignissen bei Dienstausfällen oder Neustarts.
• Stellen Sie sicher, dass dieselbe Nachricht nur einmal gesendet wird.
• Ermöglichen Sie die erneute Verarbeitung von Nachrichten im Falle eines Zustellungsfehlers.
• Trennen Sie die Ereignisverarbeitung von der Hauptanwendungslogik und verbessern Sie so die Leistung und Skalierbarkeit.

Schritt 1: Ausführen des Befehls

Um Ihrem Projekt Unterstützung für Background Jobs hinzuzufügen, führen Sie den folgenden Befehl aus:

lino feature background-job add

CLI fordert Sie auf, den Dienst auszuwählen, in dem der Background Job installiert werden soll. Im Allgemeinen wählen Sie den Dienst, der die Ereigniserzeugung zentralisiert, z. B. Catalog oder Sales. In den aktuellen Optionen kann der Assistent außerdem das Modul, die Jobbibliothek, ob Outbox-Ereignisse verarbeitet werden sollen, den Zeitplan und die Batchgröße abfragen. Der aktuelle Vorlagenfluss verwendet Hangfire für die Ausführung wiederkehrender Jobs.

Schritt 2: Konfigurieren der Ausführung

Während der Konfiguration können Sie Folgendes definieren:

• Prüfintervall: Legt fest, wie oft der Background Job die Tabelle überprüft Outbox für neue Nachrichten. Ein zu kurzes Intervall kann die Ressourcennutzung erhöhen, während ein zu langes Intervall die Ereigniszustellung verzögern kann.
• Stapel von gleichzeitig verarbeiteten Datensätzen: steuert, wie viele Ereignisse pro Lauf gelesen und gesendet werden. Größere Stapel können die Leistung steigern, erfordern jedoch mehr Speicher und Verarbeitung;
• Abrufrichtlinie: Falls das Senden von Nachrichten fehlschlägt, können Sie konfigurieren, wie oft der Job versucht, erneut zu senden.

Diese Parameter hängen von der Größe Ihres Systems, der Maschinenkapazität und dem erwarteten Ereignisaufkommen ab.

Schritt 3: Generierte Struktur

Nach der Konfiguration verfügt das Projekt über einen Background Job, der Nachrichten aus den Tabellen verarbeiten kann Outbox in jedem Dienst.

1. Der Anwendungsfall ändert die Domäne und zeichnet ein Domänen- oder Integrationsereignis auf.
2. Die Arbeitseinheit speichert die Geschäftsdaten und Nachrichten von Outbox in derselben Transaktion.
3. Hangfire führt wiederkehrende Jobs aus, die ausstehende Nachrichten stapelweise lesen.
4. Nachrichten werden an die konfigurierte Integrations-Engine wie RabbitMQ veröffentlicht, wenn die asynchrone Kommunikation aktiviert ist.
5. Abgeschlossene, fehlgeschlagene, alte oder hängengebliebene Nachrichten können von der für den Job generierten Logik und Konfiguration verarbeitet werden.

Dadurch wird sichergestellt, dass alle Integrationsereignisse zuverlässig und effizient verarbeitet werden, sodass mehrere Dienste und Module asynchron kommunizieren können, ohne die Leistung des Hauptsystems zu beeinträchtigen. Die wichtigste Betriebsregel besteht darin, die Transaktionsgrenze klar zu halten: Ereignisse, die über Outbox gesendet werden müssen, müssen im selben Transaktionsfluss erstellt werden wie die Geschäftsänderung, die sie darstellen.

Entitäten und Aufzählungen erstellen

In diesem Abschnitt gehen wir detailliert auf den Entwurf der Entitäten, Aufzählungen und Value Objects der Anwendung ein und zeigen, in welchen Diensten und Modulen jedes Element erstellt wird.

1. Erstellen der Entität Category

Um die Entität Category im Service Catalog und im Modul Merchandising zu erstellen, führen Sie aus:

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