Overview

Panorámica del Framework

WUIC Framework es una plataforma metadata-driven para crear interfaces de negocio de forma rápida y coherente.

Qué incluye

DataSource y DataRepeater para orquestar datos y renderizado.
Archetypes visuales (list, map, scheduler, chart, carousel).
Designer runtime para dashboards y templates dinámicos.
Workflow designer/runner para procesos operativos.
RAG Chatbot para consultar la codebase en lenguaje natural.
Multi-SGBD: SQL Server, MySQL, PostgreSQL y Oracle mediante providers drop-in (dbms: mssql | mysql | postgresql | oracle).

First Steps — Arranque del entorno dev

El stack WUIC está compuesto por varios servicios. Arráncalos en el orden indicado.

Prerrequisitos

Qué	Verificación	Notas
.NET 10 SDK	`dotnet --version`	Hosting Bundle para IIS en producción
Node.js 22 LTS	`node --version`	La 22 es la version con la que se prueba el paquete; con npm 10.9.x la instalacion funciona gracias al `package-lock.json` incluido
PowerShell 5.1+	`$PSVersionTable.PSVersion`	El Windows PowerShell preinstalado es suficiente: `rename-project.ps1` y los scripts `llm-workspace/` tambien funcionan en 5.1. PowerShell 7 es recomendable, no obligatorio
SQL Server 2019+	`sqlcmd -S localhost\sqlexpress -E -C -Q "SELECT 1"`	Si falta, la línea única lo instala por su cuenta (SQL Server Express, o el motor elegido con `-Dbms`); en Windows Server no, ver el recuadro de abajo. 2019 basta para los paquetes sin `.bak`; el tutorial `.bak` es una copia de SQL Server 2022 y requiere 2022 o superior
Linux (instalador `install.sh`)	`lsb_release -ds`	Ubuntu 22.04 o 24.04 LTS (24.04 recomendada): son las unicas versiones de Ubuntu que Microsoft soporta para SQL Server, la 26.04 no esta soportada (Supported platforms). Misma recomendacion con MySQL, PostgreSQL y Oracle, porque el instalador esta probado en esas versiones
GPU NVIDIA (CUDA 12.x + cuDNN 9)	`nvidia-smi`	Opcional: acelera el RAG Chatbot (sin GPU funciona en CPU)

> En Windows Server la base de datos debe instalarse antes. La linea unica obtiene los

> componentes que faltan mediante winget, que no esta presente en Windows Server: sin una

> instancia ya accesible la instalacion se detiene con `No SQL Server instance reachable and

> winget is missing`. Instala el motor antes de ejecutar la linea - SQL Server debe ser **2019 o

> superior (Express es suficiente; 2022 o superior** para el tutorial .bak), y una 2017 no

> se acepta. Si la instancia no es la predeterminada, pasala con

> -SqlServer 'localhost\NOMBREINSTANCIA'. Vale para todos los motores, no solo SQL Server.

1. Descarga el template de proyecto

En Windows una sola linea de PowerShell lo hace todo: descarga el paquete, comprueba el SDK de .NET 10

y Node.js 22 (instalando lo que falte), ejecuta dotnet restore y npm install,

e instala la extension WUIC Assistant en VS Code.

Snippet 1PowerShell

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

Opciones útiles en la misma línea: -Dbms mysql (o postgres, oracle) para un motor

distinto de SQL Server — el instalador lo instala y lo configura él mismo — y -WithTutorial

para descargar también la base de datos de ejemplo.

Cuando termina, la última pantalla ya es tu lista de tareas: abre el archivo de workspace

WuicTest.code-workspace en VS Code y pulsa F5, que arranca backend y frontend juntos con

el lanzador Fullstack: WuicTest + Chrome (los lanzadores están en .vscode/launch.json,

junto al que arranca solo el backend). Si prefieres el terminal, los comandos equivalentes

están más abajo.

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 cadena de conexión ya está lista: en el primer arranque el wizard no pide nada más. Con

-Dbms mysql o -Dbms postgres esa línea cambia en consecuencia y lleva dentro usuario y

contraseña, porque la contraseña del superusuario la genera el instalador; esa misma

contraseña se guarda en wuic-secrets.json, junto a la instalación, y es el único sitio donde

queda escrita.

La via manual sigue siendo valida, en cualquier sistema:

Parte del paquete WuicTest-src-*.zip (enlace en la sección Download del sitio).

Extráelo en una carpeta de trabajo, p. ej. C:\dev\WuicTest (los archivos van directamente

en la raíz, NO dentro de una subcarpeta src/). El paquete contiene:

WuicTest.csproj → proyecto host con <PackageReference Include="WuicCore" Version="..." />
wwwroot/ → app Angular cuyo package.json referencia wuic-framework-lib desde el registry npm
appsettings.json preconfigurado en modo firstRun = "true" con placeholders __SET_*__
appsettings-samples/ → 6 templates listos (mssql/mysql, firstRun/post-firstRun, Development)

> No hace falta clonar el repositorio del framework: WuicCore llega como paquete NuGet

> desde nuget.org y wuic-framework-lib como paquete npm desde el registry npm. El código

> fuente del framework solo se necesita si quieres modificarlo — típicamente no es tu caso.

> npm 10.9.x y los paquetes anteriores a 1.7.1: esos paquetes no incluyen package-lock.json, y

> sin lock npm 10.9.x (la version que instala Node 22 LTS) se detiene con

> Cannot read properties of null (reading 'edgesOut') al resolver las dependencias peer.

> Descarga el lock publicado junto a la release —

> https://wuic-framework.com/downloads/locks/<nombre-del-zip>.package-lock.json — colocalo en

> wwwroot/ y ejecuta npm install otra vez. La linea unica -Src lo hace por ti.

2. Database

Hace falta una instancia del motor accesible. Con la línea única no hay nada que hacer:

la instala y la configura ella, y la cadena de conexión que hay que pegar en el wizard es lo

último que imprime. En la vía manual la instancia debe existir ya.

Conexiones en appsettings.json:

MetaDataSQLConnection — DB metadata (menú, tablas, columnas, boards, usuarios)
DataSQLConnection — DB datos de la aplicación

Si es la primera instalación (AppSettings.firstRun = "true" en el template),

el wizard de scaffolding en el primer arranque crea el esquema metadata y puebla el DB datos.

Ver la página Scaffolding inicial para el flujo guiado.

#### Qué pide el asistente de primer arranque

En el primer arranque la aplicación no muestra el formulario de acceso sino la página

Configuración inicial del proyecto. Se rellena una sola vez: al terminar firstRun pasa a

false y la página no vuelve a aparecer.

Modo de instalación — dos entradas: Base de datos existente, que registra una base de

datos tuya, y Tutorial WideWorldImporters, que instala la base de ejemplo. La segunda solo

aparece si el paquete trae el tutorial (tutorialAvailable): en los paquetes sin tutorial el

desplegable no se muestra y el modo es "Base de datos existente".

SGBD — el motor. Al cambiarlo, la cadena de conexión de abajo se reescribe con la forma

del proveedor elegido.

DataSQLConnection — la cadena hacia la base de datos, y el campo del que depende todo lo

demás: hasta que no pulses Probar conexión y cargar bases de datos la lista de bases

permanece deshabilitada. La prueba valida las credenciales, enumera las bases del servidor y,

en SQL Server, corrige por su cuenta los parámetros de certificado

(Encrypt=False;TrustServerCertificate=True) avisándote. Integrated Security solo vale en

SQL Server: los demás motores necesitan usuario y contraseña.

Base de datos y Nombre de la base de metadatos — la primera se elige de la lista que

cargó la prueba (en modo tutorial es un campo libre, WideWorldImporters por defecto); la

segunda es el nombre de la base de metadatos a crear (metadataDB por defecto, MetadataCRM

en modo tutorial). Si esa base ya existe, el asistente pide confirmación antes de recrearla.

Generar automáticamente los metadatos de las tablas (solo en "Base de datos existente") —

rellena _metadati__tabelle / _metadati__colonne a partir de todas las tablas de la base

elegida. Es lo que más alarga el aprovisionamiento en bases con muchas tablas.

Usuario admin inicial — nombre de usuario (admin por defecto), contraseña (mínimo 4

caracteres) e idioma. No hay contraseña predeterminada: la que escribas aquí es la única con

la que entrarás en el primer acceso. El idioma elegido se aplica al usuario admin y a esta

misma página. Si el nombre de usuario coincide con un usuario ya presente en la DB de

metadatos, la contraseña y el idioma elegidos se aplican a ese usuario. El asistente crea

también el usuario wuic_assistant para el WUIC Assistant, con una contraseña generada: ver

RAG Chatbot.

RAG Chatbot — solo la clave de Anthropic, opcional. Nada que instalar: ver el paso 5.

Al pulsar Confirmar y crear la base de metadatos el aprovisionamiento continúa solo, con una

barra de progreso y el número de lotes procesados. Cuánto dura, medido en las instalaciones de

