Questa pagina può contenere testo tradotto automaticamente.
Convertire HTML in PDF in C# e VB.NET
Se hai già investito molto tempo e denaro nella creazione di contenuti in formato HTML, potresti voler creare PDF da quel codice HTML. Questo approccio è una scelta naturale per chiunque voglia evitare duplicazioni di lavoro.
Questo articolo è una guida dettagliata alla conversione di HTML in PDF in .NET utilizzando Docotic.Pdf insieme al suo componente aggiuntivo gratuito HtmlToPdf.
Per informazioni sul perché Docotic.Pdf sia la scelta giusta, su come installare il componente aggiuntivo e su come funziona internamente la conversione, consulta la pagina Panoramica dell'API da HTML a PDF.
Semplice conversione da HTML a PDF C#
Per prima cosa, installa il componente aggiuntivo.
Install-Package BitMiracle.Docotic.Pdf.HtmlToPdf
Utilizzando l'API HTML-PDF, il codice di conversione C# può apparire così:
static async Task ConvertUrlToPdfAsync(string urlString, string pdfFileName)
{
using var converter = await HtmlConverter.CreateAsync();
using var pdf = await converter.CreatePdfAsync(new Uri(urlString));
pdf.Save(pdfFileName);
}
È piuttosto semplice. Sono necessarie solo due chiamate per generare un documento PDF.
Il codice crea un'istanza del convertitore e la utilizza per generare un PDF da HTML. È possibile modificare il documento PDF o firmarlo con una firma digitale. Per semplicità, il codice di esempio salva il documento così com'è.
Come potete vedere, l'API è asincrona e non fornisce alcun metodo sincronico.
Utilizzo dell'API asincrona nel codice sincrono
In alcuni casi è necessario richiamare l'API da codice sincrono. Ad esempio, quando l'applicazione console utilizza una versione precedente di C# e non si dispone di un Main asincrono. Non preoccuparti, puoi comunque utilizzare il componente aggiuntivo nella tua app.
Il codice seguente mostra come convertire un URL in PDF in un normale metodo sincrono:
Task.Run(async () =>
{
using var converter = await HtmlConverter.CreateAsync();
var uri = new Uri("https://bitmiracle.com/pdf-library/html-pdf/");
using var pdf = await converter.CreatePdfAsync(uri);
pdf.Save("output.pdf");
}).GetAwaiter().GetResult();
Le applicazioni VB.NET utilizzano un codice simile. Ecco un frammento che mostra come convertire HTML in PDF in un codice VB.NET sincrono.
Task.Run(
Async Function()
Using converter = Await HtmlConverter.CreateAsync()
Dim uri = New Uri("https://bitmiracle.com/pdf-library/html-pdf/")
Using pdf = Await converter.CreatePdfAsync(uri)
pdf.Save("output.pdf")
End Using
End Using
End Function
).GetAwaiter().GetResult()
Si noti che in generale non è consigliabile chiamare metodi asincroni in modo sincrono, quindi utilizzare il wrapper solo quando non si hanno altre scelte.
Codice di esempio
Forniamo codici di esempio per applicazioni console, Windows Forms e WPF. Scarica progetti di test completi dal nostro repository GitHub:
È disponibile anche il gruppo di esempi HTML to PDF. Ogni esempio è disponibile in versione C# e VB.NET.
Crea un PDF con una stringa o un file HTML in C# e VB.NET
Convertire una stringa HTML in PDF è facile con l'API. La stringa può contenere un documento HTML completo o solo un frammento. Il convertitore creerà un PDF dal codice HTML per te.
using var converter = await HtmlConverter.CreateAsync();
var html = "<body><br><br><br><h1>Hello, World</h1></body>";
using var pdf = await converter.CreatePdfFromStringAsync(html);
pdf.Save("output.pdf");
Il codice HTML può contenere riferimenti relativi a immagini, script e file CSS. Per convertire correttamente tale codice, è necessario specificare un URL di base per tutti i link relativi nel codice HTML. Ecco come specificare un URL di base utilizzando le opzioni di conversione:
using var converter = await HtmlConverter.CreateAsync();
var incompleteHtml = "<img src=\"/images/team.svg\"></img>";
var options = new HtmlConversionOptions();
options.Load.BaseUri = new Uri("https://bitmiracle.com/");
using var pdf = await converter.CreatePdfFromStringAsync(incompleteHtml, options);
pdf.Save("output.pdf");
Il nostro repository GitHub contiene il progetto di test completo.
Convertire un file HTML è praticamente la stessa cosa che convertire un URL. Basta usare l'overload CreatePdfAsync, che accetta un percorso anziché un URL. L'URL di base e altre opzioni sono supportate anche durante la conversione di un file HTML in PDF in codice C# o VB.NET.
var sampleHtmlPath = @"C:\path\to\sample.html";
using var pdf = await converter.CreatePdfAsync(sampleHtmlPath);
pdf.Save("output.pdf");
Puoi anche convertire le immagini SVG in PDF utilizzando l'API.
Utilizza dimensioni di pagina, margini e scala personalizzati
Quando si gestiscono pagine web con layout ampi, è possibile aumentare le dimensioni del PDF di output o rimpicciolire il contenuto per adattarlo alla pagina PDF. Per posizionare meglio il contenuto ridimensionato, è anche possibile impostare i margini.
Un PDF ben ridimensionato offre un'esperienza di lettura migliore, poiché i lettori non dovranno ingrandire o rimpicciolire per visualizzare correttamente il contenuto. Se il documento HTML è difficile da leggere a causa di un carattere di piccole dimensioni, è possibile ingrandire il contenuto.
Per impostazione predefinita, l'API genera PDF con dimensioni di pagina pari al formato A4. Non sono previsti margini né ingrandimento. Utilizzando le opzioni di conversione, è possibile modificare queste impostazioni.
Scopri come impostare il fattore di scala e i margini durante la generazione di PDF da HTML
using var converter = await HtmlConverter.CreateAsync();
var html = "<html><head><style>body { background-color: coral; margin-top: 100px;}</style></head>" +
"<body><h1>Did you notice the margins and the scale?</h1></body></html>";
var options = new HtmlConversionOptions();
options.Page.MarginLeft = 10;
options.Page.MarginTop = 20;
options.Page.MarginRight = 30;
options.Page.MarginBottom = 40;
options.Page.Scale = 1.5;
using var pdf = await converter.CreatePdfFromStringAsync(html, options);
pdf.Save("output.pdf");
Il repository di campioni Docotic.Pdf contiene il progetto completo.
Specificare i modelli di intestazione e piè di pagina
L'API di conversione da HTML a PDF può aggiungere blocchi di intestazione/piè di pagina ripetibili alle pagine generate. Il convertitore crea i blocchi dai modelli HTML specificati in opzioni pagina. Consigliamo di utilizzare stili in linea e URI dati per le immagini all'interno dei modelli.
Il convertitore posiziona intestazioni e piè di pagina all'interno dei margini di pagina. Dato che i margini di pagina predefiniti sono piccoli, il contenuto di intestazione e piè di pagina potrebbe non essere visibile. Consigliamo di specificare esplicitamente i margini superiore e inferiore. Le dimensioni devono corrispondere rispettivamente a quelle dell'intestazione e del piè di pagina.
Scopri come convertire HTML in PDF e aggiungere intestazione e piè di pagina
using var converter = await HtmlConverter.CreateAsync();
var options = new HtmlConversionOptions();
options.Page.HeaderTemplate = File.ReadAllText("header-template.html");
options.Page.MarginTop = 50;
options.Page.FooterTemplate = File.ReadAllText("footer-template.html");
options.Page.MarginBottom = 50;
var url = new Uri("https://www.iana.org/numbers");
using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("output.pdf");
I modelli utilizzano codice HTML standard con supporto per alcune variabili. Queste variabili sono
date, title, url, pageNumber e totalPages. Sia i modelli di
intestazione che i modelli di
piè di pagina supportano lo
stesso set di variabili.
Il codice completo del progetto di test e del modello è disponibile nel repository degli esempi Docotic.Pdf. Il codice di esempio mostra come utilizzare le variabili e gli URI dei dati nei modelli.
Conversione da HTML a PDF C# protetta da password
Alcune pagine web richiedono l'autenticazione per accedervi. Quando si accede a un URL sicuro che richiede l'autenticazione HTTP, il browser chiede di fornire nome utente e password.
Utilizzando le opzioni di conversione, è possibile indicare all'API di fornire le credenziali per le pagine web che richiedono l'accesso.
Questo codice C# mostra come convertire HTML protetto da password in PDF
using var converter = await HtmlConverter.CreateAsync();
var url = new Uri("http://httpbin.org/basic-auth/foo/bar");
var options = new HtmlConversionOptions();
options.Authentication.SetCredentials("foo", "bar");
using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("output.pdf");
Trova l'esempio di lavoro completo nel repository degli esempi.
È anche semplice se la pagina necessita di alcuni cookie impostati per funzionare correttamente. Basta aggiungere tali cookie alle opzioni. Ecco come fare:
var options = new HtmlConversionOptions();
options.Cookies.Add(new Cookie("sessionID", "my-session-ID"));
using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("output.pdf");
Ritarda l'avvio della conversione
Per impostazione predefinita, la conversione inizia subito dopo il caricamento. Ritardare la conversione da HTML a PDF può essere utile se la pagina continua ad aggiornarsi per un po' di tempo dopo il caricamento. Questo accade spesso quando si ha a che fare con contenuti dinamici generati da chiamate JavaScript o AJAX.
Il test Acid 3 è un esempio perfetto di una pagina che trarrebbe beneficio da un ritardo prima della conversione. Il test esegue il numero di controlli necessari per valutare la capacità di un browser di visualizzare correttamente pagine web complesse. Questi controlli richiedono tempo. Prova a modificare il tempo di attesa nel codice seguente per vedere come influisce sui risultati della conversione.
var options = new HtmlConversionOptions();
options.Start.SetStartAfterDelay(10 * 1000);
using var converter = await HtmlConverter.CreateAsync();
var url = new Uri("http://acid3.acidtests.org/");
using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("output.pdf");
Il codice sopra mostra come convertire HTML in PDF con un ritardo. Sebbene il tempo aggiuntivo aiuti a ottenere risultati migliori, si noti che l'aggiunta di ritardi può influire sulle prestazioni. Ritardi insufficienti possono influire negativamente sulla qualità della conversione. Un approccio alternativo all'utilizzo di un ritardo è utilizzare uno script che venga eseguito finché la pagina non è pronta.
È possibile ottenere il progetto di test completo nel repository degli esempi Docotic.Pdf.
Esegui JavaScript prima della conversione
L'API aggiuntiva consente di eseguire codice JS prima della conversione. Il codice può generare o modificare dinamicamente il contenuto HTML. Ad esempio, può attivare o disattivare elementi o attivare il caricamento dinamico del contenuto.
Il codice seguente mostra come ritardare la conversione da HTML a PDF fino al completamento di JavaScript.
using var converter = await HtmlConverter.CreateAsync();
var options = new HtmlConversionOptions();
var js = @"document.body.style.backgroundColor = 'green';";
options.Start.SetStartAfterScriptRun(js);
var url = new Uri("https://google.com");
using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("output.pdf");
Il frammento di codice sopra riportato utilizza un codice molto semplice solo per illustrare l'approccio. Per un esempio più pratico, consulta l'app di esempio corrispondente nel nostro repository GitHub. L'app mostra come gestire una pagina che carica dinamicamente i suoi contenuti. Il codice JavaScript nell'app scorre la pagina finché non ci sono più nuovi contenuti. Dopodiché, avviene la conversione in PDF.
Converti HTML in PDF in .NET ignorando gli errori SSL
Quando si inviano richieste sicure per caricare codice HTML, il componente aggiuntivo verifica se il certificato SSL che autentica l'identità di un sito web e abilita una connessione crittografata è valido e attendibile.
Per impostazione predefinita, il componente aggiuntivo genererà un'eccezione se il convertitore da HTML a PDF non considera attendibile il certificato per qualsiasi motivo. In genere, ciò accade a causa di un certificato autofirmato, revocato o scaduto.
Se si è consapevoli del rischio di accettare un certificato non attendibile, è possibile impostare il componente aggiuntivo in modo che eluda i controlli utilizzando le opzioni del motore.
var engineOptions = new HtmlEngineOptions
{
IgnoreSslErrors = true
};
using var converter = await HtmlConverter.CreateAsync(engineOptions);
var url = new Uri("https://self-signed.badssl.com/");
using var pdf = await converter.CreatePdfAsync(url);
pdf.Save("output.pdf");
Per il codice completo, vai al repository degli esempi Docotic.Pdf.
Sovrapporre HTML a un PDF esistente
In alcuni casi si desidera utilizzare un PDF esistente come sfondo per il risultato della conversione. Ad esempio, quando si ha l'immagine di un modulo e si desidera sovrapporre un elemento alle aree vuote dell'immagine. Il risultato sarà simile a un modulo compilato. Questo è possibile con Docotic.Pdf e il componente aggiuntivo.
Questo processo prevede la creazione di un nuovo PDF a partire dall'HTML (il contenuto sovrapposto) e la successiva unione con il PDF esistente. Il documento finale includerà sia il contenuto originale che il nuovo sovrapposto. Ecco il codice che illustra il processo.
using var converter = await HtmlConverter.CreateAsync();
var options = new HtmlConversionOptions();
options.Page.SetSizeInches(4.13, 5.83);
string htmlCode =
"<div style=\"position: absolute; top: 270px; right: 100px;\">" +
"I would like to put this here</div>";
using var htmlPdf = await converter.CreatePdfFromStringAsync(htmlCode, options);
using var pdf = new PdfDocument("pdf-to-merge-with.pdf");
var xObj = pdf.CreateXObject(htmlPdf.Pages[0]);
pdf.Pages[0].Canvas.DrawXObject(xObj, 0, 0);
pdf.Save("output.pdf");
È importante specificare una dimensione di pagina per la sovrapposizione. Di solito, la dimensione dovrebbe essere uguale a quella della pagina che si desidera sovrapporre. Dopodiché, sarà necessario generare il nuovo PDF con il contenuto della sovrapposizione. Si noti che lo sfondo è trasparente per impostazione predefinita. È possibile modificare lo sfondo eseguendo uno script prima della conversione se necessario.
Il codice sopra:
- crea un documento PDF con una pagina trasparente dall'HTML
- apre un PDF esistente
- crea un XObject dalla prima pagina del documento convertito nel documento esistente
- disegna l'XObject sopra la prima pagina PDF del documento esistente
Il progetto di prova completo con un PDF sorgente di esempio si trova nel repository degli esempi Docotic.Pdf.