Da zero alla build: guida passo passo

Installazione e configurazione di Lino CLI

Il primo passo per iniziare a lavorare con Lino CLI è installare lo strumento nel proprio ambiente di sviluppo. Viene distribuito come dotnet global tool, il che significa che sarà disponibile per qualsiasi progetto .NET sul tuo computer.

Passo 1: Installazione

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

dotnet tool install --global Tolitech.Lino

Note importanti:

• Se è già installata una versione, puoi usare dotnet tool update --global Tolitech.Lino per aggiornarla.
• Assicurati che la directory degli strumenti globali di .NET sia nel PATH del sistema, affinché il comando lino funzioni correttamente.

Passo 2: Configurare la lingua

Dopo l'installazione, si consiglia di configurare la lingua (o cultura) che il CLI utilizzerà per messaggi, prompt e log:

lino preferences culture set

Ti verrà chiesto di scegliere tra le lingue disponibili. Questa configurazione garantisce che tutte le istruzioni e i prompt vengano visualizzati in modo coerente nella lingua desiderata.

Passo 3: Autenticazione e registrazione

Per accedere a tutte le funzionalità di Lino, inclusi template avanzati, pubblicazione di immagini Docker e integrazione con servizi esterni, è necessario essere autenticati.

- Se non possiedi ancora un account, registrati con il comando:

lino user register

- Se hai già un account, effettua il login con:

lino auth login

Cosa succede: il CLI memorizza localmente un token di autenticazione, permettendoti di eseguire comandi che richiedono accesso a risorse protette senza dover effettuare il login ogni volta.

Passo 4: Verifica

Per confermare che l'installazione e l'autenticazione siano state eseguite correttamente, esegui:

lino --version

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

Creazione del progetto MyApp

In questo passaggio, creeremo la struttura iniziale del progetto utilizzando Lino CLI. Questo progetto servirà come base per dimostrare la creazione di servizi, moduli, front-end e l'integrazione degli eventi.

Passo 1: Esecuzione del comando di creazione

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

lino project new

Il CLI ti guiderà passo passo, richiedendo informazioni come:

• Nome del progetto: useremo MyApp, ma puoi scegliere qualsiasi nome tu voglia;
• Funzionalità aggiuntive: analizzatori di codice, cache distribuita, supporto per eventi asincroni, ecc.

Passo 2: Configurazione delle funzionalità principali

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

• Analizzatori di codice: per garantire che il codice segua le migliori pratiche e standard coerenti, prevenendo errori comuni di implementazione;
• Cache distribuita: migliora le prestazioni dell'applicazione in scenari con più servizi, evitando query non necessarie al database;
• Comunicazione asincrona: abilita l'uso 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 tra loro tramite eventi di integrazione. Questo ti permetterà di comprendere come strutturare sistemi modulari e distribuiti utilizzando Lino.

Passo 3: Struttura generata

Dopo aver eseguito il comando e configurato le funzionalità, il CLI genererà la struttura iniziale del progetto. Essa includerà:

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

Ora il tuo progetto MyApp è pronto per ricevere i servizi, moduli, entità e front-end che configureremo nei passaggi successivi.

Aggiunta del frontend

Ora andiamo a creare l’interfaccia del sistema, il frontend, che sarà utilizzato come Backoffice. Questo frontend non sarà un’applicazione pubblica, ma uno strumento interno affinché amministratori e responsabili possano gestire prodotti, categorie, inventari, vendite e altre informazioni del sistema.

Passo 1: Esecuzione del comando di creazione

Per aggiungere un nuovo frontend al progetto, utilizza il seguente comando nel terminale:

lino webapp new

Durante il processo la CLI richiederà alcune informazioni, come ad esempio:

• Nome dell’applicazione web: in questo esempio useremo Backoffice;

Passo 2: Struttura generata

Al termine del processo, la CLI genererà la struttura iniziale del frontend all’interno della cartella WebApps/Backoffice. La struttura predefinita include:

• Cartelle per pagine, componenti e servizi dell’applicazione;
• Client HTTP per consumare le API dei servizi del progetto;
• Template iniziali;
• File di configurazione per l’integrazione con autenticazione, autorizzazione ed eventi del sistema.

Note importanti

