Introduction to Add-in Tools
In this article
Kind of Workspace for Add-in Tools
Add-in Tool Data
Add-in Tool User Interface
Add-in Tool Environment
Add-in Tool Deployment
The SharePoint Workspace Add-in API enables you to develop add-in tools for Groove workspaces. After an add-in tool is installed on a system, users can add it to a workspace like they can add a built-in tool, such as the Files tool or a Discussion tool.
This overview describes the following:
Workspaces for add-in tools
Add-in tool data and how to access it
Add-in tool user interface
Add-in tool run-time environment
Deploying an add-in tool
Kind of Workspace for Add-in Tools
The SharePoint Workspace Tool Add-in API enables you to define an add-in tool that can be used in a workspace shared with other users. SharePoint Workspace 2010 has three kinds of workspaces:
SharePoint workspaces that provide a rich client and offline access to a SharePoint site.
Groove workspaces that let you collaborate with other users independently of a SharePoint site.
File Sharing workspaces, which are a specialized form of Groove workspaces that let you share folders together with other users.
The add-in tools can only be used in the second kind of workspaces, Groove workspaces. In addition, they can only be used in 2010 workspaces and cannot be used in workspaces compatible with Groove 2007.
Add-in Tool Data
The SharePoint Workspace SDK lets you define schemas for the data that is stored in the tool and to develop the tool user interface in a Windows Form and Office Ribbon. The tool data is accessed through a .NET dataset. The ISPWDataConnector interface provides methods for you to populate a dataset with the tool’s data. The ISPWDataConnector interface also provides a method that updates the underlying tool data based on any data changes that your application has made to the dataset.
The tool data schema is defined by a manifest, which is an XML file. The manifest includes one or more definitions of the following entities:
Table—defines a set of columns, with names and types, that defines the schema for a record.
View—defines a set of records from a table. A view can also specify one or more of the following:
A subset of the columns
A subset of the records based on a where clause
A sort order
Set—specifies a collection of views, which specifies a dataset that can be used to access the tool data.
Index—improves efficiency of queries.
The ISPWDataConnector interface does not automatically update the dataset when the underlying data is changed. That is, the dataset is a copy of the underlying data made at the time that the dataset is first populated or refreshed.
At the time that the dataset is populated, it is an accurate representation of the underlying data. However, the dataset and the underlying data can diverge because of two reasons:
If your application updates the dataset, but has not yet called the Update method, the changes in the dataset have not yet been applied to the underlying data.
If another workspace member updates the tool data, this update is replicated to your instance of the tool. If you populated your dataset before the update was replicated then the updates are in the underlying data but are not in your add-in's dataset.
The Add-in Tool API provides events that notify you that the underlying data has changed. You can use the information in these events to update the dataset so that it is an accurate representation of the current state of the underlying data.
Each data record in the underlying data stores the following:
Columns defined in the table definition in the manifest
System columns that are common to all tables
Optionally, a collection of named attachments
Although the attachment metadata is read at the same time as the column data, a separate mechanism is provided to access the attachment contents. This mechanism makes is possible to efficiently read records including the attachment metadata, but access only the attachment contents that are needed by the user. If the attachment contents were read when the tool's data was read, it would be very inefficient to access records with large attachments.
The schema is defined by the XML file when the add-in tool is first added to a workspace. Although you can update the tool code that operates on the data, you cannot modify the schema after the tool is created.
Add-in Tool User Interface
Your add-in tool has complete control of a Windows UserControl hosted by the workspace and it has complete access to the Office Ribbon. Typically, tools use a Windows Form as the UserControl to display and give access to the data, and tools create a Home tab on the ribbon to provide controls that let the user perform operations on the data.
Add-in Tool Environment
The Add-In API provides access to the add-in tool’s workspace environment. The tool has read access to the following:
Contact information for the local user running the tool
Contact information for all members in the workspace
Tool display name
Workspace display name
Add-in Tool Deployment
A user typically deploys an add-in tool by running an installer on the system. The add-in tool developer builds the installer. All workspace members must run the installer before they can add the tool to a workspace or access the tool data and user interface in a workspace that contains the add-in tool. If a user accepts an invitation to a workspace that contains an add-in tool and has not run the installer, the tool displays a message that states that the tool is not installed. The user can obtain information about the missing tool by right-clicking the tool name and selecting Properties.
In the SDK, the Visual Studio project template generates a registry file that defines the following:
GUID to identify the assembly
Display name of the add-in tool
Installed location of the add-in tool DLLs and the tool manifest
File name of the tool manifest
Add-in version number
To install an add-in tool on a system, the user executes a registry file or an installer that defines keys in the registry for the items in the previous list. By default, the Visual Studio project template creates the registry file specifying the manifest file spwaddin.xml in the following location:
c:\Your_Install_Location\project-name\
If the tool DLLs and manifest are installed in a different location, you must update the registry file to reflect the correct location before the user executes it. This manual installation process can be replaced by an installer. However, the SDK does not provide an example of creating an installer.