Defining the Tool and Data Structure in the Manifest

  • Article

In this article
Editing the Manifest in Visual Studio
Overview of the Manifest
Defining Properties
Defining the Schema
Defining Tables in the Schema
Defining Views in the Schema
Defining Sets in the Schema
Defining Indexes in the Schema

You define the tool metadata and the data schema in a manifest XML file. By default, the manifest is named spwaddin.xml. But you can override this file name in the registry file.

Editing the Manifest in Visual Studio

To use the Visual Studio IntelliSense feature, you must add the .xsd that defines the manifest schema to the Visual Studio XML Schema list. To do this, follow these steps:

  1. Open the spwaddin.xml file that defines the manifest in one of the samples or in your own add-in project.

  2. In the Visual Studio XML->Schemas menu, specify the following folder and file name if you have installed SharePoint Workspace in the default location:

    C:\Program Files\Microsoft Office\Office14\Groove\XML Files\spwaddin.xsd

    or

    C:\Program Files (x86)\Microsoft Office\Office14\Groove\XML Files\spwaddin.xsd

Once you have added the schema to the list in one project, IntelliSense should work in all SharePoint Workspace add-in projects.

Overview of the Manifest

The manifest contains properties that describe the tool and the definitions of tables, views, sets, and indexes that represent your data.

When you create a new SharePoint Workspace 2010 Add-In project in Visual Studio, it creates the following manifest in your project:

<?xml version="1.0" encoding="utf-8"?>
<SPWAddin xmlns="https://schemas.microsoft.com/spw/">
  <Properties>
    <GUID>{08556b55-564a-467c-bb28-95f577d29d4b}</GUID>
    <DisplayName>SPWAddin1</DisplayName>
    <Version>1.0</Version>
    <Description></Description>
    <Website>http://www.example.com</Website>
    <Contact>user@example.com</Contact>
    <PrimaryAssemblyName>SPWAddin1.dll</PrimaryAssemblyName>
    <PrimaryAssemblyEntryClass>SPWAddin1.AddIn</PrimaryAssemblyEntryClass>
    <Author>add-in developer</Author>
    <HelpAbout>Information about add-in</HelpAbout>
    <ReleaseDate>May 30, 2010</ReleaseDate>

  </Properties>
  <Schema>
    <Tables>
      <Table Name="Table1">
        <Columns>
          <Column Name="Column1" Type="Int" />
          <Column Name="Column2" Type="String" />
        </Columns>
      </Table>

    </Tables>
    <Views>
      <View Name="Table1View" TableRef="Table1">
        <ColumnRefs>
          <ColumnRef Name="Column1" />
          <ColumnRef Name="Column2" />
        </ColumnRefs>
      </View>
    </Views>
    <Sets>
      <Set Name="SPWAddin1DataSet1">
        <ViewRefs>
          <ViewRef Name="Table1View" />
        </ViewRefs>
      </Set>
    </Sets>
  </Schema>
</SPWAddin>

The following sections describe the parts of the manifest.

Defining Properties

The first section, Properties, is used to define various attributes that describe your add-in:

  • GUID—globally unique identifier for your add-in.

  • DisplayName—name displayed in the Add Tool list, and the Workspace Tool list.

  • Version—this field is not used in this release. The add-in tool version is determined by the registry settings.

  • Description—description in the tool properties. The description should provide a brief overview of the tool and guidance on how to obtain an installer. If a user accepts an invitation to a workspace that contains an add-in tool and they have not installed it on their system, the user can display this information by right-clicking the tool and selecting Properties.

  • Website—this field is not used in this release.

  • Contact—this field is not used in this release.

  • PrimaryAssemblyName—file name of the primary assembly that should be loaded, relative to the ManifestPath value in the registry.

  • PrimaryAssemblyEntryClass—the name of the class inside the primary assembly that implements the required Tool interfaces.

  • Author—name of the tool developer. This is displayed in the tool properties.

  • HelpAbout—information about the tool. This is displayed in the tool properties.

  • ReleaseDate—date the add-in was released. This is displayed in the tool properties.

Defining the Schema

The Schema definition has the following parts:

  1. Tables—a table defines the user columns in a record schema. This schema is used to determine the columns stored in the underlying data storage for a table and provides the columns that can be selected in a view.

  2. Views—a view represents a logical subset of a table. A view can contain all or a subset of the records in a table and it can contain all or a subset of the columns in a table.

  3. Sets—a set is a collection of views.

  4. Indexes—specify that a table will have an index on the specified column. Indexes can improve the efficiency of queries and ordering.

Defining Tables in the Schema

After you create a new project from the template, the Tables section is as follows:

    <Tables>
      <Table Name="Table1">
        <Columns>
          <Column Name="Column1" Type="Int" />
          <Column Name="Column2" Type="String" />
        </Columns>
      </Table>

    </Tables>

This defines one table, Table1, which has two columns: Column1, which is of type Int, and Column2, which is of type String. You can define as many tables as needed, each with as many columns as needed.

Column and table names cannot begin with or contain underscore (_) or hyphen (-), as these are reserved for internal system columns.

The supported column types are as follows:

  • String (System.String in .NET)

  • Double (System.Double in .NET)

  • Bool (System.Boolean in .NET)

  • Int (System.Int32 in .NET)

  • DateTime (System.DateTime in .NET)

Defining Views in the Schema

After you create a new project from the template, the Views section is as follows:

    <Views>
      <View Name="Table1View" TableRef="Table1">
        <ColumnRefs>
          <ColumnRef Name="Column1" />
          <ColumnRef Name="Column2" />
        </ColumnRefs>
      </View>
    </Views>

