XAF Logic Explainer

Enséñale a tu agente de IA qué hace tu aplicación XAF realmente.

Mira cómo funciona →

Apúntalo a un módulo XAF. Lee tus entidades, controladores, acciones, reglas de negocio, navegación y personalizaciones del Model Editor directamente desde el código fuente — y entrega el resultado a cualquier agente con el que programes.

Por qué existe esto

DevExpress ha hecho un excelente trabajo para que los agentes de IA dominen XAF. Ya existen dos piezas, y esta es la tercera:

Un agente que ha leído cada página de la documentación de XAF aún no sabe que tu total de Invoice se calcula a partir de sus líneas, que ApproveController se niega a ejecutarse cuando el período está cerrado, o que tres columnas se ocultaron en el Model Editor y no aparecen en ningún archivo C#. Inventará con confianza las tres.

Ese vacío no se soluciona con mejores indicaciones. Se soluciona con extracción.

Estas herramientas se complementan. Instala las habilidades de DevExpress para el conocimiento del framework, usa el Docs MCP para la referencia oficial, y usa esto para tu propia base de código. Ninguna reemplaza a las otras.

Related MCP server: DevScope MCP

Lo que extrae

Todo lo siguiente se lee como sintaxis, usando Roslyn. Tu proyecto nunca necesita compilarse, y esta herramienta nunca se enlaza contra los ensamblados de DevExpress:

• Entidades — propiedades, tipos, asociaciones y los atributos XAF que les dan significado ([Association], [Aggregated], [RuleRequiredField], [Appearance], [ModelDefault], …). XPO y EF Core, detectados automáticamente a partir de tus sentencias using.

• Controladores y acciones — SimpleAction, PopupWindowShowAction, SingleChoiceAction, sus criterios de destino y el código del manejador que se ejecuta cuando se activan.

• Reglas de negocio — atributos de validación y reglas de código, con las condiciones adjuntas.

• Configuración del módulo — datos semilla de ModuleUpdater y lo que se crea en la primera ejecución.

• Navegación — los grupos y elementos que tus usuarios ven realmente.

• Model Editor (.xafml) — las personalizaciones que existen solo en XML y son invisibles para cualquiera que lea tu C#. Los archivos del módulo y de la plataforma se fusionan como lo hace XAF.

• Editores de propiedades y listas personalizados — incluyendo el JavaScript del que no pueden prescindir, y editores integrados reconfigurados en tiempo de ejecución a través de View.CustomizeViewItemControl<T>(). Estos viven en el proyecto de plataforma junto al módulo, por lo que nadie que lea los objetos de negocio los encuentra.

• Migraciones controladas por versión — los bloques CurrentDBVersion < new Version(…) en tu actualizador. Cada uno se ejecuta como máximo una vez para cualquier base de datos, y es la única explicación para datos que el código actual no puede justificar.

• Cada pantalla, y qué se carga en ella — ver más abajo.

Estas son la razón por la que un agente que ha leído cada clase de negocio aún puede estar equivocado con confianza sobre la aplicación:

Qué se ejecuta cuando abres esta pantalla

Nada en un repositorio XAF responde a eso, y ambas mitades faltan por diferentes razones.

Las pantallas en sí mismas no están en ningún archivo. XAF genera una vista de lista, detalle y búsqueda para cada clase de negocio, más una vista de lista para cada colección, y el Model Editor almacena solo aquellas que alguien modificó. Buscar en tu código fuente Patient_Prescriptions_ListView no encuentra nada — y eso no es evidencia de que falte.

Qué controladores se ejecutan allí se decide en tiempo de ejecución, mediante cuatro condiciones que XAF combina con AND: anidación, tipo de vista, tipo de objeto e id de vista. Cada una no tiene restricciones cuando no se establece, por lo que un controlador que no establece ninguna se carga en todas las pantallas que tienes.

Esto lee las cuatro como ViewController.IsFitToView las evalúa, contra un inventario de vistas construido a partir de los generadores de id del propio framework — y registra por qué coincidió cada una, para que la respuesta pueda verificarse en lugar de confiarse:

Dos capas, mantenidas separadas. Lo que escribió tu equipo recibe el tratamiento completo; lo que proporciona XAF está plegado detrás de una línea, porque hay mucho y no es tuyo para cambiarlo. Con un catálogo de referencia también se nombra — limitado a los módulos que realmente registras, para que un controlador de WinForms nunca aparezca en una pantalla de Blazor.

Lo que no afirmará: un controlador listado aquí aún puede desactivarse mediante Active["reason"], que depende de los datos y del usuario. Esto es lo que XAF carga en una pantalla, no lo que necesariamente hará algo — y cualquier cosa que no pudo leer del código fuente se lista aparte, con el motivo, en lugar de tratarse silenciosamente como "se ejecuta en todas partes".

Inicio rápido

dotnet tool install -g XafLogicExplainer.Cli

xaflogic agents --project "C:\MySolution\MyApp.Module"

