Associate files with PDF objects in C# and VB.NET

Associated files is a PDF 2.0 concept that provides a means to associate content in other formats with selected objects of a PDF document and identify the relationship between them.

Such associated files are usually also contained in the PDF document's embedded files so that users can easily extract them as any other attachment.

You can represent associated files in GemBox.Pdf with the PdfAssociatedFileCollection class. It’s possible to access and manipulate them via the AssociatedFiles property of the PdfDocument, PdfPage, PdfContentMark, PdfExternalObject, and PdfAnnotation classes.

GemBox.Pdf supports associating files with PDF document objects from either a file system or Streams and using various relationship types in C# and VB.NET, as shown in the following example.

PDF associated files created with GemBox.Pdf
Screenshot of PDF associated files created with GemBox.Pdf
using System.IO;
using GemBox.Pdf;
using GemBox.Pdf.Content;
using GemBox.Pdf.Content.Marked;

class Program
{
    static void Main()
    {
        // If using the Professional version, put your serial key below.
        ComponentInfo.SetLicense("FREE-LIMITED-KEY");

        using (var document = new PdfDocument())
        {
            // Make Attachments panel visible.
            document.PageMode = PdfPageMode.UseAttachments;

            using (var sourceDocument = PdfDocument.Load("%#Invoice.pdf%"))
            {
                // Import the first page of an 'Invoice.pdf' document.
                var page = document.Pages.AddClone(sourceDocument.Pages[0]);

                // Associate the 'Invoice.docx' file to the imported page as a source file and also add it to the document's embedded files.
                page.AssociatedFiles.Add(PdfAssociatedFileRelationshipType.Source, "%#Invoice.docx%", null, document.EmbeddedFiles);
            }

            using (var sourceDocument = PdfDocument.Load("%#Chart.pdf%"))
            {
                // Import the first page of a 'Chart.pdf' document.
                var page = document.Pages.AddClone(sourceDocument.Pages[0]);

                // Group the content of an imported page and mark it with the 'AF' tag.
                var chartContentGroup = page.Content.Elements.Group(page.Content.Elements.First, page.Content.Elements.Last);
                var markStart = chartContentGroup.Elements.AddMarkStart(new PdfContentMarkTag(PdfContentMarkTagRole.AF), chartContentGroup.Elements.First);
                chartContentGroup.Elements.AddMarkEnd();

                // Associate the 'Chart.xlsx' to the marked content as a source file and also add it to the document's embedded files.
                // The 'Chart.xlsx' file is associated without using a file system utility code.
                var embeddedFile = markStart.AssociatedFiles.AddEmpty(PdfAssociatedFileRelationshipType.Source, "Chart.xlsx", null, document.EmbeddedFiles).EmbeddedFile;
                // Associated file must specify modification date.
                embeddedFile.ModificationDate = File.GetLastWriteTime("Chart.xlsx");
                // Associated file stream is not compressed since the source file, 'Chart.xlsx', is already compressed.
                using (var fileStream = File.OpenRead("%#Chart.xlsx%"))
                using (var embeddedFileStream = embeddedFile.OpenWrite(compress: false))
                    fileStream.CopyTo(embeddedFileStream);

                // Associate another file, the 'ChartData.csv', to the marked content as a data file and also add it to the document's embedded files.
                markStart.AssociatedFiles.Add(PdfAssociatedFileRelationshipType.Data, "%#ChartData.csv%", null, document.EmbeddedFiles);
            }

            using (var sourceDocument = PdfDocument.Load("%#Equation.pdf%"))
            {
                // Import the first page of an 'Equation.pdf' document into a form (PDF equivalent of a vector image).
                PdfForm form = sourceDocument.Pages[0].ConvertToForm(document);

                var page = document.Pages[1];

                // Add the imported form to the bottom-left corner of the second page.
                page.Content.Elements.AddForm(form);

                // Associate the 'Equation.mml' to the imported form as a supplement file and also add it to the document's embedded files.
                // Associated file must specify media type and since GemBox.Pdf doesn't have built-in support for '.mml' file extension,
                // the media type 'application/mathml+xml' is specified explicitly.
                form.AssociatedFiles.Add(PdfAssociatedFileRelationshipType.Supplement, "%#Equation.mml%", "application/mathml+xml", document.EmbeddedFiles);
            }

            document.Save("Associated Files.pdf");
        }
    }
}
Imports System.IO
Imports GemBox.Pdf
Imports GemBox.Pdf.Content
Imports GemBox.Pdf.Content.Marked

