Creazione di applicazioni Web

Architettura frontend con app Web Blazor

Le applicazioni Web generate da Lino connettono gli utenti ai casi d'uso del backend attraverso un'interfaccia reale, non solo tramite chiamate effettuate agli strumenti API. L'attuale tipo di frontend nativo è Applicazione Web Blazor, predisposto per applicazioni amministrative, portali pubblici, back office, aree partner e interfacce specifiche del dominio.

lino web-app new --name <WebAppName>

nl comando deve essere eseguito all'interno di un progetto Lino. Richiede il nome della Web App, utilizza il template Blazor Web App, conferma i dati selezionati, crea i file necessari ed esegue i comandi che collegano il frontend alla soluzione. La forma canonica è web-app. Gli alias webapp E web esistono per la produttività, ma è preferibile la documentazione e gli esempi lino web-app new per mantenere la coerenza.

Cosa viene generato

Un'app Web Blazor generata da Lino non è solo una cartella sciolta di schermate. Si adatta alla stessa soluzione.NET e segue l'organizzazione modulare utilizzata dal backend, separando le responsabilità tra host, client, componenti condivisi e progetti di interfaccia utente per servizio o modulo.

• Progetto server: ospita l'app Web Blazor, mappa i componenti root, configura le impostazioni predefinite del servizio, le risorse statiche, l'antifalsificazione, i servizi HTTPS, MudBlazor e le modalità di rendering interattive.
• Progetto cliente: concentra i componenti in esecuzione sul lato WebAssembly, routing, layout, struttura dei menu, impostazioni del browser, funzionalità di localizzazione e integrazione con MudBlazor.
• Progetto WebApp condivise: centralizza le risorse comuni dell'interfaccia utente, le notifiche, le finestre di dialogo, i modelli di stringhe di query, i risultati dei client, i servizi di cultura/fuso orario e componenti riutilizzabili.
• Progettazioni dell'interfaccia utente per servizio e modulo: quando la soluzione dispone di servizi e moduli, Lino crea progetti frontend all'interno del framework dell'app Web per mantenere pagine, menu e risorse isolati dal contesto.

n registri host generati AddInteractiveServerComponents E AddInteractiveWebAssemblyComponents. n componenti della radice HeadOutlet E Routes utilizzo InteractiveAuto, consentendo all'applicazione di avviarsi con l'interattività tramite il server e di migrare a WebAssembly quando il runtime del client è disponibile.

Integrazione con il backend APIs

uuando esiste un'app Web, Lino mantiene il backend preparato per l'utilizzo digitato dal frontend. Servizi e moduli possono ricevere progetti Api.Contracts E Api.Client, esponendo i contratti di richiesta/risposta e i client digitati agli endpoint generati.

• L'interfaccia utente non ha bisogno di assemblare manualmente le chiamate HTTP non elaborate per ciascuna funzionalità.
• Le pagine generate chiamano client API digitati e funzionano con modelli di richiesta e risposta creati insieme al backend.
• Modelli condivisi come ClientResult, uueryParams E PageduueryParams standardizzare la gestione dei risultati, i filtri, l'impaginazione e il feedback visivo.
• Questa integrazione tramite un HttpClient tipizzato mantiene il frontend allineato a contratti, autorizzazioni, messaggi di validazione e culture usate dal resto della soluzione.

nl flusso pratico è:

Pagina Blazor -> client API tipizzato -> endpoint Minimal API -> Command/uuery -> database

uuesto percorso preserva la coerenza dell'intero stack: il modello di dominio, i casi d'uso, gli endpoint, i contratti, l'interfaccia localizzata, la navigazione e le autorizzazioni seguono le stesse convenzioni del progetto.

Funzionalità dell'interfaccia utente incluse

La Web App generata è già predisposta per le preoccupazioni comuni delle applicazioni reali:

• Instradamento dei componenti Routes.razor generato.
• Layout, navigazione e componenti visivi basati su MudBlazor.
• Generazione di menu dalle pagine disponibili in ciascun servizio o modulo.
• File .resx individuare i testi nelle culture configurate nel progetto.
• Supporta l'autenticazione, l'archiviazione dei token, i percorsi protetti e i servizi di autorizzazione quando la funzione di autenticazione è abilitata.
• Menu sensibili all'autorizzazione, che visualizzano le voci solo quando l'utente corrente dispone dell'autorizzazione richiesta.

Frontend multipli

Un singolo backend può supportare più di un'app Web. Ciò è utile quando segmenti di pubblico diversi necessitano di navigazione, sicurezza, esperienza e distribuzione diverse, ma devono continuare a condividere gli stessi servizi, moduli, casi d'uso e API.

