Come creare documenti PDF in C# e VB.NET

Tradotto da Bit Miracle. Articolo originale di Vitaliy Shibaev

Aggiornato il 29 giugno 2026

Questo articolo descrive diversi modi per creare documenti PDF in .NET con l'aiuto della libreria Docotic.Pdf. Si tratta di una libreria .NET pura in C#, ad alte prestazioni e senza dipendenze esterne per creare, modificare, convertire ed elaborare documenti PDF.

Nelle sezioni seguenti presento i principali approcci per creare PDF con Docotic.Pdf:

• Usando Core API, che fornisce controllo di basso livello su testo, grafica e interni PDF. Questa opzione è ideale per layout personalizzati, documenti molto ricchi di grafica e funzionalità avanzate.
• Usando la Layout API di alto livello, che supporta paragrafi, tabelle, intestazioni, piè di pagina e impaginazione automatica. Questa API è ideale quando vuoi documenti strutturati senza calcolare manualmente le posizioni.
• Conversione di HTML in PDF con supporto per SVG e altri formati web. Questo approccio è particolarmente utile quando la tua soluzione produce già documenti HTML e ti servono versioni PDF di quei file HTML e CSS.
• Creazione di PDF da immagini. Questo metodo è utile per documenti scansionati, report basati su immagini, ricevute e qualsiasi flusso di lavoro che parte da immagini raster.
• Unione o suddivisione di PDF. Questa è una buona scelta per assemblare report, elaborare caricamenti degli utenti, combinare documenti correlati e ristrutturare PDF di grandi dimensioni.
• Creazione di PDF da modelli. Questo approccio funziona bene quando è richiesta una formattazione coerente per documenti generati in batch come ricevute, moduli fiscali, contratti di lavoro e altri tipi di documenti ripetibili.

Gli argomenti aggiuntivi trattati nella guida includono:

• Funzionalità interattive come collegamenti e azioni JavaScript
• Approcci per testare l'output PDF e garantire risultati attesi

Creazione di PDF con Core API

Core API è la base della creazione di PDF in Docotic.Pdf. Ti offre il pieno controllo di basso livello sul posizionamento di testo, immagini e grafica vettoriale su un canvas PDF tramite la sua Canvas API. Questa API di disegno è un sottoinsieme della Core API e fornisce i metodi e le proprietà usati per aggiungere contenuti alle pagine e ad altri oggetti con canvas. Oltre al rendering, Core API supporta anche annotazioni, campi modulo, livelli, segnalibri e altre funzionalità PDF.

Ecco il codice C# che crea un PDF semplice usando tre operazioni fondamentali: disegnare testo, posizionare un'immagine e renderizzare grafica vettoriale su un canvas di pagina.

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");

Questa panoramica introduce solo una piccola parte di ciò che Core API può fare. Per argomenti avanzati, consulta l'articolo dettagliato sulla creazione di PDF con Core API. L'articolo copre la misurazione del testo, il lavoro con gli spazi colore, l'applicazione del clipping, il riempimento di aree con pattern, la gestione della trasparenza e altre funzionalità.

Generazione di PDF con Layout API

Layout API è un motore di creazione documenti di alto livello che offre il modo più semplice ed efficiente per generare PDF complessi e ricchi di contenuti.

Quando usi l'API, componi i PDF a partire da elementi strutturali come pagine, contenitori, span di testo, immagini, tabelle, collegamenti, intestazioni, piè di pagina e altro ancora. Invece di calcolare coordinate o gestire manualmente l'impaginazione, descrivi la struttura del documento e lasci che il motore di layout gestisca il resto.

Questo esempio illustra come creare un PDF usando Layout API, affidandosi al layout dichiarativo invece del posizionamento manuale.

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 guida approfondita per imparare a usare Layout API quando generi PDF in applicazioni .NET.

Conversione di contenuti web con HTML to PDF API

