Cómo crear documentos PDF en C# y VB.NET

Traducido por Bit Miracle. Artículo original de Vitaliy Shibaev

Actualizado el 6 de mayo de 2026

Este artículo describe diferentes maneras de crear documentos PDF en .NET con la ayuda de la biblioteca Docotic.Pdf. Se trata de una biblioteca .NET de alto rendimiento, escrita completamente en C# y sin dependencias externas, para crear, editar, convertir y procesar documentos PDF.

En las siguientes secciones, presento los principales métodos para crear archivos PDF con Docotic.Pdf:

• Uso de la API Core, que proporciona un control de bajo nivel sobre el texto, los gráficos y la estructura interna del PDF. Esta opción es ideal para diseños personalizados, documentos con gran cantidad de gráficos y funciones avanzadas.
• Uso de la API Layout, que admite párrafos, tablas, encabezados, pies de página y paginación automática. Esta API es ideal para documentos estructurados sin necesidad de calcular manualmente las posiciones.
• Conversión de HTML a PDF con compatibilidad con SVG y otros formatos web. Este método es especialmente útil cuando su solución ya genera documentos HTML y necesita versiones PDF de esos archivos HTML y CSS.
• Creación de PDF a partir de imágenes. Este método es útil para documentos escaneados, informes basados ​​en imágenes, recibos y cualquier flujo de trabajo que comience con imágenes rasterizadas.
• Combinación o división de PDF. Esta es una buena opción para ensamblar informes, procesar archivos subidos por usuarios, combinar documentos relacionados y reestructurar archivos PDF de gran tamaño.
• Creación de PDF a partir de plantillas. Este método funciona bien cuando se requiere un formato uniforme para documentos generados por lotes, como recibos, formularios fiscales, contratos laborales y otros tipos de documentos repetibles.

Entre los temas adicionales que se tratan en la guía se incluyen:

• Funciones interactivas, como enlaces y acciones de JavaScript
• Métodos para probar la salida PDF y garantizar los resultados esperados

Creación de archivos PDF con la API principal

La API Core es la base de la creación de PDF en Docotic.Pdf. Permite un control total y de bajo nivel sobre la colocación de texto, imágenes y gráficos vectoriales en un lienzo PDF mediante su API Canvas. Esta API de dibujo es un subconjunto de la API Core y proporciona los métodos y propiedades utilizados para añadir contenido a páginas y otros objetos con lienzos. Además de la representación, la API Core también admite anotaciones, campos de formulario, capas, marcadores y otras funciones de PDF.

A continuación, se muestra un código C# que crea un PDF sencillo mediante tres operaciones fundamentales: dibujar texto, colocar una imagen y representar gráficos vectoriales en un lienzo de página.

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

canvas.Font = pdf.CreateFont(PdfBuiltInFont.HelveticaBold);
canvas.FontSize = 14;
canvas.DrawString(40, 100, "Core API demo: text, images, and vector graphics");

var image = pdf.CreateImage("image.png");
canvas.DrawImage(image, 40, 180, 120, 120, 0);

canvas.Pen.Color = new PdfRgbColor(30, 60, 160);
canvas.Pen.Width = 2;
canvas.Brush.Color = new PdfRgbColor(200, 230, 255);
canvas.DrawRectangle(new PdfRectangle(200, 200, 150, 80), PdfDrawMode.FillAndStroke);

pdf.Save("core-api-demo.pdf");

Esta descripción general presenta solo una pequeña parte de las funcionalidades de la API principal. Para temas más avanzados, consulte el artículo detallado sobre la creación de archivos PDF con la API principal. El artículo abarca la medición de texto, el trabajo con espacios de color, la aplicación de recorte, el relleno de áreas con patrones, el manejo de la transparencia y otras capacidades.

Generación de archivos PDF con la API de diseño

La API de diseño es un motor de creación de documentos de alto nivel que proporciona la forma más sencilla y eficiente de generar PDF complejos y con gran cantidad de contenido.

Al usar la API, se componen PDF a partir de elementos estructurales como páginas, contenedores, fragmentos de texto, imágenes, tablas, enlaces, encabezados, pies de página y más. En lugar de calcular coordenadas o gestionar manualmente la paginación, se describe la estructura del documento y el motor de diseño se encarga del resto.

Este ejemplo ilustra cómo crear un PDF usando la API de diseño, basándose en el diseño declarativo en lugar del posicionamiento manual.

PdfDocumentBuilder.Create()
    .Info(info => info.Title = "Docotic.Pdf Layout API demo")
    .Generate("layout-api-demo.pdf", doc => doc.Pages(pages =>
    {
        pages.Content().Padding(100).Text(text =>
        {
            text.Span("The Layout API lets you compose PDFs from structural elements ");
            text.Line("without manually calculating coordinates or handling pagination.")
                .Style(s => s.Strong);
        });
    }));

Consulta la guía detallada para aprender a usar la API de diseño al generar archivos PDF en aplicaciones .NET.

Conversión de contenido web con la API de HTML a PDF