• Sito web pubblico: pagine accessibili a clienti, visitatori o utenti non ancora autenticati.
• Backoffice/Amministrazione: pannello di gestione interno per operatori, team di supporto e amministrativi.
• Portale partner: Accesso limitato per partner, rivenditori, fornitori o integrazioni operative.
• Zona self-service: esperienza focalizzata sul cliente finale, con menù e permessi propri.

Ogni frontend può evolversi con i propri layout, risorse, menu e regole di accesso, mentre il backend rimane organizzato per servizi, moduli, casi d'uso e contratti.

Generazione di pagine web

Dopo aver modellato l'entità, definito i casi d'uso e generato comandi, query, endpoint e persistenza, il passaggio successivo è solitamente quello di esporre la funzionalità nell'interfaccia. Lino automatizza questo passaggio con il generatore di pagine:

lino page new --service <ServiceName> --module <ModuleName> --entity <EntityName> --webapp <WebAppName>
lino page edit --service <ServiceName> --module <ModuleName> --entity <EntityName> --webapp <WebAppName>
lino page list --service <ServiceName> --module <ModuleName> --entity <EntityName> --webapp <WebAppName>

Le opzioni possono anche essere informate in modo interattivo. nl comando richiede il servizio, il modulo, l'entità, l'app Web di destinazione, il tipo di pagina e le proprietà che dovrebbero essere visualizzati nella griglia. nl tipo più comune è CRUDO; quando l'entità supporta solo la query, Lino può generare una pagina simile DataGrid.

Utilizzo page new per creare la prima versione dello schermo, page edit quando la pagina deve tenere traccia delle modifiche ai campi, ai contratti o al comportamento e page list per capire cosa è già stato generato per un'entità.

Flusso consigliato

1. Creare o selezionare l'app Web con lino web-app new.
2. Modella l'entità e genera casi d'uso, query, comandi, endpoint, contratti API e artefatti di persistenza.
3. Correre lino page new e seleziona l'entità che riceverà l'interfaccia.
4. Scegli con attenzione i campi nella griglia. Diventano colonne visibili e aiutano a impostare parametri di query, filtri e impaginazione.
5. Esegui la soluzione tramite AppHost per convalidare insieme interfaccia utente, API, autenticazione, autorizzazioni e integrazione del database.

Struttura generata

Per una pagina CRUD, Lino crea un pacchetto di pagine Blazor completo invece di un singolo file Razor:

• Registra la pagina o l'indice coordinando l'elenco, la creazione, la modifica, i dettagli e l'eliminazione.
• Componente della griglia basato su MudBlazor, con caricamento lato server, impaginazione, filtri e mappatura per i parametri di query.
• Componente del modulo con ViewModel digitato ed estensioni per mappare le richieste di creazione, aggiornamento e get-by-id.
• Risorse per titoli, etichette, pulsanti, messaggi di convalida e testi dell'interfaccia localizzati.
• Verifiche delle autorizzazioni quando l'autenticazione è abilitata, inclusa la convalida dell'accesso alla pagina e i pulsanti condizionali.

Creazione di una pagina CRUD per l'entità Vehicle, ad esempio, nel servizio Fleet, modulo Operations e applicazione Web Backoffice, la struttura segue questo formato:

src/WebApps/Backoffice/Services/Fleet/Operations/Pages/Vehicles/Registration/
├── Vehicle.razor
├── Vehicle.razor.cs
├── Resources/
│   ├── VehicleResources.resx
│   └── VehicleResources.Designer.cs
└── Components/
    ├── Form/
    │   ├── VehicleForm.razor
    │   ├── VehicleForm.razor.cs
    │   ├── VehicleFormExtensions.cs
    │   ├── VehicleViewModel.cs
    │   └── Resources/
    │       ├── VehicleFormResources.resx
    │       └── VehicleFormResources.Designer.cs
    └── Grid/
        ├── VehicleGrid.razor
        ├── VehicleGrid.razor.cs
        ├── VehicleGridExtensions.cs
        ├── VehiclePageduueryParams.cs
        └── Resources/
            ├── VehicleGridResources.resx
            └── VehicleGridResources.Designer.cs

L'idea preserva la struttura precedente utilizzata in esempi come Order: pagina principale, code-behind, componenti del modulo, componenti della griglia, estensioni e parametri impaginati. La versione attuale aggiunge funzionalità e integrazione esplicita con l'organizzazione tramite Web App, servizio e modulo.

