Creazione dei documenti

Tradotto da Bit Miracle. Articolo originale di Sergey Bobrovsky

Aggiornato il 2 luglio 2026

Ovviamente, devi generare un documento PDF con i tuoi dati. Ma spesso vuoi anche cifrare il file PDF con password. E in genere vuoi aggiungere metadati PDF al file di output.

Continua a leggere per sapere come indicare al generatore di cifrare i file PDF. Come specificare autore e parole chiave del documento.

Questo articolo fa parte di una serie su Layout API per la generazione di PDF. Se non conosci l'API, leggi prima la sezione Introduzione a Layout API.

Crea e genera

Il punto di ingresso di Layout API è la classe PdfDocumentBuilder. Si inizia creando un'istanza della classe con il metodo Create. Per generare un PDF, si chiama il metodo Generate della classe.

Generate può salvare l'output in un file o in uno stream. Entrambe le versioni del metodo richiedono come secondo parametro un delegato di tipo Action<Document>. Nel delegato descrivi il documento che vuoi ottenere. La libreria genererà un PDF in base alla descrizione.

Crittografia

Per cifrare il PDF di output, chiama il metodo Encryption prima del metodo Generate.

Devi creare e fornire un gestore di crittografia. Per cifrare PDF con password, usa un gestore di tipo PdfStandardEncryptionHandler.

PdfDocumentBuilder.Create()
    .Encryption(new PdfStandardEncryptionHandler("owner", "user"))
    .Generate("encrypted-with-password.pdf", doc => doc.Pages(_ => { }));

Puoi anche cifrare PDF con certificati. Consulta l'articolo Cifrare documenti PDF. Contiene informazioni dettagliate sui gestori di crittografia e sui permessi PDF.

Metadati PDF

In alcuni flussi di lavoro, è molto importante specificare correttamente le parole chiave PDF e l'autore PDF nel PDF di output. Layout API offre un modo semplice per farlo. Chiama il metodo Info prima del metodo Generate e fornisci i valori dei metadati nel delegato.

PdfDocumentBuilder.Create()
    .Info(info =>
    {
        info.Author = $"{Environment.UserName}";
        info.Title = "Generate encrypted PDF with custom metadata";
        info.Keywords = "Metadata keywords encryption";
    })
    .Generate("metadata.pdf", doc => doc.Pages(_ => { }));

Opzioni

Per lo stesso contenuto, la libreria può creare file PDF con una struttura interna diversa. Queste opzioni influiscono sul PDF di output.

Versione

Usa il metodo Version per impostare la versione minima del formato PDF per il PDF di output.

PdfDocumentBuilder.Create()
    .Version(PdfVersion.Pdf17)
    .Generate("version.pdf", doc => doc.Pages(_ => { }));

Nota che la libreria può creare un PDF con una versione superiore a quella specificata. Succede quando il contenuto del documento richiede una versione più recente. In altre parole: quando il documento usa funzionalità non disponibili nella versione specificata dello standard PDF.

Flussi di oggetti

Per impostazione predefinita, la libreria usa flussi di oggetti nei PDF generati. Questo aiuta a produrre file più piccoli e meglio compressi.

Puoi indicare all'API di creare file PDF senza flussi di oggetti usando il metodo ObjectStreams.

PdfDocumentBuilder.Create()
    .ObjectStreams(false)
    .Generate("no-object-streams.pdf", doc => doc.Pages(_ => { }));

Ti consiglio di continuare a usare i flussi di oggetti, a meno che non ci siano requisiti normativi. Oppure quando altre parti del tuo flusso di lavoro non possono elaborare documenti con flussi di oggetti.

Provider di stream

La libreria usa gli stream come archivio intermedio. Durante la generazione di un PDF, lo fa per le immagini e altri oggetti di grandi dimensioni. La libreria ottiene gli stream tramite il provider di stream. Esiste sempre un'istanza associata al corrente PdfDocumentBuilder.

Per impostazione predefinita, la libreria usa PdfMixedStorageStreamProvider. Questa implementazione del provider di stream fornisce stream che mantengono i dati in memoria. Questi stream scaricano il contenuto in file temporanei quando i dati diventano troppi. Ciò consente di ridurre il consumo di memoria ed evitare la frammentazione della LOH.

Puoi usare una tua implementazione dell'interfaccia IPdfStreamProvider quando generi file PDF. Uno dei motivi del cambio potrebbe essere la lentezza e/o il costo elevato delle operazioni su disco. Gli ambienti cloud potrebbero rientrare in questa descrizione.

Questo codice mostra come generare PDF interamente in memoria, senza file temporanei. Nota che ciò richiederà molta più memoria rispetto alle opzioni predefinite.

using var memoryOnlyProvider = new PdfMemoryStreamProvider();
PdfDocumentBuilder.Create()
    .StreamProvider(memoryOnlyProvider)
    .Generate("created-without-temp-files.pdf", doc => doc.Pages(_ => { }));

Alla fine la libreria chiama Dispose per ogni stream ottenuto tramite il provider di stream. Devi disporre tu stesso l'istanza del provider di stream.