Docotic.Pdf, insieme al suo componente aggiuntivo gratuito HtmlToPdf, offre un motore HTML-to-PDF moderno, di alta qualità e basato su Chrome. Puoi trasformare HTML moderno e altri contenuti web, come immagini SVG o WebP, in documenti PDF di alta qualità usando l'API fornita dal componente aggiuntivo.

HTML to PDF API può creare PDF da pagine HTML complete o da frammenti HTML. Puoi convertire contenuti da URL, stringhe HTML grezze e file HTML locali. Le ultime due opzioni rendono facile generare PDF da modelli HTML.

Vedi un esempio di come produrre un PDF da un modello HTML:

public static async Task HelloHtmlTemplate()
{
    static string GetUserName()
    {
        // Sostituisci con logica reale: input del modulo, chiamata API, configurazione, ecc.
        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");
}

Per maggiori dettagli ed esempi, consulta la nostra panoramica HTML-to-PDF.

Creazione di PDF da immagini

Docotic.Pdf offre un modo flessibile e adatto agli sviluppatori per convertire immagini in PDF. La libreria supporta i formati immagine JPEG, BMP, GIF, PNG, TIFF e JPEG 2000 tramite Core API.

Quando supportato dal formato PDF, Docotic.Pdf incorpora i byte dell'immagine così come sono, evitando la decodifica dei pixel e la ricodifica per preservare la compressione originale. La libreria preserva anche lo spazio colore quando possibile.

Inoltre, i formati SVG e WebP sono supportati tramite HTML to PDF API. Quando devi inserire immagini accanto alle etichette o alle descrizioni, Layout API ti aiuta a disporre e allineare gli elementi con il minimo sforzo.

Come combinare diverse immagini in un unico PDF

Con Docotic.Pdf puoi convertire facilmente un insieme di immagini in un singolo PDF, posizionando una immagine per ogni pagina.

L'esempio seguente carica le immagini dai file e disegna ciascuna su una propria pagina. Ogni immagine viene scalata per adattarsi alla pagina e centrata per un layout pulito e coerente.

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);
}

Gestione di immagini TIFF e GIF multipagina

Docotic.Pdf supporta completamente i file TIFF e GIF multipagina. Quando aggiungi immagini a un PDF, usa il metodo OpenImage invece di CreateImage se alcune immagini possono contenere più pagine.

Il codice seguente mostra come convertire TIFF in PDF e funziona sia per immagini a pagina singola sia per immagini multipagina:

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);
}

Puoi usare lo stesso approccio per convertire GIF in PDF. Si applica anche ad altri formati immagine, anche se per i formati che contengono un solo frame è più elaborato del necessario.

Unione e suddivisione dei PDF

Come libreria .NET completa, Docotic.Pdf può creare nuovi PDF unendo, estraendo e riorganizzando pagine da documenti esistenti.

Quando unisci PDF, la libreria non solo aggiunge pagine da un altro documento, ma accoda anche livelli, segnalibri, etichette di pagina, JavaScript condiviso, destinazioni (target dei collegamenti) e file incorporati. Per maggiori dettagli e indicazioni su come ridurre le dimensioni dei PDF combinati, consulta l'articolo su come unire i PDF.

I PDF firmati digitalmente non possono essere uniti senza invalidare le firme esistenti. Per preservare le firme, crea un portfolio PDF invece di accodare i documenti. Un'altra opzione è unire prima i PDF e poi applicare una nuova firma digitale al documento combinato.

Docotic.Pdf consente anche di copiare ed estrarre pagine in nuovi documenti. Tutti i contenuti associati alle pagine copiate vengono preservati, incluse annotazioni, controlli modulo, contenuti strutturati, livelli e altri dati correlati. Per esempi pratici, consulta l'articolo su come suddividere i PDF in .NET. Spiega anche come estrarre o rimuovere pagine.

Lavorare con i modelli PDF

I modelli PDF sono file PDF predefiniti che fungono da struttura di base per creare nuovi documenti. Sono utili quando devi produrre PDF con un layout coerente fornendo dati diversi. Se vuoi separare il design visivo dai dati stessi, i modelli PDF sono anche una buona scelta.

