HTML to PDF per .NET

Tradotto da Bit Miracle. Articolo originale di Sergey Bobrovsky

Aggiornato il 2 luglio 2026

Puoi convertire HTML in PDF usando la libreria Docotic.Pdf. Il componente aggiuntivo gratuito HtmlToPdf per la libreria rende possibile convertire HTML, SVG, WEBP e altri formati web in PDF.

Questa guida illustra le funzionalità da HTML a PDF fornite dal componente aggiuntivo e include collegamenti a pagine che forniscono ulteriori dettagli sugli argomenti trattati.

Le basi di HTML to PDF in C#

Avrai bisogno del componente aggiuntivo HtmlToPdf, di uno snippet di conversione e di una chiave di licenza. Puoi iniziare con una chiave di prova gratuita.

Installa l'add-on da NuGet

Install-Package BitMiracle.Docotic.Pdf.HtmlToPdf

Questo è il modo consigliato perché gestisce automaticamente dipendenze e aggiornamenti. Puoi anche installare manualmente il componente aggiuntivo dallo zip con i binari di Docotic.Pdf, anche se è più complicato e soggetto a errori.

Ottieni una chiave di licenza

Per provare la libreria, ottieni una chiave di licenza gratuita a tempo limitato dalla pagina di download di Docotic.Pdf. Se hai già acquistato una licenza, usa il codice che ti è stato fornito dopo l'acquisto.

Tutte le licenze Docotic.Pdf includono le funzionalità da HTML a PDF. Non è necessario acquistare una licenza aggiuntiva per usare il componente aggiuntivo.

Aggiungi il codice di conversione

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

using var converter = await HtmlConverter.CreateAsync();
var html = "<h1>Hello, World<h1>";
using var pdf = await converter.CreatePdfFromStringAsync(html);
pdf.Save("output.pdf");

Nel codice, sostituisci il valore segnaposto nella chiamata al metodo AddLicenseData con una chiave di licenza valida.

Esegui il codice

Il codice di conversione creerà un PDF dal codice HTML nella stringa. Con le opzioni di conversione predefinite, l'output conterrà una pagina in formato A4.

La libreria offre molte opzioni per personalizzare la conversione. Puoi modificare le dimensioni dell'output o aggiungere intestazioni e piè di pagina alle pagine generate. È anche possibile convertire risorse che richiedono autenticazione.

Leggi i diversi modi per convertire HTML in PDF nell'articolo dedicato, che spiega in grande dettaglio ciascun approccio.

Perché Docotic.Pdf è il convertitore HTML to PDF giusto?

La capacità di preservare stili e layout durante la conversione rende Docotic.Pdf la scelta giusta per produrre PDF da report HTML, fatture e altri documenti. La libreria produce documenti PDF perfetti al pixel da HTML e da altri formati web come SVG. Riutilizzare contenuti HTML esistenti è facile con la libreria.

Il convertitore usa il motore di rendering di Google Chrome. Questo significa lo stesso livello di conformità agli standard web di uno dei migliori browser web.

Puoi usare Docotic.Pdf per produrre PDF da layout molto complessi con CSS moderno, JavaScript e immagini. Anche il responsive web design è supportato molto bene.

Panoramica dell'architettura dell'API

L'API da HTML a PDF è disponibile solo quando si usa Docotic.Pdf insieme al componente aggiuntivo HtmlToPdf gratuito.

Il componente aggiuntivo espone solo un'API asincrona. L'abbiamo progettato per funzionare con gestori di eventi async e metodi async. Questo design consente di gestire in modo fluido attività di lunga durata, e la conversione multimediale è un esempio ideale di tale attività.

Versioni .NET e supporto della piattaforma

La libreria e il componente aggiuntivo hanno come target .NET Standard 2.0. Questo significa che entrambi sono compatibili con .NET 5 fino a .NET 10. Inoltre, sono supportati anche .NET Core 2.0+ e .NET Framework 4.6.1+.

Puoi usare le funzionalità da HTML a PDF in applicazioni Windows Forms, WPF, ASP.NET e console. Il componente aggiuntivo può essere eseguito in ambienti cloud e in container Docker.

Con l'aiuto del componente aggiuntivo, puoi generare PDF da HTML in ambienti Windows, macOS e Linux.

