Panoramica Framework

Panoramica Framework - documentazione operativa e tecnica

primi-passistable

Overview

Panoramica Framework

WUIC Framework e' una piattaforma metadata-driven per creare interfacce business in modo rapido e coerente.

Cosa include

  • DataSource e DataRepeater per orchestrare dati e rendering.
  • Archetypes visuali (list, map, scheduler, chart, carousel).
  • Designer runtime per dashboard e template dinamici.
  • Workflow designer/runner per processi operativi.
  • RAG Chatbot per interrogare la codebase in linguaggio naturale.
  • Multi-DBMS: SQL Server, MySQL, PostgreSQL e Oracle tramite provider drop-in (dbms: mssql | mysql | postgresql | oracle).

First Steps — Avvio ambiente dev

Lo stack WUIC e' composto da piu' servizi. Avviali nell'ordine indicato.

Prerequisiti

CosaVerificaNote
.NET 10 SDKdotnet --versionHosting Bundle per IIS in produzione
Node.js 22 LTSnode --versionLa 22 e' la versione con cui il pacchetto e' testato; con npm 10.9.x installa solo grazie al package-lock.json incluso
PowerShell 5.1+$PSVersionTable.PSVersionLa PowerShell preinstallata su Windows basta: rename-project.ps1 e gli script llm-workspace/ girano anche su 5.1. PowerShell 7 e' consigliata, non richiesta
SQL Server 2019+sqlcmd -S localhost\sqlexpress -E -C -Q "SELECT 1"Se manca, il one-liner lo installa da se' (SQL Server Express, o il motore scelto con -Dbms); su Windows Server no, vedi il riquadro sotto. 2019 basta per i pacchetti senza .bak; il tutorial .bak e' un backup di SQL Server 2022 e richiede 2022 o superiore
Linux (installer install.sh)lsb_release -dsUbuntu 22.04 o 24.04 LTS (24.04 raccomandata): sono le uniche Ubuntu su cui Microsoft supporta SQL Server, la 26.04 non e' supportata (Supported platforms). Stessa raccomandazione con MySQL, PostgreSQL e Oracle, perche' l'installer e' provato su quelle
GPU NVIDIA (CUDA 12.x + cuDNN 9)nvidia-smiOpzionale: accelera il RAG Chatbot (senza GPU gira su CPU)

> Su Windows Server il database va installato prima. Il one-liner si procura i componenti

> mancanti tramite winget, che su Windows Server non e' presente: senza un'istanza gia'

> raggiungibile l'installazione si ferma con `No SQL Server instance reachable and winget is