I modelli possono essere PDF basati su moduli oppure PDF statici senza moduli. Entrambi i tipi servono allo stesso scopo. Inoltre, i modelli basati su moduli includono elementi interattivi che, se non vengono appiattiti, possono raccogliere informazioni dagli utenti.

Creazione di PDF da modelli basati su moduli

I modelli basati su moduli in genere contengono AcroForms, il tipo standard e ampiamente supportato di modulo PDF interattivo. Per generare un PDF da un modello di questo tipo, in genere devi:

• compilare ogni campo segnaposto
• appiattire i campi per impedire ulteriori modifiche
• salvare il risultato come nuovo PDF

Ecco il codice C# che trova per nome un campo di testo segnaposto, gli assegna un valore, appiattisce il campo e salva il risultato, creando un PDF dal modello:

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");

Se il tuo modello contiene molti segnaposto, puoi importare dati FDF invece di compilare ogni campo singolarmente. Puoi anche usare PdfDocument.FlattenControls per appiattire tutti i campi in una volta.

Creazione di PDF da modelli statici senza moduli

Se il tuo modello non contiene campi modulo, dovrai disegnare nomi e altri dati direttamente sul canvas della pagina. I modelli PDF statici in genere contengono segnaposto visivi fissi come testo, immagini o aree vuote. Per produrre un PDF dal modello, dovrai riempire queste aree vuote e sostituire programmaticamente il testo e le immagini segnaposto.

Aree vuote

Usa la Canvas API per posizionare testo e immagini nelle aree vuote. In casi semplici, quando servono solo piccole modifiche come aggiungere un nome e una foto, questo approccio funziona bene. Devi conoscere le coordinate e le dimensioni delle aree e, per posizionare correttamente il testo, potresti doverlo prima misurare e poi allinearlo di conseguenza.

Lavorare con testo a lunghezza variabile o su più righe è più complesso, ma comunque fattibile. Combinando DrawText, DrawString e i metodi per misurare il testo, puoi andare a capo e posizionare le righe come necessario. Se il tuo modello contiene più di poche aree di questo tipo, prendi in considerazione un approccio alternativo come la generazione di PDF con Layout API.

Testo segnaposto

Docotic.Pdf fornisce anche metodi per trovare e sostituire testo. Tuttavia, usare la ricerca testuale come meccanismo di templating di solito non è più semplice che lavorare con aree vuote segnaposto. Prima di inserire nuovo contenuto, devi individuare il frammento di testo esatto e rimuoverlo in modo pulito.

Immagini segnaposto

I modelli statici possono includere immagini segnaposto per avatar utente o foto di prodotto. Per trovare un'immagine segnaposto, enumera la raccolta di immagini disegnate su ogni pagina. Per ogni immagine disegnata puoi ottenere le sue dimensioni visibili e la sua posizione. Per sostituire il segnaposto, usa 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");

Un'altra opzione è disegnare una nuova immagine sopra l'area occupata dall'immagine segnaposto, ma in genere ciò aumenta le dimensioni del PDF risultante senza un buon motivo.

Progettare segnaposto per una facile sostituzione

Per i modelli statici, è utile progettare il layout con regioni prevedibili e ben definite sia per il testo sia per le immagini. Lascia sufficiente spazio attorno alle aree che conterranno contenuti a lunghezza variabile e usa immagini segnaposto neutre che corrispondano ai rapporti d'aspetto che prevedi di inserire in seguito.

Se il tuo modello usa testo segnaposto che intendi sostituire, puoi semplificare il flusso di lavoro usando caselle di testo invece del testo grezzo. Aggiungi al modello una casella di testo sola lettura, senza bordi, e inserisci al suo interno il testo segnaposto. Quando generi il PDF finale, apri il modello, individua la casella di testo per nome e assegna direttamente il nuovo valore con box.Text = "new text";. Quindi appiattisci la casella di testo per impedire ulteriori modifiche.

Aggiunta di elementi interattivi