Cosa accade durante una conversione?

Per impostazione predefinita, una conversione consiste in queste fasi:

1. Il tuo codice chiama il metodo CreateAsync della classe HtmlConverter.
2. Il componente aggiuntivo verifica se esiste una versione idonea di Google Chrome nella cartella .local-chromium all'interno della directory di lavoro corrente.
3. Se non esiste una versione idonea, il componente aggiuntivo ne scarica una e la decomprime nella cartella .local-chromium.
4. Quando il tuo codice chiama il metodo CreatePdfAsync o CreatePdfFromStringAsync, il componente aggiuntivo usa Google Chrome per caricare l'HTML fornito.
5. Quando il contenuto è pronto per la conversione, il componente aggiuntivo indica al browser di produrre un PDF.
6. Google Chrome genera il PDF usando le funzionalità di rendering di Chromium.
7. Il componente aggiuntivo restituisce al tuo codice un PdfDocument contenente il PDF prodotto.

Piattaforme cloud e immagini Docker

Il componente aggiuntivo HtmlToPdf supporta le piattaforme cloud Azure e AWS, inclusi gli ambienti serverless. Puoi anche usare l'API da HTML a PDF in container Docker. Ecco l'elenco degli ambienti supportati:

• Azure: Azure Functions, Azure App Service, Azure VPS
• Amazon Web Services: AWS ECS, Amazon EC2
• Docker: container Windows e Linux.

La libreria e il componente aggiuntivo supportano completamente i cambiamenti dinamici dell'hardware, l'autoscaling e altre funzionalità runtime cloud-native.

Per maggiori informazioni, consulta l'articolo sull'esecuzione del componente aggiuntivo nei cloud e nelle immagini Docker.

Nella maggior parte degli scenari cloud è richiesta una licenza senza vincoli. La FAQ sulla licenza spiega come scegliere la licenza appropriata per le app cloud.

Come generare un PDF da un modello HTML

Segui questi semplici passaggi:

1. Recupera i dati per il modello.
2. Riempi il modello con i dati per produrre un HTML completo.
3. Usa Docotic.Pdf per convertire l'HTML completo in PDF.

I dati del modello in genere provengono da un database o da una risposta API. Con un database, possono essere un singolo record o un insieme di record. Per un'API, spesso si tratta di un oggetto JSON che descrive una o più entità.

Per gli esempi seguenti, userò questa persona fittizia:

var person = new
{
    Name = "Alice Johnson",
    Age = 27,
    Email = "alicej@example.com",
    Occupation = "Truck driver"
};

Ora che ho i dati, presenterò tre opzioni per preparare e compilare un modello HTML. In tutti e tre i casi, l'HTML completo risultante sarà lo stesso, anche se i modelli corrispondenti sono diversi.

Per convertire l'HTML completo, usa il codice che ho già fornito.

Segnaposto con nome

I segnaposto con nome sono token racchiusi in delimitatori doppi che usano simboli non alfanumerici. Uno dei delimitatori più resistenti alle collisioni è %%.

Ecco un modello con segnaposto con nome, insieme al codice che produce l'HTML completo a partire da esso:

var template = @"<head><title>%%NAME%%'s Profile</title></head>
<body>
    <h1>%%NAME%%</h1>
    <p><strong>Age:</strong> %%AGE%%</p>
    <p><strong>Email:</strong> %%EMAIL%%</p>
    <p><strong>Occupation:</strong> %%OCCUPATION%%</p>
</body></html>";

var completeHtml = template
    .Replace("%%NAME%%", person.Name)
    .Replace("%%AGE%%", person.Age.ToString())
    .Replace("%%EMAIL%%", person.Email)
    .Replace("%%OCCUPATION%%", person.Occupation);

L'uso di segnaposto con nome è l'approccio consigliato nella maggior parte dei casi. Tuttavia, ricordati di eseguire l'escape di tutti i valori che inserisci al posto dei segnaposto.

Motori di template

Quando il tuo modello è molto complesso e/o richiede parti riutilizzabili, i segnaposto con nome potrebbero non essere molto pratici. Prova invece un motore di template come Handlebars.Net.