Docotic.Pdf, junto con su complemento gratuito HtmlToPdf, ofrece un motor de conversión de HTML a PDF moderno y de alta calidad basado en Chrome. Puede convertir HTML moderno y otros contenidos web, como imágenes SVG o WebP, en documentos PDF de alta calidad mediante la API proporcionada por el complemento.

La API de HTML a PDF puede crear PDF a partir de páginas HTML completas o fragmentos de HTML. Puede convertir contenido de URL, cadenas HTML sin formato y archivos HTML locales. Estas dos últimas opciones facilitan la generación de PDF a partir de plantillas HTML.

Vea un ejemplo de cómo generar un PDF a partir de una plantilla HTML:

public static async Task HelloHtmlTemplate()
{
    static string GetUserName()
    {
        // Replace with real logic: form input, API call, config, etc.
        return "World";
    }

    string html = $@"
        <h1>Hello, {GetUserName()}!</h1>
        <p>This PDF was generated from an HTML template.</p>";

    using var converter = await HtmlConverter.CreateAsync();
    using var pdf = await converter.CreatePdfFromStringAsync(html);
    pdf.Save("hello-html-template.pdf");
}

Para obtener más detalles y ejemplos, consulte nuestra guía detallada HTML-to-PDF overview.

Creación de archivos PDF a partir de imágenes

Docotic.Pdf ofrece una forma flexible y fácil de usar para desarrolladores de convertir imágenes a PDF. La biblioteca admite los formatos de imagen JPEG, BMP, GIF, PNG, TIFF y JPEG 2000 a través de la API principal.

Cuando el formato PDF lo admite, Docotic.Pdf inserta los bytes de la imagen tal cual, evitando la decodificación y recodificación de píxeles para preservar la compresión original. La biblioteca también conserva el espacio de color cuando es posible.

Además, la API de conversión de HTML a PDF admite los formatos SVG y WebP. Si necesita colocar imágenes junto a etiquetas o descripciones, la API de diseño le ayuda a organizar y alinear los elementos con el mínimo esfuerzo.

Cómo combinar varias imágenes en un solo PDF

Con Docotic.Pdf, puedes convertir fácilmente un conjunto de imágenes en un único PDF, colocando una imagen por página.

El ejemplo a continuación carga imágenes desde archivos y dibuja cada una en una página independiente. Cada imagen se ajusta al tamaño de la página y se centra para lograr un diseño limpio y uniforme.

public static void ImagesOnToPdf(string[] imagePaths, string outputPath)
{
    using var pdf = new PdfDocument();

    foreach (string path in imagePaths)
    {
        var image = pdf.CreateImage(path);

        var page = pdf.AddPage();
        var pageWidth = page.Width;
        var pageHeight = page.Height;

        var scale = Math.Min(pageWidth / image.Width, pageHeight / image.Height);
        var drawWidth = image.Width * scale;
        var drawHeight = image.Height * scale;
        var x = (pageWidth - drawWidth) / 2;
        var y = (pageHeight - drawHeight) / 2;

        page.Canvas.DrawImage(image, x, y, drawWidth, drawHeight, 0);
    }

    pdf.RemovePage(0);

    pdf.Save(outputPath);
}

Manejo de imágenes TIFF y GIF de varias páginas

Docotic.Pdf es totalmente compatible con archivos TIFF y GIF de varias páginas. Al añadir imágenes a un PDF, utilice el método OpenImage en lugar de CreateImage si alguna de las imágenes puede ocupar varias páginas.

El siguiente código muestra cómo convertir TIFF a PDF y funciona tanto para imágenes de una sola página como para imágenes de varias páginas:

public static void OddFramesToPdf(string[] imagePaths, string outputPath)
{
    using var pdf = new PdfDocument();
    foreach (string path in imagePaths)
    {
        var imageFrames = pdf.OpenImage(path);
        for (int i = 0; i < imageFrames.Count; i++)
        {
            if (i % 2 != 0)
                continue;

            var image = pdf.CreateImage(imageFrames[i]);
            var page = pdf.AddPage();

            page.Width = image.Width;
            page.Height = image.Height;

            page.Canvas.DrawImage(image, 0, 0, image.Width, image.Height, 0);
        }
    }

    pdf.RemovePage(0);

    pdf.Save(outputPath);
}

Puedes usar el mismo método para convertir GIF a PDF. También se aplica a otros formatos de imagen, aunque es más complejo de lo necesario para formatos que contienen un solo fotograma.

Combinar y dividir archivos PDF

Como biblioteca .NET completa, Docotic.Pdf permite crear nuevos PDF combinando, extrayendo y reorganizando páginas de documentos existentes.

Al combinar PDF, la biblioteca no solo añade páginas de otro documento, sino que también agrega capas, marcadores, etiquetas de página, JavaScript compartido, destinos (enlaces) y archivos incrustados. Para obtener más detalles y consejos sobre cómo reducir el tamaño de los PDF combinados, consulte el artículo sobre combinación de PDF.

Los PDF con firma digital no se pueden combinar sin invalidar sus firmas existentes. Para conservar las firmas, cree un portafolio de PDF en lugar de agregar documentos. Otra opción es combinar primero los PDF y luego aplicar una nueva firma digital al documento combinado.

