Creare un'applicazione .NET completa con Lino: guida passo passo

Installazione e configurazione di Lino CLI

Il primo passo per iniziare a lavorare con il Lino CLI è installare lo strumento nel tuo ambiente di sviluppo. È distribuito come a strumento globale dotnet, il che significa che sarà disponibile per qualsiasi progetto.NET sul tuo computer. Prima dell'installazione, verificare che l'SDK.NET richiesto dai modelli attuali sia disponibile e che il terminale possa essere eseguito dotnet e che la directory degli strumenti globali.NET si trova nel file PATH.

Passaggio 1: installazione

Per installare (o aggiornare) Lino CLI, eseguire il seguente comando nel terminale:

dotnet tool install --global Tolitech.Lino

Note importanti:

• Se è già installata una versione, è possibile utilizzare dotnet tool update --global Tolitech.Lino aggiornare.
• Verificare che la directory degli strumenti globali.NET sia nel file PATH del sistema in modo che il comando lino funzionare correttamente.

Passaggio 2: configura la lingua

Dopo l'installazione, si consiglia di configurare la lingua (o la cultura) che CLI utilizzerà nei messaggi, nelle richieste e nei registri:

lino preferences culture set

Ti verrà chiesto di scegliere tra le lingue disponibili. Questa impostazione garantisce che tutte le istruzioni e i messaggi vengano visualizzati in modo coerente nella lingua desiderata. Questa preferenza modifica i messaggi, le richieste e le indicazioni localizzate CLI; non rinomina entità, servizi, moduli o termini commerciali generati nel progetto.

Passaggio 3: autenticazione e registrazione

Per accedere a tutte le funzionalità di Lino, inclusi modelli avanzati, pubblicazione di immagini Docker e integrazioni con servizi esterni, devi essere autenticato.

- Se non sei ancora registrato, registrati con il comando:

lino user register

- Se sei già registrato accedi con:

lino auth login

Che succede: CLI memorizza un token di autenticazione localmente, consentendoti di eseguire comandi che richiedono l'accesso a risorse protette senza dover accedere ogni volta che lo utilizzi. Mantieni questo token privato ed evita di condividere lo stesso profilo utente tra diversi sviluppatori, agenti CI o macchine.

Passaggio 4: verifica

Per confermare che l'installazione e l'autenticazione sono andate a buon fine, eseguire:

lino --version

Se il comando restituisce la versione installata, sei pronto per iniziare a utilizzare il file Lino CLI nei tuoi progetti

Creazione del progetto MyApp

In questo passaggio creeremo la struttura iniziale del progetto utilizzando il file Lino CLI. Questo progetto servirà come base per dimostrare la creazione di servizi, moduli, front-end e tutta l'integrazione degli eventi. Un progetto Lino non è solo una cartella con una soluzione: definisce convenzioni per i limiti del servizio, le librerie condivise, l'host Aspire, il framework frontend, i test, la gestione dei pacchetti, gli analizzatori e le configurazioni che i comandi successivi riutilizzano.

Passaggio 1: esecuzione del comando di creazione

Per creare un nuovo progetto, esegui il comando seguente nel terminale:

lino project new

CLI ti guiderà passo dopo passo, chiedendoti informazioni come:

• Nome del progetto: useremo MyApp, ma puoi scegliere il nome che preferisci;
• Funzionalità aggiuntive: analizzatori di codice, memorizzazione nella cache distribuita, supporto eventi asincroni, ecc.

Passaggio 2: configurazione delle funzionalità essenziali

Per questo progetto, ti consigliamo di abilitare le seguenti funzionalità fin dall'inizio:

• Analizzatori di codice: garantire che il codice segua buone pratiche e standard coerenti, prevenendo errori comuni di implementazione;
• Cache distribuita: migliora le prestazioni delle applicazioni in scenari con più servizi, evitando query inutili al database;
• Comunicazione asincrona: consente l'utilizzo di eventi e code per l'integrazione tra servizi, garantendo scalabilità e disaccoppiamento.

È importante abilitare tutte queste opzioni in questo progetto, poiché creeremo più servizi che comunicheranno attraverso eventi di integrazione. Questo ti permetterà di capire come strutturare sistemi modulari e distribuiti utilizzando Lino.

Passaggio 3: struttura generata

Dopo aver eseguito il comando e configurato le risorse, CLI genererà la struttura iniziale del progetto. Comprenderà:

• Cartelle servizi e moduli;
• Modelli front-end (se applicabile);
• Impostazioni iniziali della cache, eventi e integrazioni;
• File di soluzione (.slnx) e di progetto (.csproj) pronti per la compilazione.

