Creazione di PDF con l'API Core

Tradotto da Bit Miracle. Articolo originale di Sergey Bobrovsky

Aggiornato il 5 maggio 2026

L'API principale di Docotic.Pdf offre il controllo completo sulla creazione di PDF. Consente di disegnare testo, immagini e grafica vettoriale su aree di disegno fornite da pagine PDF, XObject e motivi di tassellatura.

Hai il controllo su ogni coordinata e ogni operazione di disegno, il che ti garantisce il massimo controllo sul layout delle tue pagine PDF. Per documenti con molti elementi grafici o layout personalizzati, dove la precisione è fondamentale, questo livello di controllo è indispensabile.

Con l'API principale, puoi anche aggiungere annotazioni, campi modulo, livelli, segnalibri e altro ancora ai PDF creati. L'API è il metodo più flessibile e potente per creare PDF in .NET offerto da Docotic.Pdf.

Consulta l'articolo che illustra ogni metodo per creare PDF se desideri una panoramica più ampia di tutti gli approcci disponibili in Docotic.Pdf, inclusi quelli che vanno oltre l'API Core.

Prima di iniziare

Prima di iniziare a lavorare con l'API Core, configura il tuo ambiente installando Docotic.Pdf e richiedendo una chiave di licenza.

Installa Docotic.Pdf

Per creare documenti PDF in C# o VB.NET, inizia installando la libreria da NuGet.

Install-Package BitMiracle.Docotic.Pdf

Se preferisci installare la libreria manualmente, scarica l'archivio ZIP contenente i file binari della libreria, decomprimilo e aggiungi un riferimento al file BitMiracle.Docotic.Pdf.dll dal tuo progetto.

Ottieni una chiave di licenza

Per utilizzare la libreria è necessaria una chiave di licenza. Per provare la libreria, richiedi una chiave di licenza gratuita a tempo limitato compilando il modulo nella pagina di download di Docotic.Pdf.

Esempi di base per la creazione di PDF

Questa sezione fornisce esempi di base che mostrano come creare documenti PDF con l'API Core, prima in C# e poi in VB.NET.

Come creare un PDF in C#

Ora che hai installato Docotic.Pdf e ottenuto una chiave di licenza, creare un PDF con l'API Core è semplicissimo.

BitMiracle.Docotic.LicenseManager.AddLicenseData("PUT-LICENSE-HERE");

using var pdf = new PdfDocument();
pdf.Save("empty.pdf");

Il codice mostra come creare un file PDF vuoto. La prima riga aggiunge una chiave di licenza. Senza una licenza, verrà generata un'eccezione sulla riga che crea un'istanza di PdfDocument. L'ultima riga salva il documento in un file PDF.

La struttura interna del file creato dipende dalle opzioni di salvataggio. In questo esempio, il codice utilizza l'overload del metodo Save che salva con le opzioni predefinite. Per comprendere il funzionamento di queste opzioni predefinite e quando potrebbe essere opportuno modificarle, consultare la sezione relativa alle opzioni di salvataggio.

Per rispettare la tradizione di programmazione, il secondo esempio mostra un messaggio "Hello, world!" creato con l'API Core.

using var pdf = new PdfDocument();

var page = pdf.Pages[0];
page.Canvas.DrawString(50, 50, "Hello, world!");

pdf.Save("hello.pdf");

Il codice inserisce la frase classica sulla tela della prima pagina del documento, a partire dalla posizione specificata. La riga utilizza il carattere e la dimensione del carattere predefiniti. Continua a leggere per ulteriori informazioni sull'utilizzo della tela PDF.

Utilizzo di VB.NET per creare PDF

Il codice VB.NET per creare un PDF è molto simile al codice della sezione precedente.

Using pdf As New PdfDocument()
    Dim page = pdf.Pages(0)
    page.Canvas.DrawString(50, 50, "Hello, world!")

    pdf.Save("hello.pdf")
End Using

La sezione precedente, che include un esempio in C#, spiega cosa fa il codice e come funziona.

Lavorare con l'area di lavoro PDF

Per modificare un'area di disegno in un documento PDF, si utilizza l'API Canvas. Si tratta di un sottoinsieme dell'API Core.

L'API Canvas utilizza un modello di posizionamento assoluto. Si scelgono le coordinate e l'area di disegno viene disegnata esattamente dove specificato. Il sistema di coordinate posiziona l'origine nell'angolo in alto a sinistra della pagina. Le coordinate aumentano verso destra lungo l'asse X e verso il basso lungo l'asse Y.

(0,0) ──► X
  │
  │
  ▼
  Y