Docotic.Pdf también permite copiar y extraer páginas en nuevos documentos. Se conserva todo el contenido asociado a las páginas copiadas, incluidas las anotaciones, los controles de formulario, el contenido estructurado, las capas y otros datos relacionados. Para ver ejemplos prácticos, consulte el artículo sobre Dividir archivos PDF en .NET. En él también se explica cómo extraer o eliminar páginas.

Trabajar con plantillas PDF

Las plantillas PDF son archivos PDF prediseñados que sirven como estructura base para crear nuevos documentos. Son útiles cuando se necesita generar PDF con un diseño uniforme, pero con datos diferentes. Si se desea separar el diseño visual de los datos, las plantillas PDF también son una buena opción.

Las plantillas pueden ser PDF con formularios o PDF estáticos sin formularios. Ambos tipos cumplen la misma función. Además, las plantillas con formularios incluyen elementos interactivos que, si no se integran, pueden recopilar información de los usuarios.

Creación de archivos PDF a partir de plantillas basadas en formularios

Las plantillas basadas en formularios suelen contener AcroForms, el tipo de formulario PDF interactivo estándar y ampliamente compatible. Para generar un PDF a partir de una plantilla de este tipo, normalmente se requiere:

• rellenar cada campo de marcador de posición
• aplanar los campos para evitar ediciones posteriores
• guardar el resultado como un nuevo PDF

A continuación, se muestra un código C# que busca un campo de texto de marcador de posición por su nombre, le asigna un valor, aplana el campo y guarda el resultado, creando un PDF a partir de la plantilla:

var nameOnCertificate = "Eva Marin";
using var pdf = new PdfDocument("certificate-template.pdf");
if (pdf.TryGetControl("name", out var field))
{
    if (field is PdfTextBox nameField)
    {
        nameField.Text = nameOnCertificate;
        nameField.Flatten();
    }
}

pdf.Save($"certificate-{nameOnCertificate}.pdf");

Si su plantilla contiene muchos marcadores de posición, puede importar datos FDF en lugar de rellenar cada campo individualmente. También puede usar PdfDocument.FlattenControls para aplanar todos los campos a la vez.

Creación de archivos PDF a partir de plantillas estáticas sin formularios

Si tu plantilla no contiene campos de formulario, deberás dibujar los nombres y otros datos directamente en el lienzo de la página. Las plantillas PDF estáticas suelen contener marcadores de posición visuales fijos, como texto, imágenes o áreas vacías. Para generar un PDF a partir de la plantilla, tendrás que rellenar estas áreas vacías y reemplazar el texto y las imágenes de los marcadores de posición mediante programación.

Áreas vacías

Utilice la API de Canvas para colocar texto e imágenes en áreas vacías. En casos sencillos, cuando solo necesita realizar cambios menores, como agregar un nombre y una foto, este método funciona bien. Necesita conocer las coordenadas y el tamaño de las áreas, y para posicionar el texto correctamente, es posible que deba medirlo primero y luego alinearlo en consecuencia.

Trabajar con texto de longitud variable o de varias líneas es más complejo, pero aún factible. Al combinar DrawText, DrawString y los métodos para medir texto, puede ajustar y posicionar las líneas según sea necesario. Si su plantilla contiene varias áreas de este tipo, considere un método alternativo, como generar archivos PDF con la API de Layout.

Texto de marcador de posición

Docotic.Pdf también ofrece métodos para buscar y reemplazar texto. Sin embargo, usar la búsqueda de texto como mecanismo de plantillas no suele ser más sencillo que trabajar con áreas de marcador de posición vacías. Antes de insertar contenido nuevo, debe localizar el fragmento de texto exacto y eliminarlo correctamente.

Imágenes de marcador de posición

Las plantillas estáticas pueden incluir imágenes de marcador de posición para avatares de usuario o fotos de productos. Para encontrar una imagen de marcador de posición, recorra la colección de imágenes que aparecen en cada página. Para cada imagen, puede obtener su tamaño y posición visibles. Para reemplazar la imagen de marcador de posición, utilice PdfImage.ReplaceWith.

using var pdf = new PdfDocument("invoice-template.pdf");
var paintedImages = pdf.Pages[0].GetPaintedImages();

var placeholder = paintedImages.First();
placeholder.Image.ReplaceWith("company-logo.jpg");

pdf.Save($"invoice.pdf");

Otra opción es dibujar una nueva imagen sobre el área ocupada por la imagen de marcador de posición, pero esto suele aumentar el tamaño del PDF resultante sin una buena razón.

Diseñar marcadores de posición para facilitar el reemplazo.

Para plantillas estáticas, es útil diseñar el diseño con regiones predecibles y bien definidas tanto para texto como para imágenes. Deje suficiente espacio alrededor de las áreas que contendrán contenido de longitud variable y utilice imágenes de marcador de posición neutras que coincidan con las proporciones que espera insertar posteriormente.

