Costruire documenti

Naturalmente, devi generare un documento PDF con i tuoi dati. Ma abbastanza spesso vuoi anche crittografare il file PDF con password. E di solito vuoi aggiungere metadati PDF al file di output.

Continua a leggere per sapere come istruire il generatore a crittografare i file PDF. Come specificare l'autore del documento e le parole chiave.

Questo articolo fa parte di una serie sull'API Layout per la generazione di PDF. Se sei nuovo all'API, leggi prima la parte Introduzione all'API Layout.

Create & Generate

Il punto di ingresso dell'API Layout è la classe PdfDocumentBuilder. Inizi creando un'istanza della classe con il metodo Create. Per generare un PDF, chiami il metodo Generate della classe.

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

Crittografia

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

Dovresti creare e fornire un gestore di crittografia. Per crittografare PDF con password, utilizzare un gestore di tipo PdfStandardEncryptionHandler.

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

Puoi anche crittografare PDF con certificati. Consulta l'articolo Crittografa documenti PDF. Contiene informazioni dettagliate sui gestori di crittografia e sulle autorizzazioni PDF.

Metadati del file PDF

In alcuni flussi di lavoro, è molto importante specificare le parole chiave PDF corrette e l'autore del PDF nel PDF di output. L'API Layout fornisce un modo semplice per questo. 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 struttura interna diversa. Queste opzioni influenzeranno il PDF di output.

Versione

Utilizza 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(_ => { }));

Tieni presente che la libreria può creare un PDF con una versione più grande di quella specificata. Succede quando il contenuto del documento richiede una versione più recente. In altre parole: quando il documento utilizza funzionalità non disponibili nella versione specificata dello standard PDF.

Flussi di oggetti

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

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

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

Ti suggerisco di continuare a utilizzare i flussi di oggetti a meno che non vi siano alcuni requisiti normativi. O quando alcune altre parti del flusso di lavoro non possono elaborare documenti con flussi di oggetti.

Fornitore di streaming

La libreria utilizza i flussi come spazio di archiviazione intermedio. Quando si genera un PDF, lo fa per immagini e altri oggetti di grandi dimensioni. La libreria riceve gli stream tramite il provider di streaming. Ce n'è sempre uno associato all'istanza corrente di PdfDocumentBuilder.

La libreria utilizza PdfMixedStorageStreamProvider per impostazione predefinita. Questa implementazione del provider di flussi fornisce flussi che mantengono i dati in memoria. Questi flussi trasferiscono i loro contenuti in file temporanei quando ci sono troppi dati. Ciò consente di ridurre il consumo di memoria ed evitare la frammentazione LOH.

Puoi utilizzare la tua implementazione dell'interfaccia IPdfStreamProvider durante la generazione di file PDF. Uno dei motivi del cambiamento potrebbe essere la lentezza e/o il costo delle operazioni del disco. Gli ambienti cloud potrebbero rientrare in questa descrizione.

Questo codice mostra come generare PDF completamente in memoria, senza file temporanei. Tieni presente 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 flusso che riceve tramite il provider di flussi. Devi smaltire tu stesso l'istanza del provider di streaming.