• Il frontend sarà automaticamente integrato con i servizi e i moduli selezionati, consentendo di consumare direttamente i dati di prodotti, categorie e vendite tramite le API generate da Lino.
• È possibile creare più frontend, ad esempio uno per gli amministratori (Backoffice) e un altro pubblico (Sito), seguendo lo stesso processo.

Con il frontend creato, siamo pronti a procedere con la creazione dei servizi e dei moduli che forniranno i dati e le regole di business per questa applicazione.

Creazione di servizi e moduli

In questa fase costruiremo i servizi e i moduli che comporranno l'applicazione. L'obiettivo è creare un'architettura modulare e scalabile, permettendo alle diverse aree del sistema, come prodotti, categorie, magazzino, vendite e media, di evolvere in modo indipendente, mantenendo coesione e facilitando la manutenzione.

Passo 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 dell'elaborazione di vendite e ordini;
• Stock – responsabile della gestione degli stock e dei movimenti;
• Security – responsabile dell'autenticazione, autorizzazione e gestione utenti.

Per creare un nuovo servizio, eseguire il comando:

lino service new

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

• Nome del servizio: ad esempio, Catalog;
• Database: scegli la tecnologia più adatta al tuo progetto (SQL Server, PostgreSQL, ecc.);

Passo 2: Creazione di moduli all'interno dei servizi

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

Abbiamo definito per il servizio Catalog i seguenti moduli:

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

Per creare un modulo, eseguire il comando:

lino module new

È possibile creare quanti moduli si desidera all'interno del servizio modulare Catalog. Inoltre, a seconda della complessità, alcuni moduli potrebbero diventare servizi indipendenti in futuro. La separazione mostrata qui è solo a scopo didattico ed è un esempio di organizzazione modulare.

Struttura finale del progetto

Dopo la creazione dei servizi e dei 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 del sistema, ciascuno isolato con propria logica di business, infrastruttura e hosting;
• Modules/: cartelle all'interno dei servizi modulari, per 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.

Aggiunta di autenticazione e autorizzazione

L'autenticazione e l'autorizzazione sono elementi essenziali di qualsiasi sistema moderno. In Lino CLI, aggiungerle al progetto è semplice e veloce.

Passo 1: Esecuzione del comando di autenticazione

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

lino features auth add

Il CLI ti guiderà attraverso i seguenti passaggi:

• Scelta del servizio o modulo: devi 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;
• Configurazioni aggiuntive: creazione di tabelle per utenti, ruoli e permessi e impostazione delle politiche di accesso.

Passo 2: Struttura generata

Dopo l’esecuzione del comando, il servizio Security conterrà file e cartelle come:

• Entities: classi per utenti, ruoli e permessi;
• Infrastructure: configurazioni del database e migrazioni per creare le tabelle;
• Application: servizi di autenticazione, gestione utenti e validazione delle credenziali;
• API/Host: endpoint per login, logout, registrazione e gestione dei ruoli.

Con questa configurazione, la tua applicazione avrà un’autenticazione robusta e un controllo granulare degli accessi, pronta a supportare più utenti e differenti livelli di permessi.

Aggiunta di Background Jobs

Nei sistemi distribuiti e modulari, come quello che stiamo costruendo con il 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 il Outbox Pattern per garantire che tutti i messaggi generati dai servizi vengano registrati in modo affidabile prima dell’invio. In questo modo possiamo:

• Evitarne la perdita in caso di errori o riavvii del servizio;
• Garantire che lo stesso messaggio venga inviato una sola volta;
• Consentire il rielaborazione dei messaggi in caso di errore nella consegna;
• Separare l’elaborazione degli eventi dalla logica principale dell’applicazione, migliorando prestazioni e scalabilità.

Passo 1: Esecuzione del comando

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

lino features background-job add

Il CLI ti chiederà di selezionare il servizio in cui verrà installato il Background Job. Di solito sceglierai il servizio che centralizza la produzione degli eventi, come Catalog o Sales.

Passo 2: Configurazione dell’esecuzione

Durante la configurazione, puoi definire:

• Intervallo di controllo: determina la frequenza con cui il Background Job controllerà la tabella Outbox per nuovi messaggi. Un intervallo troppo breve può aumentare l’utilizzo delle risorse, mentre un intervallo lungo può ritardare la consegna degli eventi;
• Dimensione del batch di record processati per volta: controlla quanti eventi verranno letti e inviati per ogni esecuzione. Batch più grandi possono migliorare le prestazioni, ma richiedono più memoria e potenza di calcolo;
• Politica di retry: in caso di fallimento nell’invio dei messaggi, puoi configurare quante volte il job tenterà di reinviare.

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