Si su plantilla utiliza texto de marcador de posición que planea reemplazar, puede simplificar el flujo de trabajo utilizando cuadros de texto en lugar de texto sin formato. Agregue un cuadro de texto de solo lectura y sin bordes a la plantilla e inserte el texto de marcador de posición dentro. Al generar el PDF final, abra la plantilla, localice el cuadro de texto por su nombre y asigne el nuevo valor directamente con box.Text = "nuevo texto";. Luego, aplane el cuadro de texto para evitar ediciones posteriores.

Agregar elementos interactivos

Las funciones interactivas transforman un PDF estático en un documento dinámico y fácil de navegar, enriquecido con anotaciones y marcas. Las acciones y JavaScript permiten la automatización directamente dentro del PDF.

Anotaciones

Las anotaciones son objetos que se adjuntan a una página y que representan comentarios, resaltados, archivos adjuntos y otros widgets interactivos. Son visibles en el contenido de la página y facilitan los flujos de trabajo de revisión y la colaboración.

El siguiente ejemplo en C# muestra cómo agregar anotaciones de texto, también conocidas como notas adhesivas, a una página PDF usando Docotic.Pdf.

using var pdf = new PdfDocument("example.pdf");
var page = pdf.Pages[0];

var textAnnot = page.AddTextAnnotation(new PdfPoint(50, 100), "Reviewer comment");
textAnnot.Contents = "Please check the figures on this page.";

pdf.Save("text-annotation.pdf");

El siguiente ejemplo muestra cómo resaltar texto y otro contenido para llamar la atención sobre las partes clave de un documento.

using var pdf = new PdfDocument("example.pdf");
var page = pdf.Pages[0];

var color = new PdfRgbColor(255, 255, 120);
var annotationText = "Please confirm this part.";
var bounds = new PdfRectangle(50, 250, 120, 40);
page.AddHighlightAnnotation(annotationText, bounds, color);

pdf.Save("highlight-annotation.pdf");

Enlaces

Los estándares PDF definen varios tipos de enlaces. Los más importantes y utilizados son los enlaces internos y los hipervínculos.

Los enlaces internos, también llamados acciones «Ir a», permiten saltar a una página o destino específico dentro del mismo PDF. Son útiles para referencias cruzadas y navegación interna.

A continuación, se muestra un código C# que crea un enlace desde la primera página a la página con índice 5:

using var pdf = new PdfDocument();
var page = pdf.Pages[0];

int targetPageIndex = 5;
for (int i = 0; i < targetPageIndex; i++)
    pdf.AddPage();

var rect = new PdfRectangle(50, 50, 100, 40);
page.Canvas.DrawRectangle(rect);
page.AddLinkToPage(rect, targetPageIndex);

pdf.Pages[targetPageIndex].Canvas.DrawString(50, 50, "Glad to have you here.");

pdf.Save("link-to-page.pdf");

La API de diseño ofrece otra forma de crear enlaces internos que no requiere posicionamiento absoluto.

Los enlaces externos, también llamados acciones URI, abren una URL web. Puede agregar un hipervínculo a una página PDF mediante el método PdfPage.AddHyperlink. En caso contrario, el procedimiento es el mismo que para los enlaces internos.

Marcadores

Los marcadores, también llamados esquemas, son accesos directos o enlaces especiales que ayudan a los lectores a navegar rápidamente a secciones o páginas específicas. Al hacer clic en un marcador, la aplicación de visualización salta a la parte designada del documento.

Los esquemas aparecen en el panel de marcadores del visor y proporcionan una estructura de navegación jerárquica similar a la tabla de contenido de un libro, pero interactiva. Los esquemas de PDF pueden incluir marcadores principales y marcadores anidados, lo que facilita la estructuración de documentos extensos.

El siguiente ejemplo muestra cómo crear marcadores en PDF usando C# y Docotic.Pdf. El código crea tres marcadores de nivel superior. El segundo marcador contiene un marcador anidado.

using var pdf = new PdfDocument();

for (int i = 0; i < 5; i++)
{
    var page = i == 0 ? pdf.Pages[0] : pdf.AddPage();

    var canvas = page.Canvas;
    canvas.FontSize = 14;
    canvas.DrawString(50, 50, $"Page {i + 1}");
}

var root = pdf.OutlineRoot;
root.AddChild("Getting Started", 1);

var child = root.AddChild("Things You Can Do", 2);
child.AddChild("Making Quick Improvements", 3);

root.AddChild("Keeping Everything Running Smoothly", 4);

pdf.PageMode = PdfPageMode.UseOutlines;

pdf.Save("bookmarks.pdf");

Los marcadores son diferentes de la tabla de contenido que se encuentra impresa en las páginas de un libro físico o en un PDF. Puedes crear una tabla de contenido mediante programación midiendo los encabezados y escribiendo entradas con números de página.

Para ver un método alternativo para crear una tabla de contenido usando la API de Layout, consulta el código correspondiente en nuestro repositorio de ejemplos.

Creación de scripts PDF

Las acciones de JavaScript se encuentran entre las funciones interactivas más potentes. PDF JavaScript es un subconjunto de JavaScript que expone las API del documento y del visor. Se utiliza para la validación de formularios, cálculos, diálogos de interfaz de usuario y pequeñas tareas de automatización.