Come funziona la pagina generata

La pagina utilizza gli stessi contratti generati per API. La griglia trasforma filtri e impaginazione in una richiesta di quotazione; il form trasforma il ViewModel in richieste di creazione o aggiornamento; il client digitato API invia la chiamata all'endpoint corrispondente. L'endpoint esegue il comando o la query generata e restituisce una risposta digitata all'interfaccia utente.

Frontend -> API -> Commands/uueries -> database

uuando esiste l'autorizzazione, il codice generato controlla anche le autorizzazioni come l'elenco, la creazione, la modifica, l'eliminazione e l'interrogazione per identificatore. Ciò influisce sia sull'accesso alla pagina che sulla visibilità delle azioni per l'utente.

nl risultato è un flusso completo e coerente: modello di dominio, caso d'uso, endpoint, client tipizzato, interfaccia utente localizzata, navigazione e autorizzazioni seguono le stesse convenzioni di progettazione. nl generatore riduce la ripetizione, ma i componenti rimangono modificabili per adattamenti del prodotto, usabilità e regole specifiche.

Interfaccia multilingue

Le applicazioni Web generate da Lino utilizzano file .resx per testi localizzati. Ciò consente di mantenere la stessa struttura Razor e di variare titoli, etichette, pulsanti, messaggi di errore, testi di convalida e descrizioni a seconda della cultura attiva.

La posizione non dovrebbe essere trattata come una finitura visiva. Nelle pagine amministrative e nei portali operativi, i termini incoerenti creano dubbi sulla regola aziendale. Pertanto, le risorse fanno parte dell'architettura dell'interfaccia utente e devono accompagnare pagine, moduli, griglie e componenti condivisi.

• Mantieni i tasti stabili, descrittivi e orientati al significato, evitando nomi legati al layout temporaneo dello schermo.
• Evita testo hardcoded su pagine e componenti; utilizzare le risorse per etichette, messaggi, titoli, breadcrumb, menu e conferme.
• Esaminare i termini tecnici per mantenere la coerenza tra la documentazione, i contratti CLn, API e l'interfaccia.
• Conserva lo stesso set di chiavi in ​​tutte le culture per evitare fallback imprevisti o schermate parzialmente tradotte.
• Separare la traduzione letterale dall'adattamento del prodotto: quando un termine deve essere localizzato per l'utente finale, mantenere il significato funzionale dell'azione.

Nelle pagine generate, in genere sono presenti risorse a livello di pagina, modulo e griglia. Questa separazione consente a ciascuna parte di evolversi senza mescolare testi di elenco, modifica, convalida e navigazione.

CRUD reattivo e pronto all'uso

nl CRUD generato accelera la consegna perché crea le basi ripetitive della schermata: elenco, modulo, integrazione con API, risorse, impaginazione, filtri, azioni e code-behind. Tuttavia, dovrebbe essere rivisto come un'esperienza di prodotto, non solo come un'impalcatura tecnica.

Una buona schermata CRUD deve consentire all'utente di trovare record, comprendere lo stato corrente, intraprendere azioni con sicurezza e ripristinare gli errori. uuesto vale sia per gli schermi interni del back office che per i portali rivolti a clienti o partner.

• Scegli colonne di elenco che aiutano il processo decisionale; evitare griglie con campi tecnici che non dicono nulla all'operatore.
• Configura filtri e impaginazione in base al volume di dati previsto e ai principali criteri di ricerca dell'utente.
• Esamina le convalide e i messaggi di errore per spiegare il problema nel linguaggio del dominio, non solo in termini di implementazione.
• Garantisci gli stati vuoto, caricamento e arresto anomalo per evitare schermate silenziose quando non sono presenti dati, API richiede tempo o un'operazione non viene completata.
• Confermare le eliminazioni e le operazioni irreversibili, chiarendo quale record sarà interessato.
• Mostra un feedback chiaro dopo aver salvato, modificato, eliminato o fallito utilizzando notifiche e messaggi localizzati.
• Proteggi le azioni tramite autorizzazione sul backend e sul frontend; nascondere i pulsanti migliora l'esperienza, ma non sostituisce la vera autorizzazione.
• Controlla la reattività sugli schermi più piccoli, in particolare menu di azioni, filtri, campi obbligatori e griglie con molte colonne.

nl punto di partenza generato da Lino deve essere trattato come una base coerente e integrata. Da lì, il team regola la densità visiva, l'ordine dei campi, le regole di visualizzazione, le autorizzazioni e i testi per riflettere l'effettivo processo del prodotto.