Working with Complex Data Types

Applies to: SharePoint Server 2010

In this article
Overview of Complex Types in BCS
Complex Formatting in BCS External Content Types Through String Formatting
SharePoint-Compatible Service Layer
.NET Connectivity Assemblies
Extending the External List Type System Through Custom Field Types
Customizing SharePoint List Forms
Customizing InfoPath Forms

Using Microsoft Business Connectivity Services (BCS), you can display complex data types in external lists in various ways. Complex types are data types that contain other subtypes, such as an address that is composed of street, city, state, and zip code fields. By default, although complex types are supported by the schema of external content types, complex types cannot be displayed in the presentation layer in Microsoft SharePoint 2010 and Microsoft Office 2010. For this reason, you must take additional steps to enable the display of these complex types. This topic provides an overview of complex types in Business Connectivity Services and then offers various solutions for displaying these complex types in the user interface.

Overview of Complex Types in BCS

Data in external systems is frequently exposed through granular Web services with complex message structures. Although parameter data structures of almost any complexity are supported by the schema for external content types, complex types can create incompatibilities with presentation technologies in SharePoint and Microsoft Office.

External content types define stereotyped operations, many of which require a parameter structure that is technically complex. A specific finder (also known as a Read Item in SharePoint Designer) must return a single complex type that contains the set of fields for an external content type, for example, a type "Customer" with fields "CustomerID", "Name", and "PhoneNumber". The child elements of this structure map to the columns of an external list. Most external content types contain a finder method that returns a collection of the same type as the specific finder. Issues arise when any of the fields has child elements or if a field is of a type that is not supported by the presentation technologies; for example, if a "CustomerAddress" field is added to the customer structure, which in turn has child elements defining "Street", "City", "State", and "PostalCode".

One of the primary user interface components for displaying external data in SharePoint is the external list. By design, an external list is a flat, row-based representation of data. Without additional work by a developer, complex types and simple types that are not supported in the SharePoint list type system are omitted from the list view.

The Business Connectivity Services external content type schema supports the notion of complex formatting for read-only scenarios if the complex type can be converted to a simple string by using a Microsoft .NET Framework format string (see Complex Formatting in BCS External Content Types Through String Formatting later in this topic). If read-only support is not enough or if the complex type cannot be converted with this method, SharePoint 2010 provides the capability to create custom field types that provide control over rendering and editing behavior in external lists and list item forms.

Forms are the primary user interface for external list items. Complex types pose a challenge to the generation of forms because they are difficult to design automatically while maintaining a minimum level of visual appeal. External lists can be associated with SharePoint list forms (based on ASP.NET) or Microsoft InfoPath 2010 forms. The Customizing SharePoint List Forms and Customizing InfoPath Forms sections in this topic describe how to display complex types in these forms.

Complex Formatting in BCS External Content Types Through String Formatting

In scenarios when the complex type is read-only in the external list and can be converted to a string, Business Connectivity Services supports the notion of a format string on the type descriptor to render the complex type as a string in an external list or item form. The following is an example of using string formatting to convert the Customer complex type mentioned previously.

<TypeDescriptor TypeName="CustomerAddress" IsCollection="false" Name="CustomerAddresses" > 
   <TypeDescriptors> 
      <TypeDescriptor TypeName=" CustomerAddress " Name="CustomerAddress" > 
         <Properties> 
            <Property Name="ComplexFormatting" Type="System.String" /> 
            <Property Name="FormatString" Type="System.String">{0}, {1}, {2} {3}</Property> 
         </Properties> 
         <TypeDescriptors> 
            <TypeDescriptor TypeName="System.String" Name="Street"/> 
            <TypeDescriptor TypeName="System.String" Name="City" /> 
            <TypeDescriptor TypeName="System.String" Name="StateProvince" /> 
            <TypeDescriptor TypeName="System.String" Name="PostalCode" /> 
         </TypeDescriptors> 
     </TypeDescriptor> 
   </TypeDescriptors> 
</TypeDescriptor>

SharePoint-Compatible Service Layer

Architecturally, the best approach to working with a complex data type, is to create a service layer with a flat parameter structure that exists within the limitations of the presentation layers. To continue with the example from the previous section, if the Web service returns all the fields that represent the customers at the same level, SharePoint can render and edit customer items without any modification.