Le funzionalità interattive trasformano un PDF statico in un documento dinamico e facile da navigare, arricchito con annotazioni e markup. Le azioni e JavaScript consentono l'automazione direttamente all'interno del PDF.

Annotazioni

Le annotazioni sono oggetti associati a una pagina che rappresentano commenti, evidenziazioni, allegati di file e altri widget interattivi. Sono visibili nel contenuto della pagina e supportano flussi di revisione e collaborazione.

Il seguente esempio C# mostra come aggiungere annotazioni di testo, note anche come sticky note, a una pagina 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");

L'esempio successivo mostra come evidenziare testo e altri contenuti per richiamare l'attenzione sulle parti chiave di 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");

Link

Gli standard PDF definiscono diversi tipi di link PDF. I più importanti e più utilizzati sono i link interni e i collegamenti ipertestuali.

I link interni, chiamati anche azioni GoTo, consentono di saltare a una pagina o a una destinazione denominata all'interno dello stesso PDF. Sono utili per riferimenti incrociati e navigazione interna.

Ecco il codice C# che crea un link dalla prima pagina alla pagina con indice uguale a 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");

Layout API offre un altro modo per creare link interni che non richiede posizionamento assoluto.

I link esterni, chiamati anche azioni URI, aprono un URL web. Puoi aggiungere un collegamento ipertestuale a una pagina PDF usando il metodo PdfPage.AddHyperlink. Per il resto, l'approccio è lo stesso dei link interni.

Segnalibri

I segnalibri, chiamati anche outlines, sono scorciatoie o link speciali che aiutano i lettori a navigare rapidamente verso sezioni o pagine specifiche. Quando il lettore fa clic su un segnalibro, l'applicazione visualizzatrice salta alla parte designata del documento.

Gli outlines appaiono nel pannello dei segnalibri del visualizzatore e forniscono una struttura gerarchica di navigazione simile a un indice di un libro, ma interattiva. Gli outline PDF possono includere segnalibri principali e segnalibri nidificati, il che facilita la strutturazione di documenti di grandi dimensioni.

L'esempio seguente mostra come creare segnalibri nei PDF usando C# e Docotic.Pdf. Il codice crea tre segnalibri di primo livello. Il secondo segnalibro contiene un segnalibro nidificato.

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");

I segnalibri sono diversi dall'indice che potresti trovare stampato sulle pagine di un libro fisico o visualizzato in un PDF. Puoi creare un indice programmaticamente misurando le intestazioni e scrivendo le voci con i numeri di pagina.

Per vedere un approccio alternativo alla creazione di un indice usando Layout API, dai un'occhiata al codice correlato nel nostro repository di esempi.

Scripting PDF

Le azioni JavaScript sono tra le funzionalità interattive più potenti. PDF JavaScript è un sottoinsieme di JavaScript che espone API del documento e del visualizzatore. Viene usato per la convalida dei moduli, i calcoli, le finestre di dialogo dell'interfaccia utente e piccole attività di automazione.

Puoi associare script ad annotazioni, segnalibri, controlli modulo o azioni di apertura. Con Docotic.Pdf puoi incorporare codice JavaScript in un PDF. Il codice può convalidare l'input dei moduli, calcolare valori, mostrare o nascondere campi oppure eseguire interazioni con il visualizzatore.

La raccolta di JavaScript condiviso contiene script archiviati a livello di documento. Questi script possono essere riutilizzati da più azioni. In altre parole, gli script condivisi sono utili per funzioni di utilità e logica condivisa. Aiutano a ridurre la duplicazione e semplificano la manutenzione.

Il codice seguente definisce uno script condiviso che visualizza un messaggio di avviso nel visualizzatore PDF e poi mostra come attivare quello script assegnandolo all'azione di click del pulsante.

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");

Lo script nell'esempio è semplice, ma puoi costruire azioni JavaScript di qualsiasi complessità. La documentazione di riferimento Adobe JavaScript API offre molti metodi che puoi usare. Tieni presente che i visualizzatori non Adobe di solito supportano solo un sottoinsieme dell'API.