Disegno del testo

Nella classe PdfCanvas, Docotic.Pdf fornisce due metodi principali per il rendering del testo: DrawString e DrawText. Entrambi i metodi utilizzano il font corrente del canvas, quindi si consiglia di impostare il font desiderato prima di disegnare qualsiasi testo.

Utilizzo di DrawString

Il metodo DrawString disegna sempre una singola riga di testo. Inizia a disegnare dalla posizione corrente del testo sul canvas, a meno che non si utilizzi un overload con coordinate esplicite. Alcuni overload consentono di specificare opzioni aggiuntive che controllano il modo in cui viene disegnata la riga di testo.

Avete già visto un semplice esempio di DrawString nello snippet "Hello, world!". Ecco un altro esempio che utilizza le opzioni di disegno delle stringhe per sottolineare il testo.

using var pdf = new PdfDocument();

var canvas = pdf.Pages[0].Canvas;
canvas.DrawString(50, 50, "This text is underlined", new PdfStringDrawingOptions
{
    Underline = true,
});

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

Utilizzo di DrawText

Il metodo DrawText consente di disegnare più righe di testo all'interno di un rettangolo specificato. Il metodo gestisce le interruzioni di riga e ritaglia il testo che non rientra nello spazio consentito. Le opzioni di disegno del testo definiscono l'allineamento orizzontale e verticale del testo e altri aspetti relativi al suo posizionamento e al suo rendering.

Ecco come disegnare testo in un PDF utilizzando C#:

using var pdf = new PdfDocument();

const string LongString = "Lorem ipsum dolor sit amet, consectetur adipisicing elit";
var multiLineOptions = new PdfTextDrawingOptions(new PdfRectangle(70, 70, 40, 150))
{
    HorizontalAlignment = PdfTextAlign.Left,
    VerticalAlignment = PdfVerticalAlign.Top
};

var canvas = pdf.Pages[0].Canvas;
canvas.DrawText(LongString, multiLineOptions);

pdf.Save("drawtext.pdf");

Per perfezionare l'aspetto del testo, è possibile regolare le seguenti proprietà dell'area di lavoro:

• spaziatura tra i caratteri
• spaziatura tra le parole
• ridimensionamento del testo
• alzata del testo (spostamento della linea di base)
• modalità di rendering (riempimento, contorno, riempimento e contorno e altre)

Per esempi pratici di metodi e proprietà relativi al testo, consultare il gruppo di esempi di testo.

Aggiungere e utilizzare i caratteri

A meno che non siate soddisfatti del carattere predefinito Helvetica, è consigliabile aggiungere i caratteri necessari al PDF per garantire che il testo venga visualizzato esattamente come previsto.

Docotic.Pdf può aggiungere caratteri Type1, TrueType, Compact Font Format (CFF) e OpenType da:

• la raccolta di caratteri installati nel sistema
• file e flussi esterni

Inoltre, è possibile utilizzare i 14 caratteri Type1 integrati, disponibili in qualsiasi visualizzatore PDF.

Per utilizzare un carattere nel PDF, create un oggetto PdfFont utilizzando il metodo CreateFont o CreateFontFromFile dell'oggetto PdfDocument corrispondente. Quindi assegnate il carattere all'area di disegno prima di disegnare il testo. È inoltre consigliabile impostare la dimensione del carattere.

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

var font = pdf.CreateFont("NSimSun");
canvas.Font = font;
canvas.FontSize = 14;
canvas.DrawString(10, 50, "Olá. 你好. Hello, Unicode!");

font.RemoveUnusedGlyphs();

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

Il font deve contenere i glifi per tutti i caratteri del testo che si sta tentando di disegnare. In caso contrario, verrà generata un'eccezione CannotShowTextException. Utilizzare PdfFont.ContainsGlyphsForText per verificare che il font contenga tutti i glifi richiesti.

Il supporto Unicode dipende dal tipo di font. I font di tipo 1 supportano solo il set di caratteri e la codifica latina, con una sola eccezione. I font integrati Symbol e ZapfDingbats forniscono simboli matematici, greci e decorativi.

I font TrueType, CFF e OpenType in genere supportano Unicode, ma potrebbero non includere i glifi per tutti i caratteri Unicode.

Docotic.Pdf cerca di incorporare il minor numero possibile di byte dei font per mantenere ridotto il file PDF di output. Tuttavia, quando un documento utilizza font con molti glifi, il file risultante potrebbe comunque essere relativamente grande. Utilizzare PdfFont.RemoveUnusedGlyphs per ridurre al minimo il numero di byte aggiunti dai font incorporati.