Ecco un esempio che usa un modello e un codice diversi ma produce lo stesso HTML:

var template = @"<head><title>{{name}}'s Profile</title></head>
<body>
    <h1>{{name}}</h1>
    <p><strong>Age:</strong> {{age}}</p>
    <p><strong>Email:</strong> {{email}}</p>
    <p><strong>Occupation:</strong> {{occupation}}</p>
</body></html>";

var compiledTemplate = Handlebars.Compile(template);
var completeHtml = compiledTemplate(person);

I template di Handlebars.Net sono senza logica. Se questo ti sembra troppo restrittivo, prova Scriban. Offre condizioni, cicli, espressioni, chiamate di funzioni e altro ancora.

Segnaposto posizionali

Sono molto simili ai segnaposto con nome, ma usano numeri di posizione invece dei nomi. Li hai già visti nelle chiamate al metodo string.Format.

var template = @"<head><title>{0}'s Profile</title></head>
<body>
    <h1>{1}</h1>
    <p><strong>Age:</strong> {2}</p>
    <p><strong>Email:</strong> {3}</p>
    <p><strong>Occupation:</strong> {4}</p>
</body></html>";

var completeHtml = string.Format(
    template, person.Name, person.Name,
    person.Age, person.Email, person.Occupation);

Ti suggerisco di non usare i segnaposto posizionali se non nei casi più semplici. Ecco un paio di motivi:

• Quando il modello usa un valore più di una volta, devi fornire quel valore più volte nella chiamata.
• È troppo facile cambiare l'ordine nel modello ma dimenticare di aggiornare il codice.

Converti ASPX in PDF

Usa Docotic.Pdf insieme al componente aggiuntivo gratuito HtmlToPdf per convertire ASPX in PDF. Il processo è semplice:

• Fornisci un'implementazione del metodo Render che accumula l'HTML prodotto.
• Lascia che il motore ASP.NET generi l'HTML della pagina ASPX eseguendo codice lato server e controlli.
• Converti l'HTML accumulato in PDF e restituisci il PDF nella risposta aggiornata.

Consulta il codice di esempio per vedere come generare un PDF da una pagina ASPX in un'applicazione ASP.NET Web Forms. L'applicazione di esempio dimostra il processo sopra creando una fattura in formato HTML o PDF. Puoi usare lo stesso approccio per produrre versioni PDF ad alta fedeltà dei tuoi report, estratti e altri documenti.

Converti SVG in PDF

Le conversioni da SVG a PDF vettoriale sono possibili con il componente aggiuntivo HtmlToPdf per la libreria Docotic.Pdf. Puoi usare la classe HtmlConverter come convertitore da SVG a PDF. Il seguente codice C# mostra un modo per eseguire la conversione:

using var converter = await HtmlConverter.CreateAsync();
var uri = new Uri("https://bitmiracle.com/images/team.svg");
using var pdf = await converter.CreatePdfAsync(uri);
pdf.Save("output.pdf");

Il risultato del codice sopra è un PDF vettoriale di alta qualità. Il convertitore fornito dal componente aggiuntivo HtmlToPdf usa la larghezza e l'altezza specificate in SVG per determinare il rapporto d'aspetto. A seconda delle dimensioni dell'SVG, il convertitore può ridimensionarlo proporzionalmente per adattarlo alla pagina PDF.

Opzioni che influenzano le dimensioni dell'output

Per produrre un PDF di dimensioni diverse, imposta le dimensioni della pagina e/o i margini. L'SVG convertito potrebbe comunque essere ridimensionato proporzionalmente.

Un'altra opzione è specificare larghezza e/o altezza dell'SVG nel codice HTML e convertire quell'HTML. Nell'output, l'immagine avrà la dimensione specificata. Se la dimensione è maggiore della pagina PDF, alcune parti dell'immagine non saranno visibili.

using var converter = await HtmlConverter.CreateAsync();
var html = $"<img src='https://bitmiracle.com/images/team.svg' width='200' />";
using var pdf = await converter.CreatePdfFromStringAsync(html);
pdf.Save("output.pdf");

File SVG in PDF