Passo 3: Struttura generata

Dopo la configurazione, il progetto avrà un Background Job pronto per elaborare i messaggi delle tabelle Outbox in ciascun servizio.

In questo modo si garantisce che tutti gli eventi di integrazione vengano processati in modo affidabile ed efficiente, consentendo a più servizi e moduli di comunicare in modo asincrono senza influire sulle prestazioni del sistema principale.

Creazione di entità e enumerazioni

In questa sezione, descriviamo nel dettaglio il design delle entità, delle enumerazioni e degli oggetti di valore dell'applicazione, mostrando in quali servizi e moduli verrà creato ciascun elemento.

1. Creazione dell'entità Category

Per creare l'entità, utilizzare il comando:

lino entity new

L'entità verrà creata nel servizio Catalog e nel modulo Merchandising con la seguente struttura:

┌────┬────┬───────────────┬────────┬────────┬──────────┬────────────────┐
│ PK │ FK │ Property name │ Type   │ Length │ Required │ Auto-increment │
├────┼────┼───────────────┼────────┼────────┼──────────┼────────────────┤
│ x  │    │ Id            │ Guid   │        │    x     │       x        │
├────┼────┼───────────────┼────────┼────────┼──────────┼────────────────┤
│    │    │ Name          │ string │   50   │    x     │                │
└────┴────┴───────────────┴────────┴────────┴──────────┴────────────────┘

2. Creazione dell'entità Product

Successivamente, creiamo l'entità Product nello stesso servizio e modulo, includendo oggetti di valore ed enumerazioni:

┌────┬────┬───────────────┬─────────────┬────────┬──────────┬────────────────┐
│ PK │ FK │ Property name │ Type        │ Length │ Required │ Auto-increment │
├────┼────┼───────────────┼─────────────┼────────┼──────────┼────────────────┤
│ x  │    │ Id            │ Guid        │        │    x     │       x        │
├────┼────┼───────────────┼─────────────┼────────┼──────────┼────────────────┤
│    │    │ Name          │ string      │  100   │    x     │                │
├────┼────┼───────────────┼─────────────┼────────┼──────────┼────────────────┤
│    │    │ Description   │ string      │  500   │    x     │                │
├────┼────┼───────────────┼─────────────┼────────┼──────────┼────────────────┤
│    │    │ Price         │ decimal     │        │    x     │                │
├────┼────┼───────────────┼─────────────┼────────┼──────────┼────────────────┤
│    │ x  │ CategoryId    │ Category    │        │    x     │                │
├────┼────┼───────────────┼─────────────┼────────┼──────────┼────────────────┤
│    │    │ Dimensions    │ ValueObject │        │          │                │
├────┼────┼───────────────┼─────────────┼────────┼──────────┼────────────────┤
│    │    │ Status        │ Enum        │        │    x     │                │
└────┴────┴───────────────┴─────────────┴────────┴──────────┴────────────────┘

2.1 Creazione dell'oggetto di valore ProductDimension

Questo oggetto di valore rappresenta le dimensioni del prodotto:

┌───────────────┬─────────┬────────┬──────────┐
│ Property name │ Type    │ Length │ Required │
├───────────────┼─────────┼────────┼──────────┤
│ Width         │ decimal │        │    x     │
├───────────────┼─────────┼────────┼──────────┤
│ Height        │ decimal │        │    x     │
├───────────────┼─────────┼────────┼──────────┤
│ Depth         │ decimal │        │    x     │
└───────────────┴─────────┴────────┴──────────┘

2.2 Creazione dell'enum ProductStatus

Questo enum definisce lo stato del prodotto:

┌───────┬──────────────┬──────────────┐
│ Value │ Name         │ Display Name │
├───────┼──────────────┼──────────────┤
│ 1     │ Active       │ Active       │
├───────┼──────────────┼──────────────┤
│ 2     │ Inactive     │ Inactive     │
├───────┼──────────────┼──────────────┤
│ 3     │ Discontinued │ Discontinued │
└───────┴──────────────┴──────────────┘