Module Program

    Sub Main()

        ' If using the Professional version, put your serial key below.
        ComponentInfo.SetLicense("FREE-LIMITED-KEY")

        Using document = New PdfDocument()

            ' Make Attachments panel visible.
            document.PageMode = PdfPageMode.UseAttachments

            Using sourceDocument = PdfDocument.Load("%#Invoice.pdf%")

                ' Import the first page of an 'Invoice.pdf' document.
                Dim page = document.Pages.AddClone(sourceDocument.Pages(0))

                ' Associate the 'Invoice.docx' file to the imported page as a source file and also add it to the document's embedded files.
                page.AssociatedFiles.Add(PdfAssociatedFileRelationshipType.Source, "%#Invoice.docx%", Nothing, document.EmbeddedFiles)
            End Using

            Using sourceDocument = PdfDocument.Load("%#Chart.pdf%")

                ' Import the first page of a 'Chart.pdf' document.
                Dim page = document.Pages.AddClone(sourceDocument.Pages(0))

                ' Group the content of an imported page and mark it with the 'AF' tag.
                Dim chartContentGroup = page.Content.Elements.Group(page.Content.Elements.First, page.Content.Elements.Last)
                Dim markStart = chartContentGroup.Elements.AddMarkStart(New PdfContentMarkTag(PdfContentMarkTagRole.AF), chartContentGroup.Elements.First)
                chartContentGroup.Elements.AddMarkEnd()

                ' Associate the 'Chart.xlsx' to the marked content as a source file and also add it to the document's embedded files.
                ' The 'Chart.xlsx' file is associated without using a file system utility code.
                Dim embeddedFile = markStart.AssociatedFiles.AddEmpty(PdfAssociatedFileRelationshipType.Source, "Chart.xlsx", Nothing, document.EmbeddedFiles).EmbeddedFile
                ' Associated file must specify modification date.
                embeddedFile.ModificationDate = File.GetLastWriteTime("Chart.xlsx")
                ' Associated file stream is not compressed since the source file, 'Chart.xlsx', is already compressed.
                Using fileStream = File.OpenRead("%#Chart.xlsx%")
                    Using embeddedFileStream = embeddedFile.OpenWrite(compress:=False)
                        fileStream.CopyTo(embeddedFileStream)
                    End Using
                End Using

                ' Associate another file, the 'ChartData.csv', to the marked content as a data file and also add it to the document's embedded files.
                markStart.AssociatedFiles.Add(PdfAssociatedFileRelationshipType.Data, "%#ChartData.csv%", Nothing, document.EmbeddedFiles)
            End Using

            Using sourceDocument = PdfDocument.Load("%#Equation.pdf%")

                ' Import the first page of an 'Equation.pdf' document into a form (PDF equivalent of a vector image).
                Dim form As PdfForm = sourceDocument.Pages(0).ConvertToForm(document)
                Dim page = document.Pages(1)

                ' Add the imported form to the bottom-left corner of the second page.
                page.Content.Elements.AddForm(form)

                ' Associate the 'Equation.mml' to the imported form as a supplement file and also add it to the document's embedded files.
                ' Associated file must specify media type and since GemBox.Pdf doesn't have built-in support for '.mml' file extension,
                ' the media type 'application/mathml+xml' is specified explicitly.
                form.AssociatedFiles.Add(PdfAssociatedFileRelationshipType.Supplement, "%#Equation.mml%", "application/mathml+xml", document.EmbeddedFiles)
            End Using

            document.Save("Associated Files.pdf")
        End Using
    End Sub
End Module

Want more?

Next example GitHub

Check the next example or select an example from the menu. You can also download our examples from the GitHub.


Like it?

Download Buy

If you want to try the GemBox.Pdf yourself, you can download the free version. It delivers the same performance and set of features as the professional version, but with some operations limited. To remove the limitation, you need to purchase a license.