Azioni di apertura

Un'azione di apertura è un'azione che il visualizzatore PDF esegue quando il documento viene aperto. Gli usi tipici includono l'apertura a una pagina specifica, l'esecuzione di una routine di inizializzazione JavaScript o l'impostazione delle preferenze del visualizzatore. Non ci sono restrizioni sul tipo di azione di apertura.

L'esempio seguente mostra come creare un'azione di apertura GoTo. Il codice aggiunge testo alla seconda pagina e imposta un'azione di apertura che fa sì che il visualizzatore navighi automaticamente a quella pagina quando il PDF viene aperto.

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");

Nota che non tutti i visualizzatori eseguono le azioni di apertura JavaScript. Alcuni le ignorano o chiedono prima conferma all'utente. Alcuni visualizzatori bloccano del tutto le azioni di apertura.

Per verificare se un PDF contiene un'azione di apertura, caricalo in un PdfDocument e controlla la proprietà OnOpenDocument. Se la proprietà è null, il documento non ha alcuna azione di apertura definita.

Applicazione di crittografia e firme digitali

La crittografia e le firme digitali affrontano due aspetti complementari della protezione dei PDF che crei. La crittografia controlla chi può aprire un documento e cosa può farne, mentre le firme dimostrano chi ha creato o approvato il file e confermano che non è stato alterato.

La protezione con password ti consente di impostare regole di accesso durante la creazione. Puoi assegnare una password di apertura per limitare la visualizzazione e una password del proprietario per definire autorizzazioni come stampa, copia, modifica o compilazione dei moduli. La crittografia con certificato offre una protezione più forte e specifica per il destinatario e funziona bene quando distribuisci PDF riservati a più persone senza affidarti a una password condivisa. Per maggiori dettagli, consulta l'articolo su come crittografare i PDF con password e certificati.

Le firme digitali aggiungono autenticità e integrità al momento della creazione. Docotic.Pdf può firmare i PDF usando certificati da file, dall'archivio Windows, token hardware, HSM o servizi cloud di gestione chiavi. Puoi includere timestamp e dati di convalida a lungo termine in modo che le firme restino verificabili anche molto tempo dopo la generazione del documento. Sono supportati anche flussi di firma esterni, inclusi PKCS#11 e cloud KMS.

Impostazione dei metadati PDF

I metadati PDF sono informazioni descrittive incorporate in un documento, come titolo, autore, argomento, parole chiave, date di creazione e campi simili. Aiutano software, motori di ricerca e sistemi di gestione documentale a capire di cosa tratta un file senza aprirlo.

Un documento PDF può contenere metadati in due sistemi che coesistono:

• metadati XMP
• dizionario delle informazioni del documento (Info dictionary)

XMP è il formato più ricco, strutturato e standardizzato per incorporare metadati descrittivi. Il dizionario Info è semplice e ampiamente supportato, ma limitato, ed è deprecato nello standard PDF 2.0 (ISO 32000‑2) a favore dei metadati XMP. Docotic.Pdf può leggere e scrivere entrambi i sistemi e fornisce un metodo di supporto per mantenerli sincronizzati.

Docotic.Pdf aggiorna automaticamente alcuni metadati prima di salvare un file PDF. Ad esempio, la libreria imposta i valori Producer e Creator per impostazione predefinita. Usa le opzioni di salvataggio per modificare questo comportamento e mantenere i valori dei metadati impostati esplicitamente.

Metadati XMP

Usa la proprietà PdfDocument.Metadata per accedere e modificare i metadati XMP in un PDF. Tramite questa proprietà puoi lavorare con schemi noti come XMP Core, Dublin Core e lo schema PDF, oltre a gestire i tuoi metadati personalizzati.

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 supporta array, strutture e valori tipizzati, il che lo rende adatto a metadati ricchi. Il codice sopra mostra anche come archiviare proprietà specifiche dell'applicazione nello schema XMP personalizzato.

Dizionario delle informazioni del documento

