Attachments
Attachments
This page covers embedding files inside a PDF. There are two distinct mechanisms: document-level attachments, which are embedded files with no visible presence on any page, and page-anchored file attachment annotations, which place a clickable icon on a specific page.
Document-Level Attachments
Document.AddAttachment() embeds bytes under a name, upserting it into
the document’s embedded-file name tree — adding it again with the same name
overwrites the existing entry. It returns an Attachment handle.
Document.GetAttachments() returns every document-level attachment as an
array of Attachment handles, sorted by name, and
Document.RemoveAttachment() removes one by name.
The Attachment handle exposes Name, Description, MimeType, Size,
CreationDate, and ModDate as properties, GetBytes() to read the
embedded file’s raw content back out, and GetField() / SetField() /
RemoveField() for lower-level access to individual /Filespec fields. The
optional AttachmentOptions passed to AddAttachment() accepts
mimeType, description, compress, creationDate, and modDate.
No verified code example is available for this API in the current knowledge snapshot for this platform — see the API Reference Summary below for the exact method and property names.
Page-Anchored File Attachments
Page.AddFileAttachment() embeds a file and places a /FileAttachment icon
annotation at a given rect on a specific page, returning a
FileAttachmentAnnotation. Unlike a document-level attachment, this one is
visible and clickable in a PDF viewer. FileAttachmentAnnotation shares the
common annotation properties (Rect, Color, Contents, Name, Flags,
Print, Hidden, Opacity) plus its own Icon and FileName, and
supports GetBytes() to read the embedded content and Flatten() to bake
its icon into static page content.
Tips and Best Practices
- Use a document-level attachment (
Document.AddAttachment()) for a file that should travel with the PDF without appearing on any page; usePage.AddFileAttachment()when the file should be represented by a clickable icon at a specific location. Document.AddAttachment()overwrites an existing attachment with the samename— checkDocument.GetAttachments()first if you need to avoid replacing one unintentionally.- Read an attachment’s content back with
GetBytes()on either handle type — the method exists on bothAttachmentandFileAttachmentAnnotation.
Common Issues
| Issue | Cause | Fix |
|---|---|---|
| A newly added attachment replaced an existing one | Document.AddAttachment() was called with a name already in use | Call Document.GetAttachments() first to check for a name collision |
| Attachment has no visible icon on the page | Document.AddAttachment() was used, which is document-level and has no page presence by design | Use Page.AddFileAttachment() instead for a visible, page-anchored icon |
Document.RemoveAttachment() returns false | No attachment with the given name exists in the name tree | Confirm the exact name via Document.GetAttachments() before removing |
FAQ
What is the difference between Document.AddAttachment and Page.AddFileAttachment?
Document.AddAttachment() embeds a file at the document level with no
visible icon on any page. Page.AddFileAttachment() embeds a file and
places a clickable /FileAttachment icon annotation at a specific location
on one page.
How do I list every attachment already embedded in a document?
Call Document.GetAttachments(), which returns every document-level
attachment as an array of Attachment handles sorted by name.
How do I read an attachment’s file content back out?
Call GetBytes() on the Attachment (or FileAttachmentAnnotation)
handle — it is available on both.
Can I remove an attachment?
Yes — Document.RemoveAttachment(name) removes a document-level
attachment by name and returns whether one was found and removed.
API Reference Summary
| Class/Method | Description |
|---|---|
Document.AddAttachment() | Embed bytes as a named, document-level attachment |
Document.GetAttachments() | List every document-level attachment |
Document.RemoveAttachment() | Remove a document-level attachment by name |
Attachment | Handle over one embedded file; Name, Description, MimeType, Size, GetBytes() |
Page.AddFileAttachment() | Embed a file as a page-anchored, clickable icon annotation |
FileAttachmentAnnotation | The page-anchored attachment’s annotation handle; adds Icon, FileName |