Ora il tuo progetto La miaApp è pronto per ricevere i servizi, moduli, entità e front-end che configureremo nei prossimi passi. Prima di continuare, apri la soluzione generata ed esegui dotnet build per confermare che i riferimenti, i generatori di sorgenti, i modelli, i file di progetto e la configurazione iniziale siano coerenti.

Aggiunta dell'applicazione web Backoffice

Un sistema completo in genere necessita di almeno un'applicazione web per gestire il dominio. In questa guida l'applicazione viene chiamata Backoffice e rappresenta un'interfaccia interna per amministratori, manager o utenti operativi per monitorare prodotti, categorie, scorte, vendite e altre informazioni di sistema.

L'applicazione web non sostituisce i servizi di dominio. Agisce come punto di ingresso visivo per consumare API, attivare Commands, consultare Queries e visualizzare schermate coerenti con le regole già modellate nei servizi.

Passaggio 1: esecuzione del comando di creazione

Per aggiungere una nuova applicazione web al progetto, usare:

lino web-app new

L'alias lino webapp new è disponibile anche per rendere più rapida la digitazione. Durante l'esecuzione, indicare un nome chiaro per l'applicazione web; in questo esempio useremo Backoffice.

lino web-app new --name Backoffice

Passaggio 2: comprendere la struttura generata

Al termine del processo, Lino crea la struttura iniziale della Web App in src/WebApps/<WebAppName>. Per un'applicazione Blazor, la struttura può includere progetti server/client, risorse condivise, file di localizzazione, client per consumare le APIs e convenzioni che saranno usate in seguito da lino page new.

• Cartelle per pagine, componenti, layout, servizi e risorse applicative;
• Clienti HTTP e contratti richiesti per consumare API esposti dai servizi di progetto;
• Risorse di localizzazione e modelli iniziali utilizzati dall'esperienza web;
• Progetti client/server quando la tipologia di applicazione richiede questa separazione;
• Convenzioni di percorso, navigazione e integrazione che verranno riutilizzate nella generazione della pagina;
• Punti di integrazione con autenticazione e autorizzazione quando la funzionalità di autenticazione viene aggiunta al progetto.

Passaggio 3: quando creare l'app Web nel flusso

Se sai già che il sistema avrà un'interfaccia Blazor, crea la Web App subito all'inizio, dopo la creazione del progetto. In questo modo servizi, moduli, entità, APIs e pagine generati successivamente saranno già allineati con l'applicazione web che li consumerà.

Questo flusso è particolarmente utile perché i servizi creati in seguito generano anche progetti tipizzati Api.Contracts e Api.Client, consumati dal progetto Blazor. Con la Web App presente fin dall'inizio, diventa più semplice validare il percorso completo: dominio, API, contratti, HttpClient e schermata.

Note importanti

• Il Backoffice deve consumare i dati attraverso gli API generati, mantenendo la logica aziendale nei servizi e nei moduli corretti.
• Prima di esporre le pagine amministrative, rivedere l'autenticazione, l'autorizzazione, i ruoli, le autorizzazioni e le policy di accesso.
• È possibile creare più applicazioni Web, ad esempio a Backoffice interno e a Site pubblico, quando il pubblico, le autorizzazioni, le distribuzioni o le responsabilità sono diversi.
• Evita di mescolare flussi pubblici e amministrativi nella stessa app Web quando ciò rende difficili la sicurezza, la navigazione, la distribuzione o la proprietà del team.

Una volta creata l'applicazione web, la guida può passare ai servizi e ai moduli che forniranno i dati e le regole aziendali utilizzati da questa interfaccia.

Creazione di servizi e moduli

In questo passaggio costruiremo i servizi e i moduli che comporranno l'applicazione. L'obiettivo è creare un'architettura modulare e scalabile, consentendo a diverse aree del sistema, come prodotti, categorie, inventario, vendite e media, di evolversi in modo indipendente, mantenendo la coesione e facilitando la manutenzione. I servizi definiscono i limiti di distribuzione e persistenza; I moduli organizzano le aree aziendali all'interno di un servizio modulare. Prima di creare file, valuta quali parti del dominio necessitano di un proprio database, rilascio indipendente, accordo di integrazione o proprietà separata.

Passaggio 1: definizione dei servizi

Inizialmente creeremo i seguenti servizi, ciascuno con responsabilità ben definite:

• Catalog (modulare) – responsabile della gestione di prodotti, categorie e prezzi;
• Sales – responsabile del trattamento delle vendite e degli ordini;
• Stock – responsabile della gestione delle scorte e dei movimenti;
• Security – responsabile dell’autenticazione, autorizzazione e gestione degli utenti.

Per creare i servizi dell'esempio, eseguire un comando per ogni servizio. Nel wizard di Catalog, scegliere l'architettura modulare; per gli altri, scegliere l'architettura adatta a una frontiera semplice.

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

Durante l'esecuzione del comando, il CLI richiederà:

• Nome del servizio: per esempio, Catalog;
• Nome visualizzato e stile architetturale: scegliere un'architettura semplice per frontiere compatte oppure modulare quando il servizio ha aree coese indipendenti;
• Database: scegliere la tecnologia più adatta al progetto (SQL Server, PostgreSQL, ecc.);

Passaggio 2: Creazione di moduli dentro i servizi

Non tutti i servizi devono essere modulari. Nel nostro progetto, solo il servizio Catalog avrà moduli, per separare responsabilità come merchandising e pricing.

Definiamo i seguenti moduli per il servizio Catalog:

• Merchandising – gestione di prodotti e categorie;
• Pricing – gestione di prezzi, promozioni e storico delle modifiche.

Per creare i moduli di Catalog, eseguire:

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

Puoi creare tutti i moduli che desideri all'interno del servizio modulare Catalog. Inoltre, a seconda della complessità, alcuni moduli potrebbero in futuro diventare servizi indipendenti. La separazione qui presentata è solo a scopo didattico e serve come esempio di organizzazione modulare. Non utilizzare solo i moduli per creare cartelle; usali quando proteggono un'area aziendale con le proprie entità, casi d'uso, API, migrazioni ed eventi.

Struttura del progetto finale

Dopo aver creato i servizi e i moduli, la soluzione dovrebbe avere una struttura simile alla seguente:

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/

Spiegazione della struttura:

• Services/: contiene tutti i servizi di sistema, ciascuno isolato con una propria logica di business, infrastruttura e hosting;
• Modules/: cartelle all'interno di servizi modulari, che consentono di organizzare funzionalità specifiche e mantenere il codice coeso;
• WebApps/: frontend associati al sistema, già integrati con i servizi;
• Shared/: librerie e risorse condivise tra servizi e frontend;
• tests/: test unitari e di integrazione organizzati per servizio e modulo.

Con questa struttura modulare, ogni team o sviluppatore può lavorare in modo indipendente su diverse parti del sistema, facilitando scalabilità, manutenzione e test. Dopo aver creato servizi e moduli, esegui dotnet build per confermare che i progetti siano collegati correttamente alla soluzione, host Aspire, progetti condivisi e framework di test.

Aggiunta di autenticazione e autorizzazione

L'autenticazione e l'autorizzazione sono elementi essenziali di qualsiasi sistema moderno. L'autenticazione dimostra chi è l'utente; l'autorizzazione definisce ciò che questo utente può eseguire. En Lino CLI, la funzione di autenticazione genera la base necessaria per utenti, ruoli, autorizzazioni, token, policy di accesso e integrazione con API.

Passaggio 1: esecuzione del comando di autenticazione

Per aggiungere funzionalità di autenticazione e autorizzazione, utilizzare il comando:

lino feature auth add

CLI ti guiderà attraverso i seguenti passaggi:

• Scelta del servizio o del modulo: è necessario indicare dove verranno installati gli artefatti di autenticazione. Nel nostro progetto di esempio utilizziamo il servizio Security, che centralizza tutta la logica di sicurezza del sistema;
• Impostazioni aggiuntive: creazione di tabelle di utenti, ruoli, permessi, token e configurazione di policy di accesso;
• Durata dei token: definizione della scadenza per access token e refresh token in accordo con la policy di sicurezza del prodotto;
• Tipo di identificatore utente: scegliendo la tipologia utilizzata dal modello utente e dai contratti generati.

Passaggio 2: struttura generata

Dopo aver eseguito il comando, il servizio Security conterrà file e cartelle come:

• Dominio/entità: aggregati, entità e regole per utenti, ruoli, permessi e token;
• Infrastructure/Persistence: configurazioni del database, mapping di Entity Framework e migrations per le tabelle di sicurezza;
• Application: Commands, Queries, Handlers, servizi di autenticazione, generazione di token, convalida delle credenziali e controlli dei permessi;
• API/Host: endpoint per login, logout, registrazione, refresh token e operazioni protette;
• Integrazione con l'applicazione Web: supporto per flussi autenticati quando è presente un'applicazione web.