Puede adjuntar scripts a anotaciones, marcadores, controles de formulario o acciones de apertura. Con Docotic.Pdf, puede insertar código JavaScript en un PDF. El código puede validar la entrada del formulario, calcular valores, mostrar u ocultar campos o realizar interacciones con el visor.

La colección de JavaScript compartido contiene scripts almacenados a nivel de documento. Estos scripts pueden ser reutilizados por múltiples acciones. En otras palabras, los scripts compartidos son útiles para funciones de utilidad y lógica compartida. Ayudan a reducir la duplicación y simplifican el mantenimiento.

El siguiente código define un script compartido que muestra un mensaje de alerta en el visor de PDF y luego muestra cómo activar ese script asignándolo a la acción de clic del botón.

using var pdf = new PdfDocument();

pdf.SharedScripts.Add(
    pdf.CreateJavaScriptAction("function messageBox(message) { app.alert(message,3); }")
);

var button = pdf.Pages[0].AddButton(50, 50, 100, 40);
button.Text = "Click me";
button.OnMouseUp = pdf.CreateJavaScriptAction("messageBox('Hello, dear!');");

pdf.Save("shared-javascript.pdf");

El script del ejemplo es sencillo, pero puedes crear acciones JavaScript de cualquier complejidad. La documentación de la API de JavaScript de Adobe proporciona muchos métodos que puedes usar. Ten en cuenta que los visores que no son de Adobe suelen ser compatibles solo con un subconjunto de la API.

Acciones abiertas

Una acción de apertura es una acción que el visor de PDF ejecuta al abrir el documento. Entre sus usos típicos se incluyen abrir en una página específica, ejecutar una rutina de inicialización de JavaScript o configurar las preferencias del visor. No existen restricciones en cuanto al tipo de acción de apertura.

El siguiente ejemplo muestra cómo crear una acción de apertura GoTo. El código añade texto a la segunda página y establece una acción de apertura que hace que el visor navegue automáticamente a esa página al abrir el PDF.

using var pdf = new PdfDocument();

var canvas = pdf.AddPage().Canvas;
canvas.FontSize = 14;

var message =
    "If you see this immediately after opening the file, " +
    "your PDF viewer supports open actions.";
var options = new PdfTextDrawingOptions(new PdfRectangle(100, 100, 100, 150));
canvas.DrawText(message, options);

pdf.OnOpenDocument = pdf.CreateGoToPageAction(1, 0);

pdf.Save("open-action.pdf");

Tenga en cuenta que no todos los visores ejecutan las acciones de apertura de JavaScript. Algunos las ignoran o solicitan la confirmación del usuario. Otros bloquean completamente las acciones de apertura.

Para comprobar si un PDF contiene una acción de apertura, cárguelo en un objeto PdfDocument e inspeccione la propiedad OnOpenDocument. Si la propiedad es null, el documento no tiene definida ninguna acción de apertura.

Aplicación de cifrado y firmas digitales

El cifrado y las firmas digitales abordan dos aspectos complementarios de la seguridad de los PDF que crea. El cifrado controla quién puede abrir un documento y qué acciones puede realizar con él, mientras que las firmas demuestran quién creó o aprobó el archivo y confirman que no ha sido modificado.

La protección con contraseña le permite establecer reglas de acceso durante la creación. Puede asignar una contraseña de apertura para restringir la visualización y una contraseña de propietario para definir permisos como imprimir, copiar, editar o completar formularios. El cifrado de certificados proporciona una protección más sólida y específica para cada destinatario, y resulta eficaz al distribuir PDF confidenciales a varias personas sin depender de una contraseña compartida. Para obtener más información, consulte el artículo sobre cifrado de PDF con contraseñas y certificados.

Las firmas digitales añaden autenticidad e integridad en el momento de la creación. Docotic.Pdf puede firmar PDF utilizando certificados de archivos, la Tienda Windows, tokens de hardware, HSM o servicios de claves en la nube. Puede incluir marcas de tiempo y datos de validación a largo plazo para que las firmas sigan siendo verificables mucho después de la creación del documento. También se admiten flujos de trabajo de firma externos, incluidos PKCS#11 y KMS en la nube.

Configuración de metadatos PDF

Los metadatos de un PDF son información descriptiva integrada en el documento, como el título, el autor, el asunto, las palabras clave, las fechas de creación y campos similares. Ayudan al software, a los motores de búsqueda y a los sistemas de gestión documental a comprender el contenido de un archivo sin necesidad de abrirlo.

Un documento PDF puede contener metadatos en dos sistemas coexistentes:

• Metadatos XMP
• Diccionario de información del documento (diccionario Info)

XMP es el formato más completo, estructurado y estandarizado para incrustar metadatos descriptivos. El diccionario Info es sencillo y cuenta con amplio soporte, pero es limitado y está obsoleto en el estándar PDF 2.0 (ISO 32000-2) en favor de los metadatos XMP. Docotic.Pdf puede leer y escribir en ambos sistemas y proporciona un método auxiliar para mantenerlos sincronizados.

Docotic.Pdf actualiza automáticamente algunos metadatos antes de guardar un archivo PDF. Por ejemplo, la biblioteca establece los valores de Productor y Creador por defecto. Utilice opciones de guardado para cambiar este comportamiento y conservar los valores de metadatos establecidos explícitamente.