Il dizionario Info memorizza principalmente valori di stringa di testo. È compatto e ampiamente supportato, ma limitato. Usa il dizionario Info per la compatibilità con strumenti meno recenti e preferisci XMP negli altri casi.

Sincronizzazione dei metadati

È buona pratica mantenere sincronizzati entrambi i sistemi di metadati per evitare incoerenze che potrebbero confondere lettori e strumenti automatizzati.

Usa PdfDocument.SyncMetadata per allineare i valori XMP e Info in modo che i campi corrispondenti coincidano. Il metodo completa le proprietà Info mancanti a partire da XMP e, analogamente, popola i campi XMP mancanti da Info. Imposta preferXmp: true quando XMP è la tua fonte autorevole, oppure false quando il dizionario Info deve avere la precedenza.

pdf.SyncMetadata(preferXmp: true);

Consulta la sezione Remarks nella documentazione di SyncMetadata per informazioni dettagliate su quali proprietà il metodo sincronizza.

Configurazione delle etichette di pagina e delle preferenze del visualizzatore

Un PDF appena creato può trarre vantaggio da una numerazione esplicita delle pagine, da preferenze del visualizzatore ottimizzate e da un layout di pagina scelto per presentare il contenuto del documento in modo più efficace. Queste impostazioni influenzano il modo in cui i lettori vedono e navigano il file all'apertura.

Etichette di pagina

Le etichette di pagina sono metadati che indicano ai visualizzatori PDF quale etichetta visualizzare per ogni pagina. Usale quando la numerazione visibile deve differire dall'indice fisico delle pagine. Ad esempio, quando vuoi i, ii, iii per le pagine preliminari e 1, 2, 3 per il testo principale del tuo PDF.

Questo codice C# mostra come etichettare le pagine PDF con numeri romani minuscoli per le prime tre pagine e numerazione araba a partire da 1 per le restanti.

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");

Preferenze del visualizzatore PDF

Le preferenze del visualizzatore PDF sono raccomandazioni incorporate nel documento che suggeriscono al visualizzatore come presentarlo. Ad esempio, puoi specificare che il visualizzatore debba nascondere le barre degli strumenti, centrare la finestra o adattare la finestra alla pagina. Le preferenze del visualizzatore si completano con il layout di pagina e con le impostazioni di azione di apertura.

Ecco come modificare le preferenze di visualizzazione PDF usando 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");

Tieni presente che, a seconda della loro configurazione, Adobe Acrobat e altri visualizzatori possono ignorare queste preferenze.

Layout di pagina e modalità pagina

Il layout di pagina determina come vengono disposte le pagine all'apertura del documento: una pagina alla volta, flusso continuo a una colonna o affiancamento di due pagine. La modalità pagina controlla quali pannelli dell'interfaccia utente sono visibili all'apertura: segnalibri/outline, allegati, miniature o nessuno.

Ecco come specificare che il PDF creato deve essere visualizzato come affiancamento di due pagine, con la pagina sinistra per prima, e con il pannello delle miniature visibile all'apertura:

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");

Salvataggio dei PDF

Docotic.Pdf può produrre file o stream PDF diversi dallo stesso documento che hai creato o modificato. Questi output possono conformarsi a versioni diverse del formato PDF, variare nella lunghezza in byte e richiedere quantità diverse di memoria per essere generati.

Il modo in cui la libreria produce i byte di un PDF dipende dalle opzioni di salvataggio. Quando non specifichi esplicitamente le opzioni di salvataggio, i metodi Save, SignAndSave e TimestampAndSave di un oggetto PdfDocument usano impostazioni predefinite. Queste impostazioni sono state scelte con cura e funzionano bene per la maggior parte degli scenari, ma potresti comunque doverle adattare.

Consulta la documentazione della classe PdfSaveOptions per informazioni dettagliate sulle opzioni disponibili e sui loro valori predefiniti. Le sezioni seguenti evidenziano alcune delle opzioni più importanti e forniscono raccomandazioni pratiche.