This defines one view, Table1View, which references Table1. The view contains all columns from Table1: Column1 and Column2.

A View can also contain a Where clause. For example, if you wanted to add a Where clause that limits this view to rows where Column1 is greater than 5, you could change it to the following:

      <View Name="Table1View" TableRef="Table1">
        <ColumnRefs>
          <ColumnRef Name="Column1" />
          <ColumnRef Name="Column2" />
        </ColumnRefs>
        <Where>
          <Gt>
            <ColumnRef Name="Column1" />
            <Value>5</Value>
          </Gt>
        </Where>
      </View>

Where clauses also support operator grouping. Therefore, you could do the following to limit the view to rows where Column1 is greater than 5 or Column2 begins with the letter A:

      <View Name="Table1View" TableRef="Table1">
        <ColumnRefs>
          <ColumnRef Name="Column1" />
          <ColumnRef Name="Column2" />
        </ColumnRefs>
        <Where>
          <Or>
            <Gt>
              <ColumnRef Name="Column1" />
              <Value>5</Value>
            </Gt>
            <BeginsWith>
              <ColumnRef Name="Column2" />
              <Value>A</Value>
            </BeginsWith>
          </Or>
        </Where>
      </View>

You can also nest grouping operators so that you could do the following to limit the view to rows where Column1 is greater than 5 and less than 10 or Column2 begins with the letter A:

      <View Name="Table1View" TableRef="Table1">
        <ColumnRefs>
          <ColumnRef Name="Column1" />
          <ColumnRef Name="Column2" />
        </ColumnRefs>
        <Where>
          <Or>
            <And>
              <Gt>
                <ColumnRef Name="Column1" />
                <Value>5</Value>
              </Gt>
              <Lt>
                <ColumnRef Name="Column1" />
                <Value>10</Value>
              </Lt>
            </And>
            <BeginsWith>
              <ColumnRef Name="Column2" />
              <Value>A</Value>
            </BeginsWith>
          </Or>
        </Where>
      </View>

Where clauses support the following operators:

  • And—used to group operators where both conditions must be true.

  • Or—used to group operators where only one condition must be true

  • Eq—equals

  • Geq—greater than or equals

  • Gt—greater than

  • Leq—less than or equals

  • Lt—less than

  • Neq—not equals

  • Contains—tests if one string contains another string

  • NotContains—tests if one string does not contain another string

  • BeginsWith—tests if one string begins with another string

  • NotBeginsWith—tests if one string does not begin with another string

  • EndsWith—tests if one string ends with another string

  • NotEndsWith—tests if one string does not end with another string

  • IsTrue—tests if Bool is true

  • IsFalse—tests if Bool is false

Views also support OrderBy clauses. For example, if you wanted to add an OrderBy clause that sorts the view by Column1 ascending, you could change it to the following:

      <View Name="Table1View" TableRef="Table1">
        <ColumnRefs>
          <ColumnRef Name="Column1" />
          <ColumnRef Name="Column2" />
        </ColumnRefs>
        <OrderBy>
          <ColumnRef Name="Column1" Ascending="True" />
        </OrderBy>
      </View>

OrderBy clauses also support secondary and tertiary sorts so that you could do the following to sort by Column1 ascending and then Column2 descending:

    <Views>
      <View Name="Table1View" TableRef="Table1">
        <ColumnRefs>
          <ColumnRef Name="Column1" />
          <ColumnRef Name="Column2" />
        </ColumnRefs>
        <OrderBy>
          <ColumnRef Name="Column1" Ascending="True" />
          <ColumnRef Name="Column2" Ascending="False" />
        </OrderBy>
      </View>
    </Views>

Where and OrderBy clauses can be used together to limit and sort data. Putting together all of the elements of the Where clause and the OrderBy clause, our view definition could be the following:

      <View Name="Table1View" TableRef="Table1">
        <ColumnRefs>
          <ColumnRef Name="Column1" />
          <ColumnRef Name="Column2" />
        </ColumnRefs>
        <Where>
          <Or>
            <And>
              <Gt>
                <ColumnRef Name="Column1" />
                <Value>5</Value>
              </Gt>
              <Lt>
                <ColumnRef Name="Column1" />
                <Value>10</Value>
              </Lt>
            </And>
            <BeginsWith>
              <ColumnRef Name="Column2" />
              <Value>A</Value>
            </BeginsWith>
          </Or>
        </Where>
        <OrderBy>
          <ColumnRef Name="Column1" Ascending="True" />
          <ColumnRef Name="Column2" Ascending="False" />
        </OrderBy>
      </View>

Defining Sets in the Schema

After you create a new project from the template, the Sets section is as follows:

    <Sets>
      <Set Name="SPWAddin1DataSet1">
        <ViewRefs>
          <ViewRef Name="Table1View" />
        </ViewRefs>
      </Set>
    </Sets>

This defines one set, SPWAddin1DataSet1, which contains Table1View. You can define as many sets as needed, and each set can contain as many views as needed. The same view can be used in multiple sets. The Fill and FillSchema methods return the records and schema or just the schema from the Set specified by the specified DataSet name.

Defining Indexes in the Schema

By default, the manifest created by the Visual Studio template does not include any indexes. If you were to add an index to the manifest, it might be the following:

    <Indexes>
      <Index TableRef="Table1">
        <ColumnRefs>
          <ColumnRef Name="Column1" Ascending="True" />
        </ColumnRefs>
      </Index>
    </Indexes>

This index would improve the performance of runtime queries that filter and sort on Column1. But there is a trade-off, indexes require more resources when you create a new record or update an existing one. To optimize the overall performance of your add-in tool, you should have indexes that are used for frequent queries but try to limit the number of indexes.