Calcolo delle dimensioni del testo

Poiché l'API Canvas utilizza il posizionamento assoluto, è spesso necessario sapere quanto spazio occuperà un testo prima di disegnarlo. Questo è particolarmente importante quando si genera testo in più parti, ad esempio per suddividere stringhe lunghe, allineare il testo con precisione o evitare sovrapposizioni con altri contenuti. La classe PdfCanvas fornisce diversi metodi che consentono di misurare il testo utilizzando il font e la dimensione del font attualmente selezionati.

Utilizzare PdfCanvas.MeasureText per ottenere sia la larghezza che l'altezza di una stringa così come apparirebbe sul canvas. Casi d'uso tipici includono:

• determinare se il testo si adatta a una determinata area
• calcolare manualmente le interruzioni di riga
• posizionare blocchi di testo l'uno rispetto all'altro

Per i casi in cui si centra o si allinea a destra il testo e si necessita solo dell'estensione orizzontale, utilizzare PdfCanvas.GetTextWidth. Per conoscere l'altezza di una riga di testo per il font corrente, utilizzare PdfCanvas.GetTextHeight.

Immagini di disegno

Per disegnare un'immagine su una tela PDF, crea prima un oggetto PdfImage e poi disegnalo utilizzando il metodo PdfCanvas.DrawImage.

Ecco come aggiungere un'immagine a un PDF in C#:

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

var image = pdf.CreateImage("image.png");
canvas.DrawImage(image, 10, 50);

pdf.Save("image.pdf");

Il codice crea un oggetto immagine utilizzando il metodo CreateImage dell'oggetto PdfDocument corrispondente e disegna l'immagine sulla tela della prima pagina.

Per maggiori dettagli sui formati di immagine supportati e sulle tecniche più avanzate di conversione da immagine a PDF, consulta la sezione Creazione di PDF da immagini.

Utilizzo della grafica vettoriale

Docotic.Pdf consente di disegnare linee rette, curve di Bézier e forme geometriche comuni direttamente su un'area di disegno PDF utilizzando i metodi della classe PdfCanvas. Utilizza i metodi che iniziano con Draw (ad esempio, DrawLineTo, DrawCircle, DrawRectangle) per posizionare segni visibili sull'area di disegno.

Linee e curve vengono disegnate utilizzando la penna corrente, definita tramite PdfCanvas.Pen, che specifica il colore del tratto, lo spessore e altre proprietà di disegno. A seconda della modalità di disegno, le forme possono essere tracciate, riempite o tracciate e poi riempite. Il pennello corrente, accessibile tramite PdfCanvas.Brush, viene utilizzato per riempire l'interno delle forme.

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

canvas.DrawCircle(new PdfPoint(60, 100), 40);
canvas.DrawRectangle(
    new PdfRectangle(300, 60, 110, 70),
    PdfDrawMode.Fill);

canvas.CurrentPosition = new PdfPoint(150, 90);
canvas.DrawCurveTo(new PdfPoint(180, 60), new PdfPoint(230, 120), new PdfPoint(250, 90));

pdf.Save("curve-and-shapes.pdf");

Ogni area di disegno PDF mantiene uno stato grafico, che include la penna, il pennello, il font e le posizioni correnti. Utilizzare SaveState per salvare lo stato corrente e RestoreState per ripristinare uno stato precedente. Oltre ad annullare trasformazioni temporanee e modifiche simili, il ripristino dello stato è l'unico modo per rimuovere il ritaglio una volta applicato.

I tracciati grafici consentono di creare forme complesse a partire da linee, curve e forme più semplici senza disegnarle immediatamente. Utilizzare i metodi Append, come AppendLineTo o AppendRectangle, per aggiungere segmenti al tracciato corrente. I tracciati non producono output visibile finché non vengono esplicitamente riempiti o contornati.

È possibile utilizzare qualsiasi tracciato grafico creato come area di ritaglio per limitare le successive operazioni di disegno. Il ritaglio rimane attivo finché lo stato grafico non viene ripristinato.

Esempi pratici ed eseguibili di utilizzo della grafica vettoriale sono disponibili nella sezione Grafica del repository di esempio.

Impostazione dei colori e della trasparenza

È possibile modificare i colori del tratto e del riempimento tramite la penna e il pennello di un'area di lavoro PDF. A tale scopo, utilizzare i metodi PdfPen.Color e PdfBrush.Color.

Gli spazi colore supportati, dipendenti dal dispositivo, includono Grigio, RGB e CMYK, rappresentati da PdfGrayColor, PdfRgbColor e PdfCmykColor.

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