Versione PDF

Docotic.Pdf usa per impostazione predefinita gli object streams per ottenere una migliore compressione dei file che produce. Di conseguenza, la libreria crea per default file e stream PDF 1.5.

PDF 1.5 richiede Adobe Reader 6 (rilasciato nel 2003) o più recente per visualizzare i documenti prodotti. Di solito non è un problema, a meno che tu non debba supportare strumenti legacy, visualizzatori meno recenti o dispositivi incorporati che accettano solo versioni PDF più vecchie.

Ecco come salvare con una versione di file PDF più vecchia:

using var pdf = new PdfDocument();

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

Per salvare con la versione PDF 1.4, anche gli object streams devono essere disabilitati. La libreria non userà una versione più vecchia se il documento contiene funzionalità introdotte in versioni successive.

Riduzione delle dimensioni del file

Diverse opzioni di salvataggio, quando impostate su true, fanno sì che Docotic.Pdf produca file più piccoli in termini di byte: RemoveUnusedObjects, OptimizeIndirectObjects, WriteWithoutFormatting e UseObjectStreams.

Ecco come produrre PDF senza oggetti non referenziati e spazi bianchi extra, con i dati compressi in modo compatto negli object streams:

using var pdf = new PdfDocument();

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

Queste opzioni sono più efficaci quando il PDF viene riscritto completamente. Durante un salvataggio incrementale, si applicano solo alla revisione appena aggiunta e non possono pulire o ottimizzare le parti precedenti del file.

Aggiornamenti incrementali

Docotic.Pdf può aggiornare i PDF in modo incrementale. Quando WriteIncrementally è true, la libreria accoda le modifiche al file esistente invece di riscriverlo. I dati precedenti dei riferimenti incrociati e degli oggetti restano intatti. I dati accodati sono chiamati aggiornamento incrementale e l'aggiornamento corrente, insieme a tutti quelli precedenti, costituisce una nuova revisione del file.

Gli aggiornamenti incrementali non sono possibili per i documenti appena creati perché non esiste una revisione precedente a cui accodare. La libreria ignora questa opzione per i nuovi documenti e li scrive in modalità non incrementale.

Quando sono richiesti aggiornamenti incrementali

Quando aggiungi una nuova firma digitale a un documento che contiene già firme, devi salvare il file in modo incrementale. Lo stesso vale quando aggiorni un file precedentemente firmato con nuove annotazioni o nuovi dati modulo. Riscrivere l'intero file in questi casi invaliderebbe le firme esistenti.

Allo stesso tempo, è preferibile eseguire un salvataggio non incrementale (completo) prima di applicare la prima firma digitale, in modo che la baseline firmata sia un file pulito e riscritto integralmente. Firmare un documento che contiene problemi strutturali nelle revisioni precedenti può portare a problemi imprevisti di convalida della firma.

Gli accodamenti incrementali sono richiesti anche nei flussi di lavoro che devono preservare una cronologia delle revisioni verificabile o imporre l'archiviazione documentale solo in append.

Vantaggi dell'uso degli aggiornamenti incrementali

Gli aggiornamenti incrementali consentono più firme sullo stesso file e permettono un insieme limitato di modifiche successive alla firma, come la compilazione dei campi modulo, senza invalidare le firme esistenti.

Questo approccio offre inoltre salvataggi più rapidi per piccole modifiche perché viene scritto solo il dato modificato. Preserva anche la cronologia delle revisioni del documento, che è essenziale per l'audit e altri flussi di lavoro guidati dalla conformità.

Problemi e insidie da evitare

Gli aggiornamenti incrementali non possono applicare una compressione globale o rimuovere oggetti obsoleti su tutto il file perché accodano solo gli oggetti modificati. Di conseguenza, in genere producono file più grandi e meno ottimizzati rispetto a una riscrittura completa.

La dimensione del file cresce a ogni revisione, anche quando non sono presenti oggetti inutilizzati, perché tutte le revisioni precedenti restano incorporate nel file e continuano a occupare spazio.