3. Aggiunta di nuove proprietà

Con l'evoluzione del progetto, possiamo modificare le entità esistenti per aggiungere nuove proprietà. Ad esempio, aggiungeremo un elenco di immagini all'entità Product:

lino entity edit

Creando la proprietà Images di tipo List<ProductImage>, otterremo la seguente struttura:

┌────┬────┬───────────────┬────────────────────┬────────┬──────────┬────────────────┐
│ PK │ FK │ Property name │ Type               │ Length │ Required │ Auto-increment │
├────┼────┼───────────────┼────────────────────┼────────┼──────────┼────────────────┤
│ x  │    │ Id            │ Guid               │        │    x     │       x        │
├────┼────┼───────────────┼────────────────────┼────────┼──────────┼────────────────┤
│    │    │ Name          │ string             │  100   │    x     │                │
├────┼────┼───────────────┼────────────────────┼────────┼──────────┼────────────────┤
│    │    │ Description   │ string             │  500   │    x     │                │
├────┼────┼───────────────┼────────────────────┼────────┼──────────┼────────────────┤
│    │    │ Price         │ decimal            │        │    x     │                │
├────┼────┼───────────────┼────────────────────┼────────┼──────────┼────────────────┤
│    │ x  │ CategoryId    │ EntityId           │        │    x     │                │
├────┼────┼───────────────┼────────────────────┼────────┼──────────┼────────────────┤
│    │    │ Dimensions    │ ValueObject        │        │          │                │
├────┼────┼───────────────┼────────────────────┼────────┼──────────┼────────────────┤
│    │    │ Status        │ Enum               │        │    x     │                │
├────┼────┼───────────────┼────────────────────┼────────┼──────────┼────────────────┤
│    │ x  │ Images        │ List<ProductImage> │        │          │                │
└────┴────┴───────────────┴────────────────────┴────────┴──────────┴────────────────┘

3.1 Creazione dell'entità ProductImage

Questa entità appartiene all'aggregato Product e ha la seguente struttura:

┌────┬────┬───────────────┬────────────────┬────────┬──────────┬────────────────┐
│ PK │ FK │ Property name │ Type           │ Length │ Required │ Auto-increment │
├────┼────┼───────────────┼────────────────┼────────┼──────────┼────────────────┤
│ x  │    │ Id            │ Guid           │        │    x     │       x        │
├────┼────┼───────────────┼────────────────┼────────┼──────────┼────────────────┤
│    │ x  │ ProductId     │ EntityId       │        │    x     │                │
├────┼────┼───────────────┼────────────────┼────────┼──────────┼────────────────┤
│    │    │ UploadDate    │ DateTimeOffset │        │    x     │                │
├────┼────┼───────────────┼────────────────┼────────┼──────────┼────────────────┤
│    │    │ Image         │ File           │        │    x     │                │
└────┴────┴───────────────┴────────────────┴────────┴──────────┴────────────────┘

4. Creazione di entità per altri servizi

Nel servizio Sales, creiamo l'entità ProductSnapshot, che sarà popolata dagli eventi di integrazione. Poiché l'Id originale dell'entità Product proviene dal servizio Catalog, qui non può essere auto-incrementale.

┌────┬────┬───────────────┬─────────┬────────┬──────────┬────────────────┐
│ PK │ FK │ Property name │ Type    │ Length │ Required │ Auto-increment │
├────┼────┼───────────────┼─────────┼────────┼──────────┼────────────────┤
│ x  │    │ Id            │ Guid    │        │    x     │                │
├────┼────┼───────────────┼─────────┼────────┼──────────┼────────────────┤
│    │    │ Name          │ string  │  100   │    x     │                │
├────┼────┼───────────────┼─────────┼────────┼──────────┼────────────────┤
│    │    │ Price         │ decimal │        │    x     │                │
└────┴────┴───────────────┴─────────┴────────┴──────────┴────────────────┘

Nota: solo i campi essenziali sono stati replicati in ProductSnapshot per il servizio Sales. Entità aggiuntive come Customer, Order e StockItem non saranno dettagliate qui per semplificare la documentazione.

Creazione di eventi e relativi gestori

Ricapitolando, nella sezione precedente abbiamo creato nel servizio modulare Catalog.Merchandising le entità Product, Category e ProductImage, mentre nel servizio Sales abbiamo creato l'entità ProductSnapshot.