Eso escribe AGENTS.md, CLAUDE.md y .github/copilot-instructions.md en la raíz de tu solución. Sin cuenta, sin clave API, sin servidor. Tu agente entiende la aplicación en su siguiente pregunta.

Lo que escribe, y por qué está dividido en dos

AGENTS.md se antepone a cada solicitud que un agente hace en el repositorio, por lo que su costo se paga para siempre. Volcar 70 KB de detalle de entidades allí desplazaría la pregunta real. Por lo tanto, la salida está organizada en niveles:

La parte más valiosa es la más pequeña. AGENTS.md comienza con reglas básicas — que esta aplicación usa XPO y nunca EF Core, que los inventarios son completos por lo que cualquier cosa ausente realmente no existe, y que algo del comportamiento vive en el Model Editor en lugar de en C#. Esos pocos párrafos detienen la mayor parte de la invención confiada que los agentes producen sobre bases de código XAF desconocidas.

Los archivos existentes nunca se sobrescriben: el texto generado vive entre marcadores, cualquier cosa que hayas escrito a mano se conserva, y la regeneración es idéntica byte a byte cuando nada ha cambiado.

O deja que el agente haga preguntas directamente

Los archivos generados son una instantánea. El servidor MCP es una conexión en vivo — el agente consulta tu aplicación mientras trabajas en ella, y no puede quedar obsoleto.

/plugin marketplace add peopleworks/XAFLogicExplainer
/plugin install xaf-logic-explainer@peopleworks-xaf

Eso instala una habilidad y un servidor MCP en un solo paso. Para cualquier otro cliente MCP, ejecútalo directamente desde NuGet sin instalación:

{
  "mcpServers": {
    "xaf": { "command": "dnx", "args": ["XafLogicExplainer.Mcp", "--yes"] }
  }
}

…o apunta a la CLI si ya la tienes:

{ "mcpServers": { "xaf": { "command": "xaflogic", "args": ["mcp"] } } }

Iniciado desde un directorio de solución, encuentra el módulo XAF por sí mismo, por lo que ninguna de las formas necesita una ruta.

Pregunta por algo que no esté ahí y la respuesta es la útil:

No existe una entidad llamada 'PurchaseOrder' en esta aplicación. Esta es la lista completa de 19 entidades, extraída de todo el árbol fuente: … Si el usuario espera que 'PurchaseOrder' exista, aún no se ha creado.

Combínalo con las habilidades oficiales de DevExpress. /plugin install dx-xaf@DevExpress-agent-skills enseña cómo funciona XAF; esto enseña qué hace tu aplicación. Un agente que solo tenga la primera escribirá XAF correcto contra entidades que no tienes.

El mismo conocimiento, para una persona

Un agente lee AGENTS.md o consulta el servidor MCP. Alguien que acaba de heredar una aplicación XAF de diez años necesita los mismos hechos organizados de forma muy diferente:

xaflogic explain --project "C:\MySolution\MyApp.Module" --open

Un archivo HTML. Sin servidor, sin paso de compilación, sin solicitud a la red — se abre desde un archivo adjunto de correo electrónico en una máquina sin internet, que es como realmente ocurren las transferencias.

Dibuja un mapa de tu modelo de dominio a partir de los atributos de asociación dispersos en tu código base. La mayoría de los equipos nunca han visto el suyo: existe en la cabeza de una persona, que es exactamente el conocimiento que se va cuando esa persona se marcha.

Salida real, de la aplicación de ejemplo en este repositorio. Pasa el ratón sobre una entidad y todo lo que no toca se desvanece; el morado significa que eliminar el padre elimina al hijo.

Junto a él: cada entidad y qué es cada propiedad, cada acción con el código que ejecuta, validación con el mensaje que el usuario verá realmente y la configuración del Editor de Modelo que aparece en ningún archivo C#.

Y un índice de cada expresión de criterio en la aplicación — un dialecto que no es ni SQL ni C#, recopilado de atributos dispersos por el código fuente y que de otro modo no se recopila en ningún lado:

Pruébalo con el ejemplo sin tocar tu propio código:

xaflogic explain --project tests/XafLogicExplainer.Tests/Fixtures/DemoSolution/PharmacyDemo.Module --open

Opcional: distinguir tu código del de DevExpress

La extracción lee tu código fuente sin saber nada del framework contra el que está escrito, lo que deja una pregunta sin respuesta: ¿DeleteObjectsViewController es algo que escribió tu equipo o algo que envía DevExpress? Sin respuesta, la documentación generada presenta el comportamiento del framework y tu propia lógica como si fueran lo mismo.

Si tienes una licencia de DevExpress:

xaflogic catalog build

Eso lee tu propia instalación y registra lo que XAF mismo proporciona — atributos, controladores, interfaces de modelo y módulos, con los resúmenes oficiales y enlaces de documentación que DevExpress envía. En DevExpress 26.1 eso son alrededor de 850 tipos del framework.