Le informazioni sensibili o errate delle revisioni precedenti restano recuperabili e i problemi del formato PDF o i difetti strutturali nelle revisioni precedenti non vengono corretti accodando nuovi dati.

Infine, alcuni visualizzatori e strumenti di elaborazione fanno fatica con PDF multi-revisione. Prima di fare affidamento sugli aggiornamenti incrementali, assicurati che tutti i consumer dei tuoi documenti possano gestire file con più revisioni.

Test dell'output PDF

Il test automatizzato dei PDF protegge le release dalle regressioni di contenuto e layout confrontando i PDF generati con PDF baseline archiviati nel repository o nello storage degli artefatti. Le baseline ti aiutano a rilevare modifiche accidentali in testo, font, immagini o layout e riducono la necessità di QA manuale in ogni build.

Per i risultati più affidabili, combina controlli strutturali, estrazione del testo e confronti visivi.

Confronto rapido degli approcci

Confronto della struttura del documento

Usa PdfDocument.DocumentsAreEqual per confrontare i grafi degli oggetti PDF, la versione PDF e il document security store (DSS) ignorando le proprietà del documento dipendenti dal tempo. Il metodo ignora anche i metadati del documento, gli ID del trailer e altre proprietà generate automaticamente.

Questo metodo è ideale per i flussi di test dei documenti PDF che devono garantire che non siano stati aggiunti o rimossi oggetti imprevisti. DocumentsAreEqual supporta overload per file e stream e può confrontare PDF crittografati.

Un esempio completo che dimostra questa tecnica è disponibile negli esempi di Docotic.Pdf. Oltre a mostrare come usare il metodo nelle normali applicazioni .NET, l'esempio mostra anche come usare DocumentsAreEqual in Native AOT applications.

Verifica dei PDF tramite testo estratto

Estrai il testo dall'intero documento in una volta sola oppure dalle singole pagine una dopo l'altra e confronta le stringhe. Puoi usare le opzioni di estrazione del testo per affinare il processo, ad esempio escludendo il rettangolo del piè di pagina. Per facilitare il confronto, puoi suddividere il testo estratto in righe o parole.

Per controlli strutturati, estrai prima il testo con posizione, font e altre informazioni dettagliate su ogni frammento, parola o carattere. Poi confronta ogni elemento estratto con il corrispondente elemento baseline.

Rilevamento delle differenze visive

Inizia renderizzando le pagine PDF in immagini e confronta ogni immagine con quella baseline. Usa librerie specializzate come ImageSharp.Compare o Magick.NET per rilevare differenze nelle immagini.

Preferisci un confronto rigoroso pixel per pixel, in modo che ogni pixel corrispondente in entrambe le immagini debba coincidere. Se i tuoi requisiti consentono piccole variazioni di rendering, puoi adattare la logica di confronto per tollerare differenze minori, ma l'uguaglianza esatta dei pixel offre i risultati più affidabili.

Valuta l'uso dell'hashing come controllo preliminare rapido per determinare se due immagini sono probabilmente identiche senza eseguire un confronto completo pixel per pixel. Calcola un hash SHA-256 per ogni immagine renderizzata e, se gli hash coincidono, le immagini sono quasi certamente uguali. Se gli hash differiscono, esegui quindi il confronto completo pixel per pixel.

Conclusione

Docotic.Pdf offre un toolkit completo e multilivello per creare e manipolare PDF in .NET. Gli sviluppatori possono scegliere tra il controllo di basso livello con Core API, la generazione di documenti di alto livello con Layout API o la conversione HTML-to-PDF per flussi di lavoro già basati su tecnologie web.

La libreria supporta anche PDF basati su immagini, generazione guidata da modelli e un ricco insieme di funzionalità interattive come annotazioni, link, segnalibri, azioni JavaScript e azioni di apertura.

Per garantire l'affidabilità, Docotic.Pdf include metodi per testare l'output PDF in modo che le modifiche nella tua applicazione non introducano regressioni o differenze impreviste.