Ora creeremo eventi di dominio ed eventi di integrazione. L'obiettivo è che, quando vengono creati o aggiornati prodotti nel servizio Catalog, queste modifiche vengano replicate ai servizi consumatori come Sales e Stock.

1. Creazione di eventi di dominio

Il primo passo è creare gli eventi di dominio ProductCreated e ProductUpdated con il comando:

lino event new

Durante la creazione, è possibile associare l'evento a un gestore e contemporaneamente configurare il trigger di un evento di integrazione. Questo centralizza la creazione dell'intero flusso necessario.

┌──────────────────────────────────────────────────────┬────────────────────────────────┐
│ Question                                             │ Answer                         │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Select a service:                                    │ Catalog                        │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Select a module:                                     │ Merchandising                  │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Select a entity:                                     │ Product                        │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Select the event type:                               │ Domain Event                   │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Enter the name of the event:                         │ ProductCreated                 │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Do you want to create an associated event handler?   │ Yes                            │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Trigger a integration event?                         │ Yes                            │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Choose the integration event to be triggered:        │ (Create new integration event) │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Enter the name of the event:                         │ ProductCreated                 │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Which model will be used for this integration event? │ Creation model                 │
└──────────────────────────────────────────────────────┴────────────────────────────────┘

Allo stesso modo, creiamo l'evento ProductUpdated:

┌──────────────────────────────────────────────────────┬────────────────────────────────┐
│ Question                                             │ Answer                         │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Select a service:                                    │ Catalog                        │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Select a module:                                     │ Merchandising                  │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Select a entity:                                     │ Product                        │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Select the event type:                               │ Domain Event                   │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Enter the name of the event:                         │ ProductUpdated                 │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Do you want to create an associated event handler?   │ Yes                            │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Trigger a integration event?                         │ Yes                            │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Choose the integration event to be triggered:        │ (Create new integration event) │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Enter the name of the event:                         │ ProductUpdated                 │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Which model will be used for this integration event? │ Update model                   │
└──────────────────────────────────────────────────────┴────────────────────────────────┘

Con questo, otteniamo:

• Eventi di dominio creati (ProductCreated e ProductUpdated);
• Gestori di eventi di dominio corrispondenti;
• Eventi di integrazione registrati automaticamente nell'Outbox dal gestore degli eventi di dominio.

2. Creazione dei gestori degli eventi di integrazione

Il passo successivo è definire quali servizi consumeranno gli eventi di integrazione. Per farlo, utilizziamo:

lino event-handler new

Il flusso di creazione prevede:

• Selezionare il servizio, il modulo e l'entità che conterrà il gestore;
• Selezionare l'evento di integrazione da consumare e da quale servizio/modulo/entità proviene.

Ad esempio, nel servizio Sales creiamo i gestori per ProductCreated e ProductUpdated che consumeranno gli eventi emessi da Catalog.Merchandising.Product:

┌────────────────────────────────────────────┬───────────────────┐
│ Question                                   │ Answer            │
├────────────────────────────────────────────┼───────────────────┤
│ Select a service:                          │ Sales             │
├────────────────────────────────────────────┼───────────────────┤
│ Select a entity:                           │ ProductSnapshot   │
├────────────────────────────────────────────┼───────────────────┤
│ Select the event type:                     │ Integration Event │
├────────────────────────────────────────────┼───────────────────┤
│ Select the event's service to be consumed: │ Catalog           │
├────────────────────────────────────────────┼───────────────────┤
│ Select the event's module to be consumed:  │ Merchandising     │
├────────────────────────────────────────────┼───────────────────┤
│ Select the event's entity to be consumed:  │ Product           │
├────────────────────────────────────────────┼───────────────────┤
│ Choose the event to be consumed:           │ ProductCreated    │
├────────────────────────────────────────────┼───────────────────┤
│ Enter the name of the event handler:       │ ProductCreated    │
└────────────────────────────────────────────┴───────────────────┘