Per convertire un file SVG in PDF, crea un Uri di file e passalo al metodo CreatePdfAsync. Un'altra opzione è creare uno snippet HTML con un tag img e usare quello snippet con il metodo CreatePdfFromStringAsync. Se usi percorsi relativi nel codice HTML, fornisci l'URL di base tramite le opzioni di conversione.

Per convertire più file SVG in PDF, crea uno snippet HTML contenente più tag img e usalo con il metodo CreatePdfFromStringAsync. Se tutti i file si trovano nella stessa cartella, consiglio di usare percorsi relativi nel codice HTML e di fornire l'URL di base.

Aggiungi SVG al PDF

Inizia convertendo l'SVG in PDF usando uno dei metodi HtmlConverter.

using var converter = await HtmlConverter.CreateAsync();
var uri = new Uri("https://bitmiracle.com/images/quote.svg");
using var svgPdf = await converter.CreatePdfAsync(uri);

Puoi quindi sovrapporre il contenuto del PDF prodotto sopra un altro documento, oppure unire il documento con un altro PDF.

Per sovrapporre un SVG su PDF, crea un XObject dalla prima pagina del documento convertito e disegna quell'XObject sopra una pagina PDF in un altro documento. In questo modo:

using var pdf = new PdfDocument("some-other.pdf");
var xObj = pdf.CreateXObject(svgPdf.Pages[0]);

pdf.Pages[0].Canvas.DrawXObject(xObj, 0, 0);
pdf.Save("output.pdf");

Per unire un SVG in PDF, combina il documento PDF convertito con un altro PDF usando uno dei metodi di unione disponibili.

Converti WEBP in PDF

WebP è un formato web, quindi puoi convertirlo in PDF usando Docotic.Pdf con il componente aggiuntivo HtmlToPdf. Il seguente codice C# mostra come convertire da WebP a PDF con alta गुणवत्ता:

using var converter = await HtmlConverter.CreateAsync();
var html = $"<img src='https://bitmiracle.com/pdf-library/images/edit/reorder-pages.webp'/>";
using var pdf = await converter.CreatePdfFromStringAsync(html);
pdf.Save("output.pdf");

Il codice sopra non specifica gli attributi width o height per il tag img, ma è una buona idea includerli. Tieni presente che, se la dimensione dell'immagine che specifichi è maggiore della pagina PDF, alcune parti dell'immagine non saranno visibili.

Poiché WebP è un formato raster, non si scala bene verso l'alto. Consiglio di usare immagini alla dimensione e risoluzione massime che prevedi di dover usare.

Per convertire un file WebP in PDF, usa lo stesso codice. Se il tuo HTML usa percorsi relativi, fornisci l'URL di base tramite le opzioni di caricamento. Usa un Uri di file come URL di base quando converti immagini locali.

Converti XML in PDF usando XSLT

Per convertire XML in PDF, trasforma prima l'XML in HTML usando una trasformazione XSLT. Poi converti l'HTML risultante in PDF usando Docotic.Pdf con il componente aggiuntivo HtmlToPdf.

Ecco il codice C# per la conversione da XML a PDF:

var transform = CreateTransform("invoice.xsl");
var html = TransformToHtml("invoice.xml", transform);

using var converter = await HtmlConverter.CreateAsync();
using var pdf = await converter.CreatePdfFromStringAsync(html);
pdf.Save("invoice.pdf");

Il codice:

• Crea un oggetto di trasformazione XSLT nella prima riga.
• Trasforma il file XML in un documento HTML nella seconda riga.
• Converte il risultato della trasformazione (la stringa HTML) in PDF nelle righe rimanenti.

Diamo un'occhiata più da vicino ai primi due punti. Il terzo punto è coperto completamente in questa sezione.

Crea una trasformazione XSLT

Il primo passo nel processo di conversione è creare un oggetto di trasformazione XSLT. Il codice seguente mostra come creare un oggetto di questo tipo:

public static XslCompiledTransform CreateTransform(string xsltFileName)
{
    var transform = new XslCompiledTransform();
    transform.Load(xsltFileName);
    return transform;
}

Come suggerisce il nome, XslCompiledTransform compila il foglio di stile fornito e ne produce codice IL. Se il tuo codice deve trasformare XML in PDF in blocco, riusa lo stesso oggetto di trasformazione per migliorare le prestazioni.