In questo modo, la tua applicazione disporrà di un'autenticazione solida e di un controllo granulare degli accessi, pronta a supportare più utenti e diversi livelli di autorizzazioni. Tuttavia, il codice generato dovrebbe essere trattato come una solida base, non come la revisione finale della sicurezza. Prima della produzione, esaminare la durata del token, la progettazione delle autorizzazioni, la politica delle password, HTTPS, i segreti, la limitazione della velocità, i log e le configurazioni di distribuzione.

Aggiunta di Background Jobs

In sistemi distribuiti e modulari, come quello con cui stiamo costruendo Lino CLI, non tutti i servizi comunicano direttamente tra loro. Per garantire coerenza e affidabilità nello scambio di informazioni, utilizziamo eventi di integrazione. Tuttavia, per elaborare questi eventi in modo efficiente e asincrono, abbiamo bisogno dei Background Jobs.

Lino utilizza lo standard Modello Outbox per garantire che tutti i messaggi generati dai servizi siano registrati in modo affidabile prima di essere inviati. Con questo abbiamo ottenuto:

• Evitare la perdita di eventi in caso di interruzioni o riavvii del servizio;
• Assicurarsi che lo stesso messaggio venga inviato una sola volta;
• Consentire la rielaborazione dei messaggi in caso di mancata consegna;
• Separare l'elaborazione degli eventi dalla logica dell'applicazione principale, migliorando le prestazioni e la scalabilità.

Passaggio 1: esecuzione del comando

Per aggiungere il supporto ai Background Jobs nel tuo progetto, esegui il comando:

lino feature background-job add

Il CLI ti chiederà di selezionare il servizio in cui verrà installato il Background Job. Generalmente sceglierai il servizio che centralizza la produzione di eventi, come Catalog o Sales. Nelle opzioni correnti, la procedura guidata può anche richiedere il modulo, la libreria di job, se gli eventi Outbox devono essere elaborati, la pianificazione e la dimensione del batch. Il flusso dei template correnti usa Hangfire per l'esecuzione ricorrente dei job.

Passaggio 2: configurazione dell'esecuzione

Durante la configurazione sarà possibile definire:

• Intervallo di controllo: determina la frequenza con cui il processo in background controllerà la tabella Outbox per i nuovi messaggi. Un intervallo troppo breve può aumentare l'utilizzo delle risorse, mentre un intervallo troppo lungo può ritardare la consegna degli eventi;
• Lotto di record elaborati alla volta: controlla il numero di eventi che verranno letti e inviati per esecuzione. Batch più grandi possono aumentare le prestazioni, ma richiedono più memoria ed elaborazione;
• Politica di recupero: In caso di mancato invio dei messaggi, è possibile configurare quante volte il lavoro tenterà di inviarli nuovamente.

Questi parametri dipendono dalle dimensioni del sistema, dalla capacità della macchina e dal volume previsto di eventi.

Passaggio 3: struttura generata

Dopo la configurazione, il progetto avrà un lavoro in background pronto per elaborare i messaggi dalle tabelle Outbox in ogni servizio.

1. Il caso d'uso cambia il dominio e registra un dominio o un evento di integrazione.
2. L'unità di lavoro salva i dati aziendali e i messaggi da Outbox nella stessa transazione.
3. Hangfire esegue job ricorrenti che leggono i messaggi in sospeso in batch.
4. I messaggi vengono pubblicati nel motore di integrazione configurato come RabbitMQ quando la comunicazione asincrona è abilitata.
5. I messaggi completati, non riusciti, vecchi o bloccati possono essere gestiti dalla logica e dalla configurazione generata per il lavoro.

Ciò garantisce che tutti gli eventi di integrazione vengano elaborati in modo affidabile ed efficiente, consentendo a più servizi e moduli di comunicare in modo asincrono, senza influire sulle prestazioni del sistema principale. La regola operativa più importante è mantenere chiaro il confine transazionale: gli eventi che devono essere inviati tramite Outbox devono essere creati nello stesso flusso transazionale del cambiamento aziendale che rappresentano.

Creazione di entità ed enumerazioni

In questa sezione descriveremo in dettaglio la progettazione delle entità, delle enumerazioni e dei Value Objects dell'applicazione, mostrando in quali servizi e moduli verrà creato ciascun elemento.

1. Creazione dell'entità Category

Per creare l'entità Category nel servizio Catalog e nel modulo Merchandising, eseguire:

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