Accessing Attachments
In this article
Overview of Accessing Attachments
Operations on Attachments
Accessing the Attachment Contents
Attachment Synchronization
This section describes how to access attachments.
Overview of Accessing Attachments
When a dataset is returned by the ISPWDataConnectorFill method or the Query method, apart from the data tables, the dataset also contains an attachment table that contains the attachment metadata. The internal name for the attachment table is "_Attachments". This table is the last data table in the dataset. In most cases, your add-in code can ignore this table and access the attachments using the Attachment object and the DataRow extension methods in SPWDAExtensions.
If you decide to explicitly use the _Attachments table, be aware that there is no implicit relationship between the data tables and the attachment table. But you can create in your add-in code a parent-child one-to-many relationship that uses the _RecordID field in the data table and the _ParentID field in the attachment table. This relationship will enable associating data records to one or many attachments in your add-in code, but is not used when updating the underlying data.
To improve the performance of accessing add-in tool data, the API does not automatically load the contents of each attachment when you call the Fill method or the Query method. Instead you must explicitly request the contents of an attachment by calling the GetStream method.
Note
It is possible for two attachments on a single record to have the same name.
Operations on Attachments
The following are the supported operations for attachments. These methods are available through .NET extension methods exposed on the DataRow. These operations provide Create, Read, Update, and Delete (CRUD) functionality.
During the CRUD operations AddAttachment and ReplaceAttachment, you should not dispose of the stream until the dataset is committed to the tool's underlying data with the Update method.
Although there is no method that you can use to launch an attachment, you can provide that capability in your add-in code. See the AttachmentsAndConflicts sample in the SDK for an example of launching an attachment.
Accessing the Attachment Contents
You can get the contents of the attachment by calling the GetStream method. You can replace the contents of an existing attachment by using the ReplaceAttachment method. You can create a new attachment by using the AddAttachment method.
Note
It is not necessary to get the current contents of an attachment by using GetStream before replacing the contents by using ReplaceAttachment or renaming an attachment by using RenameAttachment.
Attachment Synchronization
If a record with one or more large attachments is created or updated by another member of the workspace, there may be an interval of time when your instance of the workspace has received the updated record including the attachment metadata, but has not yet received the contents of the attachments. The content of an attachment can be in any of the following states:
SPWContentState.Current—contents present
SPWContentState.None—contents missing
SPWContentState.Old—obsolete contents present
If the attachment has obsolete contents present, it means that another workspace member has updated the attachment contents. Your instance of the workspace has received the updated record but has not yet received the updated contents. Your add-in should treat the attachment contents as stale data and wait until it receives the updated contents.
Your add-in can test the ContentState attachment property to determine the state of the application contents or can use events to be notified when the state of the attachment contents changes.
In a workspace involving multiple endpoints, attachment synchronization can result in multiple scenarios. The _ContentState system field provides the current state of the attachment. In a workspace that has user1 and user2 as members, the following attachment related scenarios are possible:
User1 adds a new attachment: synchronization happens in two steps, with metadata becoming synchronized first, followed by the attachment content.
User2 gets the attachment metadata row with the ContentState field set to "none".
On attachment synchronization, ContentState is set to "current" for User2.
User1 edits an existing attachment.
User2 gets the updated attachment metadata row and the ContentState field is set to "Old".
On attachment synchronization, ContentState is set to "current".