prueba: 30 s - 2 min en modo tutorial, 1-4 min sobre una base existente con el scaffold

automático activado. Al terminar, la página deja paso al formulario de acceso.

3. Backend (.NET)

Desde la raíz de la carpeta extraída (p. ej. C:\dev\WuicTest):

Snippet 3PowerShell

# Primera vez: restore paquetes NuGet (pulls WuicCore + deps desde nuget.org, ~30 s)
dotnet restore

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

El backend expone las API en http://localhost:5000.

4. Frontend (Angular)

En una segunda shell, desde la subcarpeta wwwroot/:

Snippet 4PowerShell

cd wwwroot

# Primera vez: restore dependencias npm (pulls wuic-framework-lib desde npm registry, ~2 min)
npm install

# Arranque dev server
npm run serve:dev

El frontend está disponible en http://localhost:4200.

Las credenciales son las del usuario admin elegido en el asistente de primer arranque: el

nombre de usuario es admin si no lo cambiaste, y la contraseña es la que escribiste (no hay

contraseña predeterminada).

5. RAG Chatbot (opcional)

El RAG Chatbot (Administración > RAG Chat) se ejecuta **dentro del backend

.NET**: el motor de retrieval (rag-engine/WuicRagEngine.dll, ONNX Runtime

in-process) lo carga el backend cuando AppSettings.rag-use-dotnet-engine es

"true" (valor por defecto en los paquetes de release). **Sin Python, sin

venv, ningún servidor separado que arrancar.**

La primera vez que se abre el chatbot (o al final del first-run) el

backend descarga por sí solo los modelos ONNX (bge-m3 + reranker), el

tokenizer y el índice (~4,5 GB) desde rag-engine-models-url (por defecto

https://wuic-framework.com/rag-models) en rag-engine/artifacts/. Solo hace

falta conexión a internet una vez; la descarga corre en segundo plano (1-5 min)

y llega una notificación in-app al inicio y al final. Mientras tanto el

componente muestra el estado RAG offline y el resto de la aplicación

funciona con normalidad.

Claves AppSettings relevantes (todas con valores por defecto listos):

rag-use-dotnet-engine = true — activa el motor .NET (false = fallback Python, ver abajo)
rag-engine-device = auto — auto | cuda | cpu: con GPU NVIDIA (CUDA 12.x + cuDNN 9) ~1 s/consulta, en CPU ~15-25 s/consulta
rag-engine-profile = release — release = fuentes del framework solo como firma; internal = índice completo
rag-engine-models-url — origen de la descarga en el primer arranque
rag-engine-cuda-path = (vacío) — carpeta de las DLL CUDA/cuDNN si no están instaladas a nivel de sistema

Para el chat con LLM configura rag-llm-provider + rag-llm-api-key (Claude

vía Anthropic, o un modelo local vía Ollama con rag-llm-base-url). Sin

provider solo funciona la modalidad retrieval (búsqueda de snippets). Detalle

de las claves en la página AppSettings.

> El stack histórico Python (scripts/rag-setup.ps1 + rag_server.py en

> 127.0.0.1:8765) solo puede usarse como fallback con

> rag-use-dotnet-engine = "false" y no se incluye en los paquetes de release.

Resumen de servicios

Servicio	Puerto	Obligatorio	Comando rápido
SQL Server	1433	sí	(servicio Windows)
Backend .NET	5000	sí	`dotnet watch ... run`
Frontend Angular	4200	sí	`npm run serve:dev`
Engine RAG .NET (ONNX)	in-process	no	cargado por el backend en el primer chat

Quick Start — primer componente

1. Configura el endpoint AsmxProxy.

2. Define route metadata y columnas.

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>

Las primeras listas muestran 20 registros: es el modo Trial

Una instalacion recien hecha funciona sin licencia, es decir, en modo Trial, y en ese

modo cada consulta esta limitada a 20 registros. No es un error ni un limite de la base

de datos: una lista que indica "20 de 20" sobre una tabla con miles de filas simplemente

esta funcionando sin licencia.

Como confirmarlo en un segundo:

Snippet 6Bash

curl -s http://localhost:5000/api/Meta/LicenseStatus

licenseValid: false confirma el modo Trial, y licenseReason dice por que

(invalid_signature, license_expired, machine_fingerprint_not_authorized, ...).

Como salir: se pega la licencia desde Administracion > Editor AppSettings, pestana Licensing,

y tiene efecto de inmediato: no hace falta reiniciar el backend. Los detalles, incluidos los

limites que el modo Trial impone mas alla del numero de registros, estan en la pagina

Licensing.