Trasforma XML in HTML

Il secondo passo consiste nel generare HTML dall'XML usando l'oggetto di trasformazione XSLT creato nel passaggio precedente.

public static string TransformToHtml(string xmlFileName, XslCompiledTransform transform)
{
    using var xmlReader = XmlReader.Create(xmlFileName);
    using var sw = new StringWriter();
    using var writer = XmlWriter.Create(sw, transform.OutputSettings);
    transform.Transform(xmlReader, null, writer);
    return sw.ToString();
}

Il codice usa XmlReader e XmlWriter perché sono adatti a file XML di grandi dimensioni e aiutano a mantenere basso l'uso della memoria.

Codice di esempio per la conversione da XML a PDF

Il nostro repository di esempi include versioni C# e VB.NET di una sample application che converte una fattura XML in un PDF. La sample application contiene un esempio di fattura XML e il foglio di stile XSLT corrispondente.

Quando navighi verso un URL che restituisce XML in un browser moderno, il browser può applicare automaticamente l'XSLT associato (se presente) per generare e visualizzare HTML leggibile. Questo funziona solo quando sia i file XML sia quelli XSLT sono ospitati sullo stesso server. Per evitare richieste cross-origin, il browser non caricherà né applicherà il foglio di stile quando apri direttamente il file XML dal file system locale.

Compromessi e modi alternativi per creare PDF

L'API da HTML a PDF non è l'unico modo per generare PDF con Docotic.Pdf, e non è sempre il più efficiente. Questa sezione illustra le alternative per aiutarti a scegliere l'opzione giusta per il tuo scenario.

Quando HTML to PDF è la scelta giusta

Scegli l'approccio HTML to PDF quando il tuo team crea già documenti con HTML/CSS. In particolare se i tuoi documenti assomigliano a pagine web: fatture, ordini di acquisto, certificati, ricevute e simili.

Il componente aggiuntivo HtmlToPdf consente ai team di riusare modelli HTML/CSS esistenti e beneficiare di funzionalità di layout e rendering ad alta fedeltà. Usando il componente aggiuntivo, il percorso verso un output PDF di alta qualità può essere il più rapido.

Limitazioni da tenere presenti

L'API da HTML a PDF usa il motore di rendering HTML di Google Chrome. Questo motore è potente, ma comporta un overhead. Una conversione tipica da HTML a PDF consuma più CPU e memoria rispetto, per esempio, al disegno diretto su un Canvas di una pagina PDF. Questo overhead può rallentare la generazione batch ad alto volume.

Il motore del browser aumenta anche l'ingombro runtime, che può essere indesiderabile in immagini Docker minime o in ambienti con risorse limitate. Per esempio, l'API potrebbe non funzionare in ambienti serverless con limiti molto rigidi su consumo di memoria e tempo di esecuzione.

Altri modi per produrre PDF in Docotic.Pdf

La libreria Docotic.Pdf offre diversi altri modi per creare documenti, ciascuno adatto a esigenze diverse:

• Generazione diretta di PDF tramite l'API Canvas
  Ideale per layout strutturati e prevedibili come biglietti, etichette o moduli. Offre prestazioni massime e controllo completo su coordinate, tipografia e posizionamento del contenuto.

• Generazione di PDF basata su template
  Spesso è la scelta migliore quando si lavora con template approvati e vincolati da requisiti di conformità. Parti da un PDF esistente e compili campi, sostituisci segnaposto e allega documenti correlati secondo necessità.

• Generazione di PDF con l'API Layout
  Fornisce elementi costitutivi come pagine, contenitori, immagini, paragrafi di testo e altri elementi di layout. Descrivi il layout PDF interamente in codice usando un'API fluida e la libreria genera il PDF dal tuo layout.

• Composizione da altri PDF e immagini
  Offre un modo leggero per assemblare estratti, report, pacchetti di documenti e altri documenti a partire da PDF e immagini esistenti. Converti le immagini in pagine PDF, combina più PDF, aggiungi pagine o riusa frammenti.

Confronto con altre soluzioni HTML to PDF

Per aiutarti a scegliere la libreria HTML‑to‑PDF giusta per .NET, ecco informazioni su come Docotic.Pdf con il componente aggiuntivo HtmlToPdf si confronta con altre soluzioni popolari per convertire HTML in PDF.