Metadatos XMP

Utilice la propiedad PdfDocument.Metadata para acceder y modificar los metadatos XMP en un PDF. Mediante esta propiedad, puede trabajar con esquemas conocidos como XMP Core, Dublin Core y el esquema PDF, así como gestionar sus propios metadatos personalizados.

using var pdf = new PdfDocument();
var xmp = pdf.Metadata;

xmp.Pdf.Creator = new XmpString("Second-line authoring terminal");
xmp.Pdf.Title = new XmpString("Quarterly Report");

var creators = new XmpArray(XmpArrayType.Ordered);
creators.Values.Add(new XmpString("Second-line authoring terminal"));
creators.Values.Add(new XmpString("Assistive authoring terminal"));
xmp.DublinCore.Creators = creators;

var descriptions = new XmpArray(XmpArrayType.Alternative);
descriptions.Values.Add(new XmpLanguageAlternative("x-default", "Quarterly Report"));
descriptions.Values.Add(new XmpLanguageAlternative("fr", "Rapport trimestriel"));
descriptions.Values.Add(new XmpLanguageAlternative("de", "Quartalsbericht"));
xmp.DublinCore.Descriptions = descriptions;

var author1 = new XmpString("First Author");
author1.Qualifiers.Add("role", "main author");

var author2 = new XmpString("Second Author");
author2.Qualifiers.Add("role", "co-author");

var authors = new XmpArray(XmpArrayType.Unordered);
authors.Values.Add(author1);
authors.Values.Add(author2);
xmp.Custom.Properties.Add("authors", authors);

pdf.Save("with-xmp-metadata.pdf");

XMP admite matrices, estructuras y valores tipados, lo que lo hace ideal para metadatos complejos. El código anterior también muestra cómo almacenar propiedades específicas de la aplicación en el esquema XMP personalizado.

Diccionario de información de documentos

El diccionario Info almacena principalmente valores de cadenas de texto. Es compacto y cuenta con un amplio soporte, aunque tiene limitaciones. Utilice el diccionario Info para garantizar la compatibilidad con herramientas antiguas y, en otros casos, prefiera XMP.

Sincronización de metadatos

Es recomendable mantener sincronizados ambos sistemas de metadatos para evitar inconsistencias que puedan confundir a los lectores y a las herramientas automatizadas.

Utilice PdfDocument.SyncMetadata para alinear los valores XMP e Info de modo que los campos correspondientes coincidan. Este método completa las propiedades Info faltantes a partir de XMP y, de forma similar, rellena los campos XMP faltantes a partir de Info. Establezca preferXmp: true cuando XMP sea su fuente autorizada, o false cuando el diccionario Info deba tener prioridad.

pdf.SyncMetadata(preferXmp: true);

Consulte la sección Observaciones en la documentación de SyncMetadata para obtener información detallada sobre qué propiedades sincroniza el método.

Configuración de etiquetas de página y preferencias del visor

Un PDF recién creado puede beneficiarse de una numeración de página explícita, preferencias de visualización ajustadas y un diseño de página elegido para presentar el contenido del documento de forma más eficaz. Estos ajustes influyen en cómo los lectores ven y navegan por el archivo por primera vez.

Etiquetas de página

Las etiquetas de página son metadatos que indican a los lectores de PDF qué etiqueta mostrar para cada página. Úselas cuando la numeración visible deba diferir del índice físico de la página. Por ejemplo, cuando desee usar i, ii, iii para la información preliminar y 1, 2, 3 para el texto principal de su PDF.

Este código C# muestra cómo etiquetar las páginas de un PDF con números romanos en minúscula para las tres primeras páginas y numeración arábiga a partir del 1 para las demás.

using var pdf = new PdfDocument();

for (int i = 0; i < 8; i++)
    pdf.AddPage();

pdf.PageLabels.AddRange(0, 2, PdfPageNumberingStyle.LowercaseRoman);
pdf.PageLabels.AddRange(3, PdfPageNumberingStyle.DecimalArabic);

pdf.Save("with-page-labels.pdf");

Preferencias del visor de PDF

Las preferencias del visor de PDF son recomendaciones integradas en el documento que sugieren cómo debe presentarse. Por ejemplo, puede especificar que el visor oculte las barras de herramientas, centre la ventana o la ajuste a la página. Estas preferencias complementan la configuración del diseño de página y las acciones de apertura.

A continuación, se explica cómo cambiar las preferencias de visualización de PDF con Docotic.Pdf:

using var pdf = new PdfDocument();

pdf.ViewerPreferences.DisplayTitle = false;
pdf.ViewerPreferences.FitWindow = true;
pdf.ViewerPreferences.HideToolBar = true;
pdf.ViewerPreferences.HideMenuBar = true;
pdf.ViewerPreferences.HideWindowUI = true;
pdf.ViewerPreferences.CenterWindow = true;

pdf.Save("with-viewer-prefs.pdf");

Tenga en cuenta que, según su configuración, Adobe Acrobat y otros visores pueden ignorar estas preferencias.

