De cero a tu primer PDF en 10 minutos

1Instala el paquete

Instala solo uno. XtudioPdf.AspNetCore ya incluye el motor.

Requiere .NET 8 o .NET 10. Funciona en Windows, Linux, macOS y Docker. No es compatible con .NET Framework (4.x).

2Instala la extensión (una vez por equipo)

Eso es todo. La primera vez que abres un .pdfx, la extensión instala sola el diseñador (la herramienta xtudiopdf) y lo mantiene actualizado. Sin extensión, instálalo a mano: dotnet tool install -g XtudioPdf.Tool

3Crea tu documento

Clic derecho en la carpeta donde guardas tus reportes y agrega un documento XtudioPdf. Ponle un nombre, por ejemplo Factura.

4Diseña

Doble clic en Factura.pdfx y el diseñador se abre como una pestaña más de tu editor. No necesitas ejecutar tu app.

1 2 3 4

1. Bloques. Arrástralos a la hoja: texto, tablas, imágenes, QR, gráficos… Una Fila pone bloques lado a lado; una Columna los apila.
2. La hoja. El encabezado y el pie se repiten en cada página; el cuerpo crece con tus datos y pasa solo a nuevas páginas.
3. Propiedades. Haz clic en un bloque para cambiar su texto, letra, colores, bordes, espacios y cuándo se muestra.
4. Previsualización (Ctrl+Enter) muestra el PDF real. Guarda con Ctrl+S.

5Conecta tus datos

La pestaña Datos muestra las propiedades de tu clase. Nunca escribes un campo a mano: lo eliges.

1 2 3 4

1. Tus campos. Haz clic en uno (o arrástralo) para insertarlo en el texto seleccionado, por ejemplo {{Cliente.Nombre}}.
2. En la hoja cada campo es una etiqueta celeste. El botón de la base de datos, arriba, muestra en su lugar los valores de ejemplo.
3. Una tabla repite una fila por cada ítem de una lista y pasa a la página siguiente cuando no entra.
4. Elige la lista (Lineas, Items…) y el campo de cada columna. Los formatos como {{Total:N2}} o el monto en letras {{Total:letras}} van después de los dos puntos.

La previsualización usa tus datos de ejemplo: el archivo .sample.json junto a la plantilla o un método estático GetSampleData() en tu clase.

6Genera el PDF en tu código

Cada .pdfx del proyecto se embebe al compilar y se valida contra su clase: si un campo no existe, el compilador te avisa.

// Program.cs
builder.Services.AddPdfReports();

// Reportes/FacturaReporte.cs: se crea sola; XtudioPdf la completa a partir del .pdfx
public sealed partial class FacturaReporte
{
    public byte[] Generar(FacturaDto datos) => Render(datos);
}

// Tu endpoint devuelve el PDF
app.MapGet("/facturas/{id:int}/pdf", async (int id, FacturaReporte reporte, AppDb db) =>
    await db.Facturas.FindAsync(id) is { } factura
        ? Results.File(reporte.Generar(factura), "application/pdf", $"factura-{id}.pdf")
        : Results.NotFound());

Sin ASP.NET Core (XtudioPdf.Core):

var templates = new PdfTemplates().AddAssembly(typeof(Program).Assembly);
byte[] pdf = templates.Render("Factura", factura);

Qué haces con los bytes depende de ti: devolverlos desde tu API, guardarlos, adjuntarlos a un correo o enviarlos a la autoridad tributaria junto con el XML.

7Activa Pro (opcional)

Community funciona sin clave e incluye el 100% de las funciones para desarrolladores individuales y empresas con menos de $1M USD de ingresos anuales. Con una clave Pro, ponla en appsettings.json o en la variable de entorno XTUDIOPDF_LICENSE_KEY.

"XtudioPdf": { "LicenseKey": "XTPD.…" }

• Se valida 100% sin conexión tanto en el diseñador como en producción — nunca se comunica con servidores externos.
• Incluye el nombre de tu empresa en los metadatos Creator del PDF y soporte prioritario.