Share via

Handling Data Connector Events

  • Article

All CRUD-related operations on data result in change events. To receive events, the tool developer registers an event callback function and registers the table name for which events are requested. Subscription to data change events provides events for both DataRow updates and attachment updates.

The Add-in API provides data events that send you notification when the underlying add-in tool data changes. The dataset that your add-in accesses is a copy of the underlying tool data and does not have a direct connection to the underlying data. Consequently, if the underlying data changes, your add-in's dataset may not match the underlying data. Your add-in can use the data events to update the dataset or refresh it with a new copy.

To obtain data events, your add-in must subscribe to them. Once your add-in has subscribed to events, it receives events under the following circumstances:

  1. Your add-in has updated the dataset and then committed the changes.

  2. Another instance of the add-in has updated the dataset and committed the changes. For example, if another workspace member updates the add-in tool data, SharePoint Workspace sends the data directly to your add-in tool’s underlying data. In this case, your dataset does not have these data changes and does not match the underlying data. In this case, your add-in has to either merge the data events into the dataset or refresh the whole dataset.

In most cases, refreshing the whole dataset is less efficient than merging the data events into the dataset. Consequently, to maximize your add-in’s performance you should merge data events instead of refreshing the whole dataset. However, merging data events into the dataset is a more complex development task. Developing an add-in tool that merges data events into the dataset requires significantly more development, testing, and debugging resources than developing an add-in tool that updates the whole dataset.

The add-in tool data events are asynchronous events: that is, the events are not part of the transaction updating the underlying data and the underlying data is not locked while you are processing the events. Asynchronous events have advantages in that the underlying data can be updated more reliably and efficiently. But asynchronous events also have disadvantages. One disadvantage of asynchronous events is that the underlying data may have had later updates before you have finished processing an event. Another disadvantage of asynchronous events is that they are not guaranteed. In most cases, your add-in is notified of all changes in the underlying data when you have an event subscription. But there are rare cases when your add-in is not notified. There are some cases when it is more likely that your add-in will not receive events. For example, if your add-in or another instance of your add-in creates a record, updates it, and then immediately deletes the record, the events can be lost. But, although it is very unlikely, any event may be lost.

The add-in tool events contain the updated data. Although your add-in code can examine the contents of the event, typically, add-in code merges the update into a DataSet using the MergeChangedData .NET extension method, without examining the contents of the event.

Note

If your add-in receives a data change event and is about to merge the updates into the DataSet, the merge fails if any of the DataRows being updated by the event have unsaved changes. In this case, your add-in must first temporarily remove any unsaved updates before merging the data change event.

Note

If an instance of an add-in has updated the underlying data and receives an event for that update, the event's ChangeSource property indicates that the event is local and you do not have to merge the changes into the DataSet. But if the user is running two instances of the same add-in by opening the add-in tool within the workspace and in a separate window, changes from one instance will be marked as local to the other instance. In this case, you have to merge these changes into the DataSet. Because there is no effect if you merge in changes to a DataSet that are already present in the DataSet, you should always merge changes, even if the source is local.

The following APIs provide support for event subscriptions:

See the AttachmentsAndConflicts sample provided with the SDK for an example of handling events.

Note

If an attachment larger than 16 kilobytes is created or updated by another workspace member, you will typically receive two data events for this data change.