Si también instalaste el componente de código fuente de DevExpress, registra dónde se activa cada controlador del framework — las cuatro condiciones que XAF verifica antes de ejecutarlo. Eso no se puede leer de los ensamblados: cuatro de cada cinco controladores integrados establecen su destino dentro de un constructor. Pasa --dx-sources <Components/Sources> si no están junto a tus ensamblados.

La extracción lo recoge automáticamente y puede decir cosas que de otro modo no podría:

• "ArchiveController extiende el DeleteObjectsViewController integrado" — estás cambiando cómo funciona la eliminación en toda la aplicación, no añadiendo una característica a su lado.

• "[AuditedByFinance] no es un atributo de XAF ni de .NET" — tu equipo lo inventó, por lo que su significado vive en este código base y en ninguna documentación en ningún lado.

• "32 controladores del framework también se cargan en esta pantalla" — nombrados, con lo que hace cada uno, y limitados a los módulos que tu aplicación realmente registra, por lo que un controlador de WinForms nunca aparece en una pantalla de Blazor.

El catálogo se escribe en ~/.xaflogic/catalog/, nunca en tu repositorio: se deriva de software con licencia. Todo funciona sin él — solo agudiza la salida. Consulta NOTICE.md.

Comandos

La documentación se genera en inglés o español (--lang en|es).

Banderas útiles: --orm auto| xpo|efcore, --lang en|es, --enrich (resúmenes de lógica de negocio generados por IA por controlador y acción), --force, --all.

--enrich necesita un modelo, y cualquiera de estos es suficiente — una clave en la línea de comandos tiene prioridad, luego el entorno, luego una cuenta de PeopleWorks Copilot si tienes una:

xaflogic extract --enrich --api-key sk-...              # or any OpenAI-compatible endpoint:
xaflogic extract --enrich --api-key ... --ai-base-url http://localhost:11434/v1 --ai-model qwen2.5-coder

export OPENAI_API_KEY=sk-...        # picked up with no configuration at all
export ANTHROPIC_API_KEY=sk-ant-...

Todo lo demás en esta herramienta funciona sin clave, sin cuenta y sin red.

La extracción es incremental — un SHA-256 sobre tus archivos .cs y .xafml significa que un proyecto sin cambios es una no operación. Hay un archivo .targets de MSBuild si quieres que se ejecute al compilar.

Estado

v0.14.0. El motor de extracción es la parte madura: se ejecuta en producción contra aplicaciones XAF reales. La superficie orientada al agente es lo que está llegando ahora, en abierto.

PeopleWorks Copilot, donde creció esta herramienta, es ahora un destino entre varios, en lugar del destino alrededor del cual se construyó todo. Las salidas que más importan no necesitan ningún servidor.

La versión larga

Por qué un tercio del comportamiento de una aplicación XAF vive fuera de sus clases de negocio, los cuatro lugares donde se esconde y cómo se ve realmente la salida extraída:

• Tu agente de código sabe XAF. Nunca ha visto tu aplicación.

• Tu agente de código sabe XAF. Nunca ha visto tu aplicación. — en español

Cada uno está escrito en su propio idioma en lugar de traducido del otro. Fuentes en docs/Blog/.

Diseño del repositorio

src/
  XafLogicExplainer.Core                 Roslyn extraction engine — no DevExpress reference
  XafLogicExplainer.Mcp                  MCP server (ModelContextProtocol 2.1)
  XafLogicExplainer.Cli                  the `xaflogic` command
  XafLogicExplainer.CopilotSync          PeopleWorks Copilot target + AI enrichment
  XafLogicExplainer.DescriptionAnnotator generates missing [Description] attributes
  XafLogicExplainer.Blazor               in-app help panel for XAF Blazor apps
plugins/
  xaf-logic-explainer                    the installable Claude Code plugin

Construido sobre .NET 10.

Solo XafLogicExplainer.Blazor hace referencia a paquetes de DevExpress; necesita la fuente NuGet de DevExpress y una licencia para compilar. Todo lo demás se compila en cualquier lugar, por lo que CI puede verificarlo gratis.

Contribuir

La contribución más valiosa es decirnos qué se perdió el extractor. XAF es enorme, cada código base usa una porción diferente, y ningún proyecto individual ejercita todo el framework. Hay una plantilla de issue de brecha de extracción exactamente para esto: muestra el patrón XAF que usa tu proyecto y qué no pudo ver la herramienta.

Consulta CONTRIBUTING.md. Los informes de errores, la documentación y las traducciones son igualmente bienvenidos.

Licencia

MIT. Consulta NOTICE.md para la relación con DevExpress.

Un proyecto comunitario independiente — no afiliado, respaldado ni apoyado por Developer Express Inc. No contiene código fuente de DevExpress y no necesita una licencia de DevExpress para compilar o ejecutar. DevExpress, XAF y eXpressApp Framework son marcas comerciales de Developer Express Inc.

Construido por Pedro Hernández (PeopleWorks), Microsoft MVP para .NET — para la comunidad de DevExpress y XAF.