┌────────────────────────────────────────────┬───────────────────┐
│ Question                                   │ Answer            │
├────────────────────────────────────────────┼───────────────────┤
│ Select a service:                          │ Sales             │
├────────────────────────────────────────────┼───────────────────┤
│ Select a entity:                           │ ProductSnapshot   │
├────────────────────────────────────────────┼───────────────────┤
│ Select the event type:                     │ Integration Event │
├────────────────────────────────────────────┼───────────────────┤
│ Select the event's service to be consumed: │ Catalog           │
├────────────────────────────────────────────┼───────────────────┤
│ Select the event's module to be consumed:  │ Merchandising     │
├────────────────────────────────────────────┼───────────────────┤
│ Select the event's entity to be consumed:  │ Product           │
├────────────────────────────────────────────┼───────────────────┤
│ Choose the event to be consumed:           │ ProductUpdated    │
├────────────────────────────────────────────┼───────────────────┤
│ Enter the name of the event handler:       │ ProductUpdated    │
└────────────────────────────────────────────┴───────────────────┘

In questo modo, abbiamo due gestori di eventi di integrazione nel servizio Sales, che consumano solo i campi necessari dagli eventi di integrazione provenienti da Catalog.Merchandising. Questo assicura che le tabelle replicate contengano solo i dati essenziali, ottimizzando spazio e prestazioni.

Generazione di pagine web, API, Commands e Queries

Uno dei grandi vantaggi di Lino CLI è la possibilità di creare in modo integrato pagine web, API, Commands e Queries automaticamente, semplificando l’intero flusso di sviluppo. Per iniziare, basta eseguire il comando:

lino page new

Durante il processo, eseguirai le seguenti operazioni:

• Selezionare il servizio, il modulo e l’entità da esporre;
• Scegliere i campi che faranno parte della lista;
• Generare automaticamente le pagine di elenco (griglia con paginazione) e i form di creazione/modifica;
• Generare le classi HttpClient per l’uso nel frontend;
• Creare tutte le API REST necessarie (POST, PUT, PATCH, DELETE e GET);
• Creare Commands e Queries con i rispettivi Handlers, che interagiscono con il database garantendo il flusso completo di CRUD.

Con questo comando, ottieni un’applicazione funzionante senza dover scrivere manualmente il layer di interfaccia, le API e la logica di business, mantenendo standard e coerenza tra i servizi.

Per questo progetto, possiamo generare pagine integrate per le seguenti entità:

• Catalog.Merchandising.Category
• Catalog.Merchandising.Product
• Sales.ProductSnapshot

Dopo aver generato pagine, API e Commands/Queries, l’applicazione sarà pronta per interagire completamente tra frontend e backend, con validazioni, rotte e persistenza già configurate automaticamente da Lino CLI.

Creazione delle migrazioni del database

Ora che tutte le entità sono state create, è il momento di generare le migrazioni affinché i database vengano creati o aggiornati secondo il modello definito. Lino CLI automatizza questo processo, integrandosi con Entity Framework e creando script pronti all’esecuzione.

Per creare una nuova migrazione, eseguire il comando:

lino database migrations new

Durante l’esecuzione, sarà necessario:

• Selezionare il servizio e il modulo che riceveranno la migrazione;
• Fornire una descrizione per la migrazione, ad esempio "Initial migration".

┌───────────────────────────────────────────┬───────────────────┐
│ Question                                  │ Answer            │
├───────────────────────────────────────────┼───────────────────┤
│ Select a service:                         │ Catalog           │
├───────────────────────────────────────────┼───────────────────┤
│ Select a module:                          │ Merchandising     │
├───────────────────────────────────────────┼───────────────────┤
│ Current version of the service:           │ 0.1.0             │
├───────────────────────────────────────────┼───────────────────┤
│ Provide a description for this migration: │ Initial migration │
└───────────────────────────────────────────┴───────────────────┘

Dopo la conferma, Lino CLI genererà:

• Una nuova migrazione del database per la versione corrente del servizio;
• Uno script SQL corrispondente, posizionato nel layer Infrastructure.Persistence, nel percorso /scripts/<version>/<nome file>;
• La registrazione della versione della migrazione nella cronologia del servizio, garantendo tracciabilità e coerenza.

Buone pratiche:

• Creare nuove migrazioni ogni volta che il modello dei dati cambia (nuove entità, proprietà o modifiche alle relazioni);
• Revisionare gli script SQL generati prima di applicarli in produzione;
• Mantenere il controllo di versione del database allineato con la versione dell’applicazione, evitando conflitti e problemi di sincronizzazione.