Punti chiave del confronto

La maggior parte delle soluzioni basate su browser offre rendering di alta qualità e supporta completamente HTML, CSS e JavaScript moderni. Tuttavia, ci sono differenze importanti.

Confronto dettagliato

Controlla le informazioni nella tabella per avere il quadro completo e trarre le tue conclusioni.

Conclusione

Docotic.Pdf con il componente aggiuntivo HtmlToPdf offre conversioni da HTML a PDF affidabili e di alta qualità insieme a un'API PDF completa di funzionalità. La libreria funziona bene per generare report PDF, fatture, ricevute e altri documenti aziendali da HTML, preservando una fedeltà visiva perfetta al pixel.

Il componente aggiuntivo fornisce un'API .NET asincrona che gira completamente on-premise. I tuoi dati non lasciano mai i tuoi server, dandoti il controllo completo su sicurezza e privacy.

Oltre alla conversione da HTML a PDF, Docotic.Pdf può aggiungere protezione con password ai PDF generati e firmarli con firme digitali, incluse firme abilitate LTV.

Puoi assemblare i documenti finali unendo più PDF generati. Se un PDF diventa troppo grande dopo la conversione HTML o l'unione, la libreria può rimuovere gli oggetti duplicati all'interno del file e applicare altri metodi per ridurre le dimensioni del file. Per migliorare l'esperienza di lettura, Docotic.Pdf può anche ottimizzare i PDF per Fast Web View (linearizzare il PDF).

Passi successivi:

• Rivedi i codici di esempio per HTML to PDF
• Esplora l'API della libreria più ampia
• Contattaci per domande o suggerimenti

Domande frequenti

Come scegliere una libreria HTML to PDF per .NET?

Prima di selezionare una libreria, definisci e raccogli i tuoi requisiti. Risparmierai tempo nella valutazione se sai che una libreria candidata non può unire PDF convertiti e questa funzionalità è richiesta per la tua soluzione. Vedi la sezione di confronto per un confronto affiancato delle librerie HTML to PDF più popolari per .NET.

Perché il mio HTML non viene renderizzato correttamente nel PDF?

Se il tuo HTML appare corretto in Google Chrome ma non nel PDF generato, controlla le opzioni di conversione. Assicurati che ci sia abbastanza larghezza per contenere il contenuto. L'HTML potrebbe anche richiedere l'esecuzione di JavaScript prima della conversione.

Perché usare template HTML invece di API PDF dirette?

L'uso di template HTML rende la tua soluzione molto flessibile nel layout dei documenti. Puoi cambiare facilmente l'aspetto dei tuoi PDF usando le potenti capacità di styling di HTML e CSS. Inoltre, non devi duplicare il design dei tuoi documenti online con un'API PDF.

Come convertire ASPX in PDF?

Per convertire ASPX in PDF, lascia che il motore ASP.NET generi l'HTML della pagina ASPX e poi converti quell'HTML in PDF usando la libreria Docotic.Pdf. Ulteriori dettagli sono disponibili nella sezione corrispondente.

Come sovrapporre un SVG su un PDF?

Per sovrapporre un SVG su un PDF, genera un PDF dall'SVG, quindi crea un XObject dalla prima pagina del documento generato. Poiché l'XObject ha uno sfondo trasparente, puoi posizionarlo sopra una pagina PDF in un altro documento.

Come aggiungere una filigrana al PDF generato?

Per aggiungere una filigrana a un documento PDF prodotto da HTML, crea un XObject, riempilo con il contenuto della filigrana e poi disegna l'XObject sopra le pagine del documento. Puoi usare grafica vettoriale, immagini e testo per la filigrana.

Docotic.Pdf è migliore di wkhtmltopdf?

Docotic.Pdf supporta completamente HTML, CSS e JavaScript moderni, mentre wkhtmltopdf spesso produce rendering incoerenti per documenti web moderni. Inoltre, Docotic.Pdf offre API oltre la conversione da HTML a PDF. Per esempio, la libreria può firmare PDF con firme digitali abilitate LTV, mentre wkhtmltopdf può solo convertire HTML.