> missing`. Installa quindi il motore prima di lanciare la riga - per SQL Server serve la

> 2019 o superiore (la Express basta; 2022 o superiore per il tutorial .bak), e una

> 2017 non viene accettata. Se l'istanza non e' quella predefinita, passala con

> -SqlServer 'localhost\NOMEISTANZA'. Vale per tutti i motori, non solo SQL Server.

1. Scarica il template di progetto

Su Windows fai tutto con una riga di PowerShell: scarica il pacchetto, verifica .NET SDK 10 e Node.js 22

(installando cio' che manca), esegue dotnet restore e npm install, e installa

l'estensione WUIC Assistant in VS Code.

Snippet 1PowerShell
& ([scriptblock]::Create((irm https://wuic-framework.com/install.ps1))) -Src

Opzioni utili sulla stessa riga: -Dbms mysql (oppure postgres, oracle) per un motore

diverso da SQL Server — che l'installer installa e configura da se' — e -WithTutorial per

scaricare anche il database di esempio.

Quando ha finito, l'ultima schermata e' gia' l'elenco delle cose da fare: si apre il file di

workspace WuicTest.code-workspace in VS Code e si preme F5, che avvia backend e frontend

insieme con il launcher Fullstack: WuicTest + Chrome (i launcher stanno in

.vscode/launch.json, insieme a quello per il solo backend). Chi preferisce il terminale trova

i comandi equivalenti piu' sotto.

Snippet 2text
Developer workspace ready: C:\Users\<user>\AppData\Local\WUIC\app

  code "C:\Users\<user>\AppData\Local\WUIC\app\WuicTest.code-workspace"
  then F5 > 'Fullstack: WuicTest + Chrome' (backend http://localhost:5000, frontend http://localhost:4200)

First start opens the first-run wizard: paste this connection string (Windows authentication)
  Data Source=localhost\SQLEXPRESS;Integrated Security=SSPI;Initial Catalog=WuicData;Encrypt=False;TrustServerCertificate=True

La stringa di connessione e' gia' pronta: al primo avvio il wizard non chiede altro. Con

-Dbms mysql o -Dbms postgres la riga cambia di conseguenza e porta dentro di se' utente e

password, perche' la password del superutente la genera l'installer; la stessa password

viene salvata in wuic-secrets.json, accanto all'installazione, ed e' l'unico posto in cui

resta scritta.

Il percorso manuale resta valido e funziona su qualunque sistema:

Parti dal pacchetto WuicTest-src-*.zip (link nella sezione Download del sito).

Estrailo in una cartella di lavoro, es. C:\dev\WuicTest (i file vanno direttamente nella root,

NON dentro una sottocartella src/). Il pacchetto contiene:

  • WuicTest.csproj → progetto host con <PackageReference Include="WuicCore" Version="..." />
  • wwwroot/ → app Angular con package.json che referenzia wuic-framework-lib da npm registry
  • appsettings.json preconfigurato in modalita' firstRun = "true" con placeholder __SET_*__
  • appsettings-samples/ → 6 template pronti (mssql/mysql, firstRun/post-firstRun, Development)

> Non serve clonare il repository del framework: WuicCore arriva come pacchetto NuGet da

> nuget.org e wuic-framework-lib come pacchetto npm da npm registry. Il sorgente del framework

> serve solo se vuoi modificarlo — tipicamente non e' il tuo caso.

> npm 10.9.x e i pacchetti precedenti alla 1.7.1: quei pacchetti non contengono

> package-lock.json, e senza lock npm 10.9.x (quello che installa Node 22 LTS) si ferma con

> Cannot read properties of null (reading 'edgesOut') mentre risolve i peer. Scarica il lock

> pubblicato accanto alla release — https://wuic-framework.com/downloads/locks/<nome-zip>.package-lock.json

> — mettilo in wwwroot/ e rilancia npm install. Il one-liner -Src lo fa da solo.

2. Database

Serve un'istanza del motore raggiungibile. Con il one-liner non devi fare niente: la

installa e la configura lui, e la stringa di connessione da incollare nel wizard e' l'ultima

cosa che stampa. Nel percorso manuale l'istanza deve essere gia' presente.

Connessioni in appsettings.json:

  • MetaDataSQLConnection — DB metadata (menu, tabelle, colonne, board, utenti)
  • DataSQLConnection — DB dati applicativi

Se e' la prima installazione (AppSettings.firstRun = "true" nel template),

il wizard di scaffolding al primo avvio crea lo schema metadata e popola il DB dati.

Vedi la pagina Scaffolding iniziale per il flusso guidato.

#### Cosa chiede il wizard di primo avvio

Al primo avvio l'applicazione non mostra il login ma la pagina **Configurazione iniziale

progetto**. Si compila una volta sola: al termine firstRun passa a false e la pagina non

ricompare piu'.

  • Modalita' setup — due voci: DB esistente, che registra un database gia' tuo, e

Tutorial WideWorldImporters, che installa il database di esempio. La seconda compare

solo se il pacchetto porta con se' il tutorial (tutorialAvailable): nei pacchetti senza

tutorial la tendina non c'e' affatto e la modalita' e' "DB esistente".

  • DBMS — il motore. Cambiandolo, la stringa di connessione sotto viene riscritta nella

forma del provider scelto.

  • DataSQLConnection — la stringa verso il DB dati, ed e' il campo da cui dipende tutto il

resto: finche' non premi Test connessione e carica DB l'elenco dei database resta

disabilitato. Il test verifica le credenziali, elenca i database del server e, su SQL

Server, corregge da se' i parametri dei certificati

(Encrypt=False;TrustServerCertificate=True) dicendotelo. Integrated Security vale solo

su SQL Server: sugli altri motori servono utente e password.

  • Database dati e Nome DB metadati — il primo si sceglie dall'elenco caricato dal

test (in modalita' tutorial e' un campo libero, default WideWorldImporters); il secondo e'

il nome del database metadati da creare (default metadataDB, MetadataCRM in modalita'

tutorial). Se quel database esiste gia', il wizard chiede conferma prima di ricrearlo.

  • Esegui scaffold automatico delle tabelle (solo "DB esistente") — popola

_metadati__tabelle / _metadati__colonne da tutte le tabelle del database scelto. E' la

voce che allunga di piu' il provisioning su database con molte tabelle.

  • Utente admin iniziale — username (default admin), password (minimo 4 caratteri) e

lingua. Non esiste una password predefinita: quella scritta qui e' l'unica con cui entrerai

al primo login. La lingua scelta viene applicata all'utente admin e a questa pagina stessa.

Se lo username coincide con un utente gia' presente nel DB metadati, password e lingua scelte

vengono applicate a quell'utente. Il wizard crea anche l'utente wuic_assistant per il WUIC

Assistant, con una password generata: vedi RAG Chatbot.

  • RAG Chatbot — solo la chiave Anthropic, opzionale. Niente da installare: vedi il punto 5.

Premuto Conferma e genera metadataDB il provisioning va avanti da solo, con una barra e il

numero di batch elaborati. Quanto dura, misurato sulle installazioni di prova: 30 s - 2 min

in modalita' tutorial, 1-4 min su un database esistente con lo scaffold automatico attivo.

Finito, la pagina lascia il posto al form di login.

3. Backend (.NET)

Dalla root della cartella estratta (es. C:\dev\WuicTest):

Snippet 3PowerShell
# Prima volta: restore pacchetti NuGet (pulls WuicCore + deps da nuget.org, ~30 s)
dotnet restore

# Avvio dev con hot reload
$env:ASPNETCORE_ENVIRONMENT = 'Development'
dotnet watch run

Il backend espone le API su http://localhost:5000.

4. Frontend (Angular)

In una seconda shell, dalla sottocartella wwwroot/:

Snippet 4PowerShell
cd wwwroot

# Prima volta: restore dipendenze npm (pulls wuic-framework-lib da npm registry, ~2 min)
npm install

# Avvio dev server
npm run serve:dev

Il frontend e' disponibile su http://localhost:4200.

Le credenziali sono quelle dell'utente admin scelto nel wizard di primo avvio: lo username e'

admin se non l'hai cambiato, la password e' quella che hai scritto tu (non esiste una

password predefinita).

5. RAG Chatbot (opzionale)

Il RAG Chatbot (Amministrazione > RAG Chat) gira dentro il backend .NET:

il motore di retrieval (rag-engine/WuicRagEngine.dll, ONNX Runtime

in-process) viene caricato dal backend quando AppSettings.rag-use-dotnet-engine

e' "true" (default nei pacchetti di release). **Niente Python, niente venv,

nessun server separato da avviare.**

Alla prima apertura del chatbot (o a fine first-run) il backend scarica da

solo modelli ONNX (bge-m3 + reranker), tokenizer e indice (~4,5 GB) da

rag-engine-models-url (default https://wuic-framework.com/rag-models) in

rag-engine/artifacts/. Serve una connessione internet una sola volta; il

download gira in background (1-5 min) e a inizio/fine download arriva una

notifica in-app. Nel frattempo il componente mostra lo stato RAG offline e

il resto dell'applicazione funziona normalmente.

Chiavi AppSettings rilevanti (tutte con default gia' pronti):

  • rag-use-dotnet-engine = true — attiva l'engine .NET (false = fallback Python, vedi sotto)
  • rag-engine-device = auto — auto | cuda | cpu: con GPU NVIDIA (CUDA 12.x + cuDNN 9) ~1 s/query, su CPU ~15-25 s/query
  • rag-engine-profile = release — release = sorgenti framework solo come firma; internal = indice integrale
  • rag-engine-models-url — sorgente del download al primo avvio
  • rag-engine-cuda-path = (vuoto) — cartella delle DLL CUDA/cuDNN se non installate a livello di sistema

Per la chat con LLM valorizza rag-llm-provider + rag-llm-api-key (Claude

via Anthropic, oppure un modello locale via Ollama con rag-llm-base-url).

Senza provider funziona solo la modalita' retrieval (ricerca snippet).

Dettaglio delle chiavi nella pagina AppSettings.

> Lo stack storico Python (scripts/rag-setup.ps1 + rag_server.py su

> 127.0.0.1:8765) resta utilizzabile solo come fallback con

> rag-use-dotnet-engine = "false" e non e' incluso nei pacchetti di release.

Riepilogo servizi

ServizioPortaObbligatorioComando rapido
SQL Server1433si(servizio Windows)
Backend .NET5000sidotnet watch ... run
Frontend Angular4200sinpm run serve:dev
Engine RAG .NET (ONNX)in-processnocaricato dal backend alla prima chat

Quick Start — primo componente

1. Configura endpoint AsmxProxy.

2. Definisci route metadata e colonne.

3. Monta wuic-data-source + wuic-data-repeater.

Snippet 5HTML
<wuic-data-source [hardcodedRoute]="'cities'"></wuic-data-source>
<wuic-data-repeater [hardcodedAction]="'list'"></wuic-data-repeater>

Le prime liste mostrano 20 record: e' la modalita' Trial

Un'installazione appena fatta gira senza licenza, cioe' in modalita' Trial, e in quella

modalita' ogni query e' limitata a 20 record. Non e' un errore ne' un limite del database:

una lista che dichiara "20 di 20" su una tabella con migliaia di righe sta semplicemente

girando senza licenza.

Come confermarlo in un secondo:

Snippet 6Bash
curl -s http://localhost:5000/api/Meta/LicenseStatus

licenseValid: false conferma la Trial, e licenseReason dice perche' (invalid_signature,

license_expired, machine_fingerprint_not_authorized, ...).

Come uscirne: si incolla la licenza da Amministrazione > Editor AppSettings, scheda Licensing,

ed e' valida subito — non serve riavviare il backend. I dettagli, compresi i limiti che la

Trial impone oltre al numero di record, stanno nella pagina Licensing.