Add-in Tool Object Model

  • Article

The Add-in API is a fairly simple set of interfaces and XML files. This section describes the Add-in tool's conceptual object model. Once you understand the object model, you will be able to understand how the interfaces and classes fit together. This section starts with a simplified object model, which describes the minimum elements of an add-in. The following sections describe a more detailed conceptual object model.

Simplified Add-in Conceptual Object Model

This section describes what you have to do to develop a very simple add-in tool. Creating a Visual Studio project from the "SharePoint Workspace 2010 Add-In" template creates all of the elements of this simple add-in tool. By creating a project from the template, you have done the following:

  • Defined registry keys that identify the add-in.

  • Defined a manifest that specifies the structure of your data.

  • Implemented the ISPWManagedToolAddin inteface and the ISPWManagedToolAddinUI interface.

  • Implemented a user interface including the Office Ribbon.

In the ISPWManagedToolAddin implementation, you have put code in one method, OnToolStart. In the ISPWManagedToolAddinUI interface, all methods are optional. The API provides other API objects to you through the arguments it passes to your implementation of OnToolStart.

The logic flow of your add-in is also simple. The logic flow is in the OnToolStart(ISPWTool, ISPWToolUI) method and in your user interface code. Your implementation of the OnToolStart(ISPWTool, ISPWToolUI) method does the following:

  1. Gets the ISPWTool and ISPWToolUI objects from the method parameters.

  2. Gets the SPWDataConnector object from ISPWTool. The SPWDataConnector object provides access to the tool's data.

  3. Uses the SPWDataConnector object to get the tool data to display when the user first views the tool. Typically, it calls the Fill method or the Query(String) method to transfer some or all of the tool's underlying data to a DataSet. It can then initialize the form in its user interface to display the data. It can display the data in a grid or any other form control.

  4. Calls the ISPWToolUIShow method to display the form to the user.

  5. At this point, the user and the user interface events determine the operations that the add-in performs. Typically, the user:

    1. Requests specific data to be displayed. In this case, the user interface calls the Query(String) method to get the requested data and then displays it to the user.

    2. Updates the data in a form and then requests that the data be saved. In this case, the user interface updates the data in the DataSet and calls the Update(DataSet) method. This method applies the changes in the DataSet to the underlying data.

    3. Exits the application.

You can develop a more complex add-in, which supports file attachments and conflicts. However, the basic structure of the add-in remains the same. The following sections describe the objects that you can use in an add-in and describes the add-in structure in more detail.

Defining Data Structures in the Manifest

The manifest is identified in the add-in's registry keys and defines the data structures for the add-in. The XML structure of the manifest is declared in Groove\XMLFiles\spwaddin.xsd file in the SharePoint Workspace install folder. The manifest defines the following structures for the add-in.

  • Properties that define the overall metadata for the tool.

  • Schema that defines the data structure for the underlying data and the DataSets that are available to the add-in. The following data structures are defined in the manifest:

    • Tables—define the tables in the underlying data storage and the tables in the dataset. Each DataRow in the table has the following:

      • Columns defined in the manifest consisting of a name and type. Optionally, you can enable conflicts (see following section) for a specific column.

      • System columns defined by the API.

      • A collection of attachments. Each attachment has a name that consists of a file name and file type, metadata, and contents.

    • Views—define a logical view of the data. Each table in the view can be restricted to a subset of columns or to a subset of records with a Where clause. In addition, the table can be sorted with an OrderBy clause. Sorting a table in a view creates an index in the table in the underlying data.

    • Sets—define a collection of Views that are in the DataSet.

    • Indexes—identifies columns in tables that should be indexed in the underlying data. Specifying a sort in a view creates an index on the underlying table. But you can also explicitly create an index to improve efficiency in queries on large tables.

In addition to defining the elements in the manifest, spwaddin.xsd defines the Query element. The Query element is used at run-time, but is not used in the manifest.

Detailed Object Model with Attachments, Events, and Conflicts

The following figure is a containment diagram for the Add-in API. The containment diagram shows how you get one object from another.

Add-in API object containment diagram

Add-in API object containment diagram

The containment diagram shows that all Add-in API objects can be accessed from the ISPWTool object that is provided in the parameter to your OnToolStart method. Once you have implemented the ISPWManagedToolAddin inteface and the ISPWManagedToolAddinUI interface, you do not have to implement or create another of the Add-in API objects. The API creates the objects and returns them to you.

The ISPWTool object provides access to the following objects:

The ISPWApplication object provides access to an ISPWContact object that describes the current contact. The ISPWWorkspace object provides access to an enumeration of ISPWMember objects that describe the members of the workspace, which include the current contact. The ISPWMember interface inherits from the ISPWContact interface.

All other add-in objects are available through the SPWDataConnector object.

The following methods in the SPWDataConnector object provide a DataSet that supports the Add-in API extensions:

For many purposes, you can treat this DataSet as a typical .NET DataSet. However, you can also use the Add-in API extensions on this DataSet and on its DataRows.

The DataSet has one extension method, MergeChangedData(DataSet, SPWDataChangeEventArgs). This method merges the changes in the SPWDataChangeEventArgs object together with the DataSet. The SPWDataChangeEventArgs object is provided by the SPWDataConnector object through an event handler method.

The DataRow has extension methods to handle attachments and conflicts.

The following DataRow extension methods provide an Attachment object:

  • AddAttachment method adds a new attachment to a DataRow and returns the attachment. The attachment is created from the specified stream.

  • GetAttachment method returns the attachment that has the specified name from the DataRow.

  • GetAttachments method returns all attachments from the DataRow.

The Attachment object has the attachment metadata but does not contain the attachment contents. The Add-in API stores the attachment contents separately from the DataSet to improve performance. The Attachment.GetStream method provides the attachment contents as a Stream.

The last two items in the Add-in API object containment diagram are not new objects, but conflict objects that you obtain from DataRow and Attachment. The DataRow has a GetConflicts extension method that returns conflict DataRows and the Attachment object has a GetConflicts method that returns conflict Attachment objects. See Resolving Conflicts for more information about conflicts.