canvas.Pen.Color = new PdfRgbColor(30, 60, 160);
canvas.Pen.Width = 3;

canvas.Brush.Color = new PdfCmykColor(0, 20, 5, 0);

canvas.DrawRectangle(
    new PdfRectangle(50, 50, 100, 40),
    PdfDrawMode.FillAndStroke);

pdf.Save("fill-and-stroke-colors.pdf");

Docotic.Pdf supporta spazi colore basati su CIE e indipendenti dal dispositivo, inclusi i colori L*a*b* e i colori calibrati basati su ICC. L'API Core supporta anche i colori spot e gli spazi colore di separazione per i flussi di lavoro che richiedono inchiostri personalizzati o output specifici per canale.

Il codice di esempio riportato di seguito mostra come creare colori Lab, colori basati su profili e colori spot. Per eseguire l'esempio, è necessario prima scaricare il profilo ICC utilizzato.

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

var labColorSpace = new PdfLabColorSpace(pdf, [0.5, 1, 0.5]);
canvas.Pen.Color = new PdfLabColor(labColorSpace, 50, -50, 50);
canvas.Pen.Width = 3;

var rgbProfile = pdf.CreateColorProfile("AdobeCompat-v2.icc");
canvas.Brush.Color = new PdfRgbColor(rgbProfile, 210, 105, 30);

canvas.DrawRectangle(
    new PdfRectangle(50, 50, 100, 40),
    PdfDrawMode.FillAndStroke);

var tintTransform = new PdfExponentialFunction(
    pdf, 1, [0d, 0, 0, 0], [0, 0.8, 0.73, 0.25], [0d, 1]);
var separationColorSpace = new PdfSeparationColorSpace(
    pdf, "BLOODRED", new PdfCmykColorSpace(), tintTransform);
canvas.Pen.Color = new PdfSpotColor(1.0, separationColorSpace);

canvas.DrawCircle(new PdfPoint(100, 70), 60);

pdf.Save("using-special-colors.pdf");

È possibile anche tracciare e riempire forme utilizzando motivi a mosaico. Un motivo è definito da una cella del motivo disegnata su una tela dedicata. Ne esistono due tipi:

• Motivi colorati. Le loro celle definiscono i colori.
• Motivi non colorati. Le loro celle vengono colorate dal colore della penna/pennello al momento dell'utilizzo.

Per utilizzare un motivo, crearne uno utilizzando CreateColoredPattern o CreateUncoloredPattern dell'oggetto PdfDocument corrispondente. Quindi applicare il motivo tramite PdfPen.Pattern e/o PdfBrush.Pattern. Consultare il codice di esempio per la creazione e l'utilizzo di motivi nel repository di esempio.

I colori semitrasparenti consentono di disegnare forme, testo e immagini con opacità variabile. Utilizzare PdfPen.Opacity e PdfBrush.Opacity per produrre colori traslucidi.

Inoltre, le modalità di fusione controllano il modo in cui il contenuto trasparente interagisce con ciò che si trova al di sotto. Per modificare la modalità di fusione di un canvas, utilizzare PdfCanvas.BlendMode.

Aggiunta e personalizzazione delle pagine

Docotic.Pdf espone la collezione PdfDocument.Pages, che puoi utilizzare per gestire tutte le pagine di un documento. Nella classe PdfDocument sono presenti due metodi principali che consentono di aggiungere nuove pagine: AddPage e InsertPage.

Utilizza AddPage() per aggiungere una nuova pagina alla fine del documento. Per inserire una pagina in qualsiasi posizione, utilizza InsertPage(index). Entrambi i metodi restituiscono la nuova istanza di PdfPage.

Ogni nuova pagina ha le dimensioni predefinite di 595 x 842 unità di spazio utente. Corrisponde alle dimensioni di un foglio A4. Nella maggior parte dei casi, l'unità di spazio utente in PDF è pari a 1/72 di pollice. In altre parole, un'unità di spazio utente equivale a un pixel quando la risoluzione della pagina è di 72 pixel per pollice.

È possibile modificare le dimensioni di una pagina in qualsiasi momento impostando la larghezza e/o l'altezza a un numero specifico di unità di spazio utente.

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

page.Width = 600;
page.Height = 800;

Un'altra opzione è quella di utilizzare una delle dimensioni predefinite:

page.Size = PdfPaperSize.Ledger;

È inoltre possibile cambiare l'orientamento della pagina da verticale a orizzontale e ruotarla di 90°, 180° o 270° in senso orario.

page.Orientation = PdfPaperOrientation.Landscape;
page.Rotation = PdfRotation.Rotate180;