However, you must weigh this approach and its overhead of writing, hosting, and maintaining custom code against the overhead of handling complex types in the presentation layers for each application by using a complex service. In many enterprise deployments a service layer already exists, especially for business entities such as Customer or Product that have broad use in many applications. The cost of adding methods for use with SharePoint 2010 might be less than the cost of handling the type complexity in each application.

.NET Connectivity Assemblies

If adding or extending a service layer is not an option, SharePoint 2010 provides a way to package the external content type definition with a class that encapsulates the business logic behind an external content type operation. You can define the flattened interface of the external content type by using the Business Data Connectivity Designer in Visual Studio 2010 and implement any aggregation and type conversion logic needed in the code stubs that the tool generates. After the implementation is complete, you can use Visual Studio to generate a solution package (.wsp file ) containing the external content type definition and the assembly that can be imported to SharePoint 2010.

Note

To import this type of package, farm administrator privileges are required because the code behind the external content type runs in full trust mode. For information about the creation of .NET connector assemblies, see Using the SharePoint Business Data Connectivity Designer in Visual Studio 2010 by Boris Scholl.

Because modifying the behavior of back-end services is not always an option, SharePoint 2010 also provides several ways to extend the presentation layer to handle complex types.

Extending the External List Type System Through Custom Field Types

The SharePoint 2010 list infrastructure supports a set of generic data types, which are sufficient to address the most common data entry scenarios. To represent complex business data items such as addresses, SharePoint 2010 provides a way to define custom field types that you can make available across all sites on a SharePoint farm. The custom field type definition file is central to a custom field type. It defines how to render a field on the list and item views. It also defines any variable properties and a reference to the assembly that implements the field type. The field class inherits from SPField and represents particular fields based on the custom field type. The field class defines the capabilities, such as sorting, of a column based on the custom field, defines the behavior of a cell within a list and the content database, and can implement custom validation logic.

Most complex custom field types also require a rendering control class, a rendering template, or a custom value class. For more information about custom field types, see Custom Field Types and Walkthrough: Creating a Custom Field Type.

After you define the custom type, you can reference it by using type descriptors in the external content type definition, as shown in the following example.

<TypeDescriptor TypeName="Customer.Address” Name="CustomerAddress" DefaultDisplayName="Customer Address"> 
   <Properties> 
       <Property Name="SPCustomFieldType" Type="Customer.Address">Customer Address</Property> 
   </Properties> 
</TypeDescriptor> 

With that definition of type descriptors, an external list based on the external content type can determine that type descriptor "CustomerAddress" refers to a custom field type and render it appropriately.

Customizing SharePoint List Forms

When you create a new external list, SharePoint 2010 automatically generates forms to enable the creation, editing, and viewing of list items. SharePoint forms are based on .NET Framework controls and share their extensibility capabilities, which you can use to render complex types appropriately. Custom field types described in this topic are the extensibility mechanism most often used for complex types. For simpler cases, you might be able to extend a native SharePoint Foundation field. For more information about list form customization, see List Forms.

Customizing InfoPath Forms

SharePoint 2010 also supports the use of InfoPath forms for viewing and editing list items. InfoPath provides features that make it easy for non-developers to create attractive forms with powerful validation and conditional formatting. Another advantage InfoPath forms have over standard list forms is their ability to function inside the browser or as stand-alone forms, or to function in rich clients. InfoPath forms are the forms technology used to work with external list data offline in Microsoft SharePoint Workspace 2010. In SharePoint 2010, you cannot begin to create InfoPath forms for external lists in InfoPath Designer. Instead, you can generate InfoPath forms in SharePoint Designer either from the external list or external content type designers. After they are generated, you can customize them in InfoPath Designer.

For external content types that contain complex types, it is difficult to generate a visually appealing layout by default. Therefore, the forms generator generates a blank form. However, because InfoPath does support complex types in the designer, after a form is generated, you can open it in InfoPath Designer from the external list designer in SharePoint Designer. The custom types are available in the fields list. See Figure 1, and can be laid out manually.

Figure 1. Field list in InfoPath Designer

After the customizations are complete, you must publish the updated form back to the external list by using the Quick Publish button on the File menu.

Figure 2. Quick Publish button in InfoPath Designer