Documentos de construcción

Por supuesto, necesitas generar un documento PDF con tus datos. Pero muchas veces también querrás cifrar el archivo PDF con contraseñas. Y normalmente querrás agregar metadatos PDF al archivo de salida.

Continúe leyendo para saber cómo indicarle al generador que cifre archivos PDF. Cómo especificar el autor del documento y las palabras clave.

Este artículo es parte de una serie sobre la API Layout para la generación de PDF. Si es nuevo en la API, lea primero la parte Introducción a la API de Layout.

Create & Generate

El punto de entrada de Layout API es la clase PdfDocumentBuilder. Comienza creando una instancia de la clase con el método Create. Para generar un PDF, llama al método Generate de la clase.

Generate puede guardar la salida en un archivo o secuencia. Cualquiera de las versiones del método requiere un delegado de tipo Action<Document> como segundo parámetro. En el delegado, describe el documento que desea obtener. La biblioteca generará un PDF basado en la descripción.

Cifrada

Para cifrar el PDF de salida, llame al método Encryption antes del método Generate.

Debería crear y proporcionar un controlador de cifrado. Para cifrar PDF con contraseñas, utilice un controlador de tipo PdfStandardEncryptionHandler.

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

También puede cifrar PDF con certificados. Consulte el artículo Cifrar documentos PDF. Contiene información detallada sobre controladores de cifrado y permisos de PDF.

Metadatos del archivo PDF

En algunos flujos de trabajo, es muy importante especificar las palabras clave de PDF y el autor del PDF adecuados en el PDF de salida. Layout API proporciona una forma sencilla de hacerlo. Llame al método Info antes del método Generate y proporcione los valores de metadatos en el delegado.

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

Opciones

Para el mismo contenido, la biblioteca puede crear archivos PDF con diferente estructura interna. Estas opciones afectarán el PDF de salida.

Versión

Utilice el método Version para establecer la versión mínima del formato PDF para el PDF de salida.

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

Tenga en cuenta que la biblioteca puede crear un PDF con una versión más grande que la especificada. Ocurre cuando el contenido del documento requiere una versión más reciente. Para decirlo de otra manera: cuando el documento utiliza funciones no disponibles en la versión especificada del estándar PDF.

Flujos de objetos

De forma predeterminada, la biblioteca utiliza flujos de objetos en los archivos PDF generados. Esto ayuda a producir archivos más pequeños y mejor comprimidos.

Puede indicarle a la API que cree archivos PDF sin secuencias de objetos utilizando el método ObjectStreams.

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

Le sugiero que siga utilizando flujos de objetos a menos que existan algunos requisitos reglamentarios. O cuando otras partes de su flujo de trabajo no pueden procesar documentos con flujos de objetos.

Proveedor de flujo

La biblioteca utiliza transmisiones como almacenamiento intermedio. Al generar un PDF, lo hace para imágenes y otros objetos de gran tamaño. La biblioteca obtiene transmisiones a través del proveedor de transmisiones. Siempre hay uno asociado con la instancia actual de PdfDocumentBuilder.

La biblioteca utiliza PdfMixedStorageStreamProvider de forma predeterminada. Esta implementación del proveedor de flujo proporciona flujos que mantienen los datos en la memoria. Estas transmisiones descargan su contenido en archivos temporales cuando hay demasiados datos. Esto permite reducir el consumo de memoria y evitar la fragmentación de LOH.

Puede utilizar su propia implementación de la interfaz IPdfStreamProvider al generar archivos PDF. Una razón para el cambio podría ser que las operaciones del disco sean lentas y/o costosas. Los entornos de nube podrían encajar en esta descripción.

Este código muestra cómo generar PDF completamente en la memoria, sin archivos temporales. Tenga en cuenta que esto requerirá mucha más memoria que con las opciones predeterminadas.

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

La biblioteca finalmente llama a Dispose para cada transmisión que recibe a través del proveedor de transmisión. Deben deshacerse de la instancia del proveedor de transmisión ustedes mismos.