Oltre a impostare la larghezza, l'altezza o una dimensione predefinita della pagina, è anche possibile regolare le dimensioni della pagina insieme al ritaglio o al ridimensionamento del contenuto esistente.

Riutilizzo dei contenuti con XObjects

Un XObject PDF è un contenitore che racchiude grafica vettoriale, immagini e testo. Ogni XObject ha la propria area di lavoro, consentendo di creare XObject complessi quanto le normali pagine PDF.

Gli XObject sono simili alle immagini vettoriali. È possibile riutilizzare lo stesso oggetto su più pagine senza ricrearne il contenuto o aumentare le dimensioni del documento. È inoltre possibile ridimensionare e ruotare tali oggetti senza introdurre artefatti visivi. Grazie a queste caratteristiche, gli XObject sono ideali per elementi ripetuti come loghi, illustrazioni, sfondi, filigrane e altri elementi grafici ricorrenti.

Creazione e utilizzo di XObjects

Per creare un XObject, utilizzare il metodo PdfDocument.CreateXObject. Modificare la larghezza e l'altezza dell'oggetto, se necessario. Quindi riempire l'area di disegno con testo, immagini e grafica nello stesso modo di un normale canvas di pagina.

Utilizzare il metodo PdfCanvas.DrawXObject nel codice C# o VB.NET per aggiungere l'XObject ad altri canvas. Si noti che è possibile disegnare XObject su canvas forniti sia da pagine che da altri XObject.

Ecco un esempio di codice C# che crea un XObject con un'illustrazione e la disegna su due pagine.

using var pdf = new PdfDocument();

var xobj = pdf.CreateXObject();

var options = new PdfTextDrawingOptions(new PdfRectangle(0, 0, 100, 50))
{
    HorizontalAlignment = PdfTextAlign.Center,
    VerticalAlignment = PdfVerticalAlign.Center,
};
xobj.Canvas.FontSize = 16;
xobj.Canvas.DrawText("Company Logo", options);
xobj.Canvas.DrawRectangle(options.Bounds);

var page1 = pdf.Pages[0];
page1.Canvas.DrawXObject(xobj, 100, 100);

var page2 = pdf.AddPage();
page2.Canvas.DrawXObject(xobj, 200, 200);

pdf.Save("using-xobjects.pdf");

Trasformare le pagine con XObjects

Gli XObject consentono anche scenari che vanno oltre il semplice riutilizzo di elementi grafici. Un esempio comune è la combinazione di due pagine PDF esistenti in un'unica pagina più grande. Trasformando ciascuna pagina sorgente in un XObject, è possibile disegnarle una accanto all'altra su una nuova area di lavoro, creando di fatto una pagina doppia unita. Questo approccio offre il pieno controllo su posizionamento, spaziatura e ridimensionamento, semplificando la creazione di layout comparativi, doppie pagine di libri o anteprime multipagina.

La stessa tecnica può essere applicata quando è necessario ridimensionare le pagine PDF. Invece di ridisegnare o ricostruire il contenuto, è possibile creare un XObject dalla pagina originale e disegnarlo ridimensionandolo alla nuova dimensione. Ciò consente di ridurre le dimensioni di pagine troppo grandi, ingrandire quelle piccole o normalizzare un documento con dimensioni miste con il minimo sforzo.

Ambito e limitazioni dell'API Core

L'API Core offre un controllo preciso e di basso livello sulla creazione di PDF, ma non fornisce alcuna funzionalità di impaginazione automatica. Non sono presenti margini, intestazioni, piè di pagina o logica di interruzione di pagina integrati e tutto il contenuto deve essere posizionato manualmente. La misurazione del testo e la suddivisione tra le pagine sono responsabilità interamente affidate al codice, rendendo questo l'approccio più manuale alla creazione di PDF.

L'impaginazione automatica, incluso il supporto per tabelle, paragrafi e interruzioni di pagina, è disponibile tramite l'API Layout di livello superiore.

Conclusione

L'API principale di Docotic.Pdf offre il controllo completo sulla creazione di PDF. Consente di disegnare testo, immagini e grafica vettoriale su aree di lavoro fornite da pagine PDF, XObject e motivi di tassellatura.

L'API è progettata per scenari che richiedono un controllo preciso e di basso livello: è possibile posizionare esplicitamente ogni elemento, gestire autonomamente le dimensioni del testo e la suddivisione delle pagine, e manipolare direttamente lo stato, i colori e la trasparenza della grafica.

Nel complesso, l'API principale è lo strumento più flessibile per la creazione di PDF quando precisione e controllo sono prioritari.