Crea documenti PDF in C# e VB.NET

Come sviluppatore .NET, hai bisogno di generare report PDF, fatture, ricevute o altri documenti? Usare la libreria Docotic.Pdf per generare documenti PDF nei progetti .NET Core, .NET Standard o .NET Framework. Puoi farlo facilmente e senza conoscere il formato PDF.

API .NET per la generazione di PDF

Docotic.Pdf è la libreria di codice gestita al 100% senza dipendenze esterne. Puoi usarlo per creare documenti PDF su ambienti cloud Windows, Linux, Amazon e Azure. Anche macOS, iOS, Android e altri ambienti cloud vanno bene.

La libreria offre diversi modi per generare documenti PDF. Innanzitutto, puoi utilizzare l'API di layout di alto livello per aggiungere intestazioni e piè di pagina, tabelle, paragrafi e suddividere automaticamente il contenuto nelle pagine. L'API di layout è disponibile nel componente aggiuntivo gratuito Docotic.Pdf.Layout.

Oppure puoi creare documenti PDF basati su modelli HTML utilizzando il componente aggiuntivo HTML to PDF (anch'esso gratuito). Leggi l'articolo Converti HTML in PDF per maggiori dettagli.

Inoltre, puoi produrre documenti PDF utilizzando l'API della libreria principale. Supporta qualsiasi contenuto PDF:

• testo,
• immagini,
• grafica vettoriale,
• moduli,
• annotazioni,
• segnalibri,
• livelli e altri.

Tuttavia, l'API principale non supporta componenti di layout di alto livello, come intestazioni, tabelle e sezioni. Con la libreria principale, dovrai misurare il contenuto e dividerlo tu stesso tra le pagine PDF.

Puoi anche utilizzare insieme i componenti aggiuntivi con la libreria principale. Ad esempio, genera il documento PDF utilizzando l'API di layout e quindi aggiungi più contenuti con la libreria principale. Tieni presente che il componente aggiuntivo di layout supporta .NET Standard 2.1, .NET Core, .NET 5 e framework più recenti. La libreria principale e il componente aggiuntivo da HTML a PDF supportano .NET Standard 2.0, .NET 4.7.2+, .NET Core, .NET 5 e versioni successive.

I componenti aggiuntivi di Docotic.Pdf sono disponibili su NuGet e inclusi nello zip con file binari della libreria. Per provare la libreria senza restrizioni sulla modalità di valutazione, è possibile ottenere la chiave di licenza gratuita limitata nel tempo qui.

Crea documenti PDF utilizzando l'API di layout

Questo esempio C# mostra come generare un documento PDF in C# utilizzando l'API di layout:

PdfDocumentBuilder
    .Create()
    .Generate("long-text.pdf", doc => doc.Pages(page =>
    {
        string text = File.ReadAllText(@"C# in Depth, Fourth Edition.txt");
        page.Content().Text(text);

        page.Footer().AlignCenter().Text(t => t.CurrentPageNumber());
    }));

Il codice converte un file di testo in un PDF. Divide il testo lungo in pagine e disegna anche i numeri di pagina nell'area del piè di pagina. Non è necessario calcolare l'altezza del testo o contare le pagine: la libreria si occupa di queste attività di routine.

L'API di layout è un'API fluente. La maggior parte delle chiamate possono essere concatenate insieme, quindi è possibile scrivere un codice più compatto rispetto ai framework "dichiarativi". Esaminiamo l'API in modo più dettagliato.

Imposta le proprietà del documento PDF

La generazione del PDF inizia con la classe PdfDocumentBuilder. Consente di specificare le proprietà di un documento PDF generato. Ad esempio, puoi impostare metadati, crittografia, versione PDF o abilitare la visualizzazione Web veloce. Ecco l'esempio C# di base:

PdfDocumentBuilder
    .Create()
    .Encryption(new PdfStandardEncryptionHandler("owner", "user"))
    .Info(info =>
    {
        info.Author = "Docotic.Pdf library";
        info.Title = "How to create PDF in .NET";
        info.Keywords = "C#, VB.NET";
    })
    .Version(PdfVersion.Pdf16)
    .Generate("result.pdf", doc => doc.Pages(_ => {}));

Questo esempio crea un documento PDF vuoto protetto da password con metadati personalizzati e lo salva in un file. Puoi anche salvare il documento in uno stream, basta usare il overload PdfDocumentBuilder.Generate(Stream, ..).

Quando imposti un PdfDocumentBuilder, è il momento di popolare il documento PDF con il contenuto. L'API di layout fornisce un oggetto Document per la registrazione di risorse comuni (tipografia, immagini) e la definizione del contenuto della pagina PDF. Puoi configurare un Document nel secondo argomento dei metodi PdfDocumentBuilder.Generate. Impariamo come impostare le pagine PDF.

Definire il layout della pagina PDF

Questo esempio C# mostra come creare un documento PDF con pagine A3 con orientamento orizzontale:

PdfDocumentBuilder.Create().Generate("pages.pdf", doc =>
{
    doc.Pages((PageLayout page) =>
    {
        page.Size(PdfPaperSize.A3, PdfPaperOrientation.Landscape)
            .MarginVertical(50)
            .MarginHorizontal(40);

        page.Header().PaddingBottom(30).AlignRight().Text("Hello PDF");

        page.Content().Column(c =>
        {
            c.Item().Text("Page 1");
            c.Item().PageBreak();
            c.Item().Text("Page 2");
        });

        page.Footer().Text(t => t.CurrentPageNumber());
    });
});

Il metodo Document.Pages() definisce il layout per una o più pagine. Innanzitutto, il codice di esempio definisce le impostazioni comuni per tutte le pagine: dimensioni, orientamento, margini. Puoi anche specificare la direzione del contenuto, lo stile del testo predefinito o il colore dello sfondo.

Quindi, l'esempio genera il layout e il contenuto della pagina. La classe PageLayout fornisce metodi per posizionare il contenuto della pagina nei seguenti slot:

• Background() - un livello di sfondo coperto da altri contenuti
• Header() - un'intestazione comune per tutte le pagine
• Content() - il contenuto della pagina principale
• Footer() - un piè di pagina comune per tutte le pagine
• Foreground() - un livello in primo piano che copre altri contenuti

Il motore di layout genera pagine in base al contenuto aggiunto allo slot PageLayout.Content(). Altri slot vengono ripetuti su ogni pagina. Puoi aggiungere contenuto agli slot utilizzando la classe LayoutContainer. Questo è un elemento chiave dell'API di layout, che consente di generare layout, tabelle, testo o immagini arbitrari.

L'esempio precedente utilizza il metodo LayoutContainer.Column che impila verticalmente il contenuto. Quella colonna contiene 3 elementi: la porzione di testo per la prima pagina, l'interruzione di pagina esplicita e la porzione di testo per la seconda pagina.

Esiste anche il metodo LayoutContainer.Row. Guarda come creare documenti PDF a più colonne utilizzando righe e colonne insieme.

È possibile combinare diversi layout di pagina in un documento PDF. Basta chiamare più volte il metodo Document.Pages. Per un esempio, guarda l'esempio Impostazioni del layout della pagina PDF su GitHub.

Aggiungi testo ai documenti PDF

Il testo è una parte importante dei documenti PDF. Puoi utilizzare i metodi LayoutContainer.Text per aggiungere testo. In precedenza, hai visto i casi d'uso per l'overload LayoutContainer.Text(string). Diamo un'occhiata a un altro sovraccarico di questo metodo:

PdfDocumentBuilder.Create().Generate("text.pdf", doc =>
{
    doc.Pages(p => p.Content().Text(text =>
    {
        text.Span("VB.NET").Style(t => t.Strong);
        text.Span(" is a multi-paradigm, object-oriented programming language, implemented on.NET, Mono, and the ");
        text.Hyperlink(".NET Framework", new Uri("https://dotnet.microsoft.com/en-us/download/dotnet-framework"));
        text.Line(".");

        text.Line("Microsoft launched VB.NET in 2002 as the successor to its original Visual Basic language.");
    }));
});

La classe TextContainer fornisce metodi per disegnare testo, collegamenti, numeri di pagina. Utilizza i metodi Span e Line per aggiungere testo a una riga corrente. Il metodo Line completa inoltre la riga corrente. Questo esempio utilizza anche il metodo Hyperlink che aggiunge un collegamento a una risorsa esterna.

Ecco un altro esempio che mostra come utilizzare i numeri di pagina dinamici nel piè di pagina:

PdfDocumentBuilder.Create().Generate("footer.pdf", doc =>
{
    doc.Pages(p => p.Footer().AlignRight().Text(text =>
    {
        text.Style(t => t.Parent.FontColor(new PdfRgbColor(255, 0, 0)));

        text.CurrentPageNumber();
        text.Span(" / ");
        text.PageCount();
    }));
});

L'API di layout fornisce un modo per formattare i numeri di pagina. Ad esempio, puoi disegnare numeri di pagina esadecimali in questo modo:

text.CurrentPageNumber().Format(p => "0x" + p?.ToString("x2"));

L'esempio Aggiungi intestazione e piè di pagina ai documenti PDF nell'esempio C# e VB.NET illustra come formattare i numeri di pagina come numeri romani.

Potresti notare che gli esempi precedenti utilizzano il metodo Style. Esaminiamo il concetto di stili di testo in modo più dettagliato.

Tipografia

Gli stili di testo ti consentono di personalizzare l'aspetto del testo. La classe TextStyle fornisce metodi per modificare la dimensione del carattere, la spaziatura delle lettere, i colori e altre proprietà del testo. Gli oggetti TextStyle sono immutabili, quindi ogni chiamata al metodo produce un nuovo stile di testo. Puoi applicare lo stile del testo a diversi livelli di layout:

PdfDocumentBuilder.Create().Generate("text-styles.pdf", doc =>
{
    doc.Pages(page =>
    {
        page.TextStyle(TextStyle.Parent.FontSize(30));

        page.Content()
            .TextStyle(TextStyle.Parent.FontColor(new PdfRgbColor(0, 0, 255)))
            .Text(t =>
            {
                t.Style(TextStyle.Parent.Underline());

                t.Span("Hello PDF").Style(TextStyle.Parent.DirectionRightToLeft());
            });
    });
});

La proprietà TextStyle.Parent restituisce uno stile speciale con tutte le proprietà del testo non definite. L'esempio precedente disegna "Hello PDF" con un carattere blu, sottolineato, di 30 punti, in ordine inverso (da destra a sinistra). Guarda l'esempio Personalizza l'aspetto del testo nei documenti PDF per un altro esempio di ereditarietà dello stile di testo.

La classe TextStyle supporta la personalizzazione di tutto tranne un carattere associato. Utilizza i metodi Document.TextStyleWithFont quando devi specificare un carattere personalizzato per il tuo stile di testo. Questo esempio C# mostra come utilizzare un carattere di sistema:

PdfDocumentBuilder.Create().Generate("fonts.pdf", doc =>
{
    doc.Pages(page =>
    {
        TextStyle style = doc.TextStyleWithFont(SystemFont.Family("Arial").Bold());
        page.Content().Text("Bold text").Style(style);
    });
});

Per impostazione predefinita, il motore di layout rimuove i glifi dei caratteri inutilizzati. Per questo motivo, i documenti generati potrebbero avere dimensioni ridotte anche per i caratteri di grandi dimensioni. Puoi anche specificare un caricatore di caratteri personalizzato, caratteri di fallback e un gestore per i glifi mancanti. Per ulteriori dettagli, vedere l'esempio Utilizza caratteri diversi nei documenti PDF.

L'API di layout fornisce una raccolta di stili predefiniti. Puoi utilizzarli o personalizzarli tramite la classe Typography:

PdfDocumentBuilder.Create().Generate("typography.pdf", doc =>
{
    doc.Typography(t =>
    {
        var baseFont = new FileInfo("arial.ttf");
        t.Document = doc.TextStyleWithFont(baseFont);
        t.Header = t.Parent.FontSize(20).FontColor(new PdfGrayColor(20));
        t.Footer = t.Footnote;
    });

    doc.Pages(page =>
    {
        page.Header().AlignCenter().Text("Header");

        page.Content().Text(t =>
        {
            t.Line("Title").Style(t => t.Title);
            t.Line("Heading 1").Style(t => t.Heading1);
            t.Line("Regular");
        });

        page.Footer().Height(20).AlignCenter().Text(t => t.CurrentPageNumber());
    });
});

Con la classe Typography, non è necessario utilizzare variabili per mantenere i riferimenti allo stile del testo. Puoi registrare gli stili necessari utilizzando i metodi Document.Typography e successivamente caricarli dall'oggetto Typography. Scopri come utilizzare gli stili predefiniti e personalizzati nell'esempio Tipografia.

Immagini

Come il testo e i caratteri, le immagini sono un'altra parte fondamentale dei documenti PDF. L'API di layout ti consente di aggiungere immagini in questo modo:

PdfDocumentBuilder.Create().Generate("image.pdf", doc =>
{
    var imageFile = new FileInfo("image.jpg");
    Image image = doc.Image(imageFile);
    doc.Pages(page => page.Content().MaxWidth(200).Image(image));
});

Tabelle

L'API di layout consente di generare tabelle. Questo esempio C# mostra come aggiungere una tabella a un documento PDF:

PdfDocumentBuilder.Create().Generate("table.pdf", doc =>
{
    doc.Pages(page =>
    {
        page.Content().Table(t =>
        {
            t.Columns(c =>
            {
                c.ConstantColumn(200);
                c.RelativeColumn(1);
            });

            t.Header(h =>
            {
                h.Cell().Text("Product");
                h.Cell().Text("Features");
            });

            t.Cell().Text("Docotic.Pdf");
            t.Cell().Text("Extract text, PDF to images, compress PDF");
            t.Cell().Text("Docotic.Pdf.Layout");
            t.Cell().Text("Create PDF");
        });
    });
});

È possibile creare tabelle di qualsiasi complessità. Questo esempio mostra come utilizzare i bordi, gli sfondi e gli intervalli delle celle.

Collegamenti interni

I documenti PDF supportano collegamenti interni che consentono di generare segnalibri o sommari. Questo esempio C# di base mostra come aggiungere un collegamento a una sezione del documento utilizzando l'API di layout:

PdfDocumentBuilder.Create().Generate("link.pdf", doc =>
{
    doc.Pages(page =>
    {
        page.Content().Column(c =>
        {
            const string SectionName = "Chapter 1";
            c.Item().SectionLink(SectionName).Text("Link");

            c.Item().PageBreak();

            c.Item().Section(SectionName).Text("Target");
        });
    });
});

Puoi anche scaricare e provare l'esempio Aggiungi sommario ai documenti PDF da GitHub.

Layout complessi

Puoi combinare diversi componenti di layout per generare documenti PDF complessi. Scarica e prova l'esempio Genera documenti PDF con layout complesso da GitHub.

È possibile estendere l'API di layout. I metodi LayoutContainer.Component e LayoutContainer.Container ti consentono di riutilizzare componenti personalizzati. L'esempio Componenti di layout mostra come implementare un componente personalizzato utilizzando l'interfaccia ILayoutComponent.

Conclusione

Libreria Docotic.Pdf fornisce diversi mezzi per creare documenti PDF in C# e VB.NET. È possibile generare documenti PDF da zero con o senza utilizzare il componente aggiuntivo di layout. In alternativa, puoi creare PDF da HTML utilizzando il componente aggiuntivo da HTML a PDF.

Contattaci se hai domande sulla generazione di PDF.

Risorse correlate

• Esempi API di layout
• Documentazione API di layout
• Firma documenti PDF in C# e VB.NET
• Crittografa documenti PDF in C# e VB.NET
• Converti HTML in PDF in C# e VB.NET