Seguendo questo flusso, si garantisce che il database sia sempre aggiornato e coerente con il modello di dominio definito in Lino CLI, riducendo errori e semplificando la manutenzione.

Generazione di immagini Docker

Dopo aver completato la generazione del codice per una versione specifica, effettuato i test e implementato tutte le regole di business necessarie, è possibile generare immagini Docker per i servizi e le applicazioni web del progetto, da pubblicare successivamente in un registro di container.

Lino CLI semplifica questo processo con il comando:

lino build

Durante l’esecuzione, vedrete un elenco di tutti i servizi e le applicazioni web disponibili nel progetto, insieme alle loro versioni correnti:

Select the services or web applications you want to include in the build:

> [ ] Services
    [ ] Catalog |0.1.0|
    [ ] Sales |0.1.0|
    [ ] Security |0.1.0|
    [ ] Stock |0.1.0|
  [ ] Web applications
    [ ] Backoffice |0.1.0|

Potete selezionare uno o più servizi e applicazioni web per generare le immagini simultaneamente, semplicemente contrassegnando gli elementi desiderati.

Successivamente, vi verrà chiesto come aggiornare la versione delle immagini generate. Le opzioni disponibili sono:

• Mantieni la versione corrente – non modifica la versione esistente;
• Patch – incrementa la versione patch (es.: 0.1.0 → 0.1.1);
• Minor – incrementa la versione minor (es.: 0.1.0 → 0.2.0);
• Major – incrementa la versione major (es.: 0.1.0 → 1.0.0).

Dopo aver selezionato i servizi e definito l’incremento di versione, Lino CLI esegue:

• Build del codice di ogni servizio e applicazione web;
• Generazione dell’immagine Docker corrispondente;
• Applicazione del tag con la versione definita;
• Rendere le immagini disponibili per la pubblicazione nel vostro registro di container.

Al termine del processo, considerando che tutti i servizi e applicazioni web siano stati selezionati, le immagini generate avranno la seguente struttura:

• my-app/services/catalog-host - tag: 0.1.0
• my-app/services/sales-api - tag: 0.1.0
• my-app/services/security-api - tag: 0.1.0
• my-app/services/stock-api - tag: 0.1.0
• my-app/webapps/backoffice - tag: 0.1.0

Nota: Questo processo garantisce coerenza tra il codice e la versione delle immagini Docker, facilitando il deploy e la manutenzione di più ambienti, oltre a permettere che ogni servizio sia isolato in container indipendenti.

Creazione delle versioni nell’applicazione

Incrementare nuove versioni per i servizi o le applicazioni web è un processo semplice e centralizzato in Lino CLI. Basta eseguire il comando:

lino version bump

Come per la generazione delle immagini Docker, eseguendo questo comando vedrete un elenco completo di tutti i servizi e le applicazioni web del progetto. Solo gli elementi selezionati avranno la versione incrementata, mentre gli altri rimarranno invariati.

Select the services or web applications that will have version changes:

> [ ] Services
    [ ] Catalog |0.1.0|
    [ ] Sales |0.1.0|
    [ ] Security |0.1.0|
    [ ] Stock |0.1.0|
  [ ] Web applications
    [ ] Backoffice |0.1.0|

Dopo aver selezionato gli elementi desiderati, vi verrà chiesto di scegliere il tipo di incremento della versione. Le opzioni disponibili sono:

• Patch – piccole correzioni senza impatto funzionale;
• Minor – aggiunta di nuove funzionalità compatibili con le versioni precedenti;
• Major – modifiche che possono rompere la compatibilità con le versioni precedenti.

È importante notare che le versioni dei servizi e delle applicazioni web hanno un impatto diretto su:

• I tag delle immagini Docker;
• Le cartelle utilizzate per memorizzare gli script generati dalle migrazioni del database;
• Il controllo delle release e la cronologia del progetto.

Con questo, concludiamo la guida passo passo a tutti i comandi essenziali per la costruzione di un progetto web utilizzando Lino CLI, dall’installazione, creazione di servizi, entità, eventi e pagine, fino alla generazione di immagini Docker e al versionamento.

Non dimenticate di seguire il nostro canale YouTube per tutorial dettagliati, dimostrazioni pratiche e suggerimenti sull’uso dello strumento, dalle operazioni di base alle funzionalità avanzate.