Diseño de página y modo de página

El diseño de página determina cómo se organizan las páginas al abrir el documento: una página a la vez, una columna continua o dos páginas. El modo de página controla qué paneles de la interfaz de usuario se muestran al abrir el documento: marcadores/esquemas, archivos adjuntos, miniaturas o ninguno.

A continuación, se muestra cómo especificar que el PDF creado se muestre como dos páginas, con la página izquierda primero y el panel de miniaturas visible al abrirlo:

using var pdf = new PdfDocument();

for (int i = 0; i < 7; i++)
{
    var page = i > 0 ? pdf.AddPage() : pdf.Pages[0];
    page.Canvas.FontSize = 36;
    page.Canvas.DrawString(100, 100, $"Page {i + 1}");
}

pdf.PageLayout = PdfPageLayout.TwoPageLeft;
pdf.PageMode = PdfPageMode.UseThumbs;

pdf.Save("with-layout-and-mode.pdf");

Guardar archivos PDF

Docotic.Pdf puede generar diferentes archivos o flujos PDF a partir del mismo documento que usted creó o editó. Estos archivos pueden ajustarse a diferentes versiones del formato PDF, variar en tamaño y requerir diferentes cantidades de memoria para su generación.

La forma en que la biblioteca genera los bytes de un PDF depende de las opciones de guardado. Si no se especifican explícitamente las opciones de guardado, los métodos Save, SignAndSave y TimestampAndSave de un objeto PdfDocument utilizan la configuración predeterminada. Estos valores predeterminados se han seleccionado cuidadosamente y funcionan bien en la mayoría de los casos, pero es posible que deba ajustarlos.

Consulte la documentación de la clase PdfSaveOptions para obtener información detallada sobre las opciones disponibles y sus valores predeterminados. Las secciones siguientes destacan algunas de las opciones más importantes y proporcionan recomendaciones prácticas.

Versión PDF

Docotic.Pdf utiliza flujos de objetos por defecto para lograr una mejor compresión de los archivos que genera. Por lo tanto, la biblioteca crea archivos y flujos PDF 1.5 por defecto.

PDF 1.5 requiere Adobe Reader 6 (lanzado en 2003) o posterior para visualizar los documentos generados. Esto no suele ser un problema, a menos que necesite compatibilidad con herramientas antiguas, visores obsoletos o dispositivos integrados que solo acepten versiones anteriores de PDF.

A continuación, se explica cómo guardar con una versión anterior de un archivo PDF:

using var pdf = new PdfDocument();

var options = new PdfSaveOptions
{
    Version = PdfVersion.Pdf14,
    UseObjectStreams = false,
};
pdf.Save("version-1.4.pdf", options);

Para guardar con la versión PDF 1.4, también deben deshabilitarse las secuencias de objetos. La biblioteca no utilizará una versión anterior si el documento contiene características introducidas en versiones posteriores.

Reducción del tamaño del archivo

Varias opciones de guardado, al activarse, hacen que Docotic.Pdf genere archivos más pequeños (en cuanto a tamaño): RemoveUnusedObjects, OptimizeIndirectObjects, WriteWithoutFormatting y UseObjectStreams.

A continuación, se explica cómo generar archivos PDF sin objetos sin referencia ni espacios en blanco adicionales, con los datos compactados en flujos de objetos:

using var pdf = new PdfDocument();

var options = new PdfSaveOptions
{
    UseObjectStreams = true,
    RemoveUnusedObjects = true,
    OptimizeIndirectObjects = true,
    WriteWithoutFormatting = true,
};
pdf.Save("optimized.pdf", options);

Estas opciones son más efectivas cuando el PDF se reescribe por completo. Durante un guardado incremental, se aplican solo a la revisión recién añadida y no pueden limpiar ni optimizar las partes anteriores del archivo.

Actualizaciones incrementales

Docotic.Pdf permite actualizar archivos PDF de forma incremental. Cuando WriteIncrementally es true, la biblioteca añade los cambios al archivo existente en lugar de sobrescribirlo. Los datos de referencias cruzadas y de objetos anteriores permanecen intactos. Los datos añadidos se denominan actualización incremental, y la actualización actual, junto con todas las anteriores, constituye una nueva revisión del archivo.

Las actualizaciones incrementales no son posibles para documentos recién creados, ya que no existe una revisión anterior a la que añadir los cambios. La biblioteca ignora esta opción para los documentos nuevos y los escribe en modo no incremental.

Cuando se requieren actualizaciones incrementales

Al añadir una nueva firma digital a un documento que ya contiene firmas, debe guardar el archivo de forma incremental. Lo mismo se aplica al actualizar un archivo previamente firmado con nuevas anotaciones o datos de formulario. En estos casos, reescribir el archivo completo invalidaría las firmas existentes.

Asimismo, es recomendable realizar un guardado completo (no incremental) antes de aplicar la primera firma digital, de modo que la versión firmada sea un archivo limpio y completamente reescrito. Firmar un documento con problemas estructurales en revisiones anteriores puede provocar problemas inesperados de validación de firmas.

Las adiciones incrementales también son necesarias en flujos de trabajo que deben conservar un historial de revisiones auditable o que exigen el almacenamiento de documentos solo para adiciones.

Ventajas de usar actualizaciones incrementales

Las actualizaciones incrementales permiten múltiples firmas en el mismo archivo y posibilitan un conjunto limitado de modificaciones posteriores a la firma, como rellenar campos de formulario, sin invalidar las firmas existentes.

Este método también permite guardar cambios menores con mayor rapidez, ya que solo se escriben los datos modificados. Además, conserva el historial de revisiones del documento, lo cual es fundamental para auditorías y otros flujos de trabajo que requieren cumplimiento normativo.

Problemas y trampas que se deben evitar

Las actualizaciones incrementales no pueden aplicar compresión global ni eliminar objetos obsoletos en todo el archivo, ya que solo añaden los objetos modificados. Por lo general, generan archivos más grandes y menos optimizados que una reescritura completa.

El tamaño del archivo aumenta con cada revisión, incluso cuando no hay objetos sin usar, porque todas las revisiones anteriores permanecen integradas en el archivo y siguen ocupando espacio.

La información confidencial o incorrecta de revisiones anteriores se puede recuperar, y los problemas de formato PDF o los defectos estructurales existentes en revisiones anteriores no se corrigen al añadir nuevos datos.

Por último, algunos visores y herramientas de procesamiento tienen dificultades con los PDF de múltiples revisiones. Antes de utilizar actualizaciones incrementales, asegúrese de que todos los usuarios de sus documentos puedan manejar archivos con múltiples revisiones.

Probando la salida PDF

Las pruebas automatizadas de PDF protegen las versiones de errores de contenido y diseño al comparar los PDF generados con los PDF de referencia almacenados en su repositorio o repositorio de artefactos. Las referencias ayudan a detectar cambios accidentales en texto, fuentes, imágenes o diseño, y reducen la necesidad de control de calidad manual en cada compilación.

Combine comprobaciones estructurales, extracción de texto y comparaciones visuales para obtener los resultados más fiables.

Comparación rápida de enfoques

Comparación de la estructura del documento

Utilice PdfDocument.DocumentsAreEqual para comparar gráficos de objetos PDF, la versión del PDF y el almacén de seguridad del documento (DSS), ignorando las propiedades del documento dependientes del tiempo. Este método también ignora los metadatos del documento, los identificadores de pie de página y otras propiedades generadas automáticamente.

Este método es ideal para flujos de trabajo de prueba de documentos PDF que deben garantizar que no se hayan agregado ni eliminado objetos inesperados. DocumentsAreEqual admite sobrecargas de archivos y flujos, y puede comparar PDF cifrados.

Un ejemplo completo que demuestra esta técnica está disponible en los ejemplos de Docotic.Pdf. Además de mostrar cómo usar el método en aplicaciones .NET estándar, el ejemplo también muestra cómo usar DocumentsAreEqual en aplicaciones AOT nativas.

Verificación de archivos PDF mediante texto extraído

Extraiga el texto del documento completo de una vez o de páginas individuales una tras otra y compare las cadenas. Puede usar las opciones de extracción de texto para ajustar el proceso, como excluir el rectángulo del pie de página. Para facilitar la comparación, puede dividir el texto extraído en líneas o palabras.

Para realizar comprobaciones estructuradas, primero extraiga el texto con la posición, la fuente y otra información detallada sobre cada fragmento, palabra o carácter. Luego, compare cada elemento extraído con el elemento de referencia correspondiente.

Detección de diferencias visuales

Comience por convertir las páginas PDF a imágenes y compare cada imagen con la imagen de referencia. Utilice bibliotecas especializadas como ImageSharp.Compare o Magick.NET para detectar diferencias entre las imágenes.

Se recomienda una comparación estricta píxel a píxel, de modo que cada píxel correspondiente en ambas imágenes coincida. Si sus requisitos permiten pequeñas variaciones en la renderización, puede ajustar la lógica de comparación para tolerar diferencias menores, pero la igualdad exacta de píxeles proporciona los resultados más fiables.

Considere utilizar el hashing como una verificación previa rápida para determinar si dos imágenes son probablemente idénticas sin realizar una comparación completa de píxeles. Calcule un hash SHA-256 para cada imagen renderizada y, si los hashes coinciden, las imágenes son casi con seguridad idénticas. Si los hashes difieren, realice la comparación completa píxel a píxel.

Conclusión

Docotic.Pdf proporciona un conjunto de herramientas integral y multicapa para crear y manipular archivos PDF en .NET. Los desarrolladores pueden elegir entre el control de bajo nivel con la API Core, la generación de documentos de alto nivel con la API Layout o la conversión de HTML a PDF para flujos de trabajo ya basados ​​en tecnologías web.

La biblioteca también admite archivos PDF basados ​​en imágenes, generación mediante plantillas y un amplio conjunto de funciones interactivas como anotaciones, enlaces, marcadores, acciones de JavaScript y acciones de apertura.

Para garantizar la fiabilidad, Docotic.Pdf incluye métodos para probar la salida de PDF, de modo que los cambios en la aplicación no introduzcan regresiones ni diferencias inesperadas.