BDC Model Best Practices for Duet Enterprise

Learn best practices to protect your Duet Enterprise for Microsoft SharePoint and SAP solutions from degraded performance and other problems that can occur when you work with large volumes of external data.

Applies to: Duet Enterprise for Microsoft SharePoint and SAP Server 2.0 | Office 2010 | SharePoint Server 2010

In this article
Specify Default Limit Filter Values
Avoid Using the FilterField Attribute on Filters
Avoid Specifying the UsedForDisambiguation Property on Limit Filters That Are Not Meant for Use by the Entity Picker
Specify the Title Property for External Items
Anticipate Business Connectivity Services Wildcard Behavior When Designing Finder Methods
Finder Methods Should Return Zero Rows Instead of Throwing Exceptions

When you implement Business Data Connectivity (BDC) service metadata models in your Duet Enterprise solutions, you can protect your solutions from problems, such as degraded performance, that can occur when you manipulate large volumes of external data by doing the following:

  • Specifying default Limit filter parameter values.

  • Avoiding the unnecessary use of client-side filtering.

  • Understanding how to use Limit filter properties correctly.

  • Understanding the behavior of Finder methods well enough to anticipate edge cases that can be introduced by wildcard behavior and zero results.

For an overview of the BDC service, see Business Data Connectivity (BDC) Service (https://msdn.microsoft.com/en-us/library/ee556407.aspx). For a description of the BDC metadata model, see BDC Model Infrastructure (https://msdn.microsoft.com/en-us/library/ee556378.aspx).

Specify Default Limit Filter Values

Always specify explicit, low default values for Limit filters. Microsoft Business Connectivity Services (BCS) internally calls Finder methods on external data when performing many operations, such as displaying forms. These calls use the default value of the Limit filter that is specified in the model, and are sometimes followed by additional calls for each item that is returned. To prevent performance degradation in these scenarios, it is best to specify an explicit default value. When the value is numerical, specify as low a value as possible. An empty default Limit filter value can also prevent items from showing up in SharePoint workspaces.

The following examples show how to specify a default parameter value for a Limit filter.

Filter descriptor with a default property

<FilterDescriptor Type="Limit" Name="Maximum Query Hits">
  <Properties>
    <Property Name="CaseSensitive" Type="System.Boolean">false</Property>
    <Property Name="IsDefault" Type="System.Boolean">false</Property>
  </Properties>
</FilterDescriptor>

Type descriptor with a default parameter value

<TypeDescriptor TypeName="System.Int32" AssociatedFilter="Maximum Query Hits" Name="MaxHits">
  <DefaultValues>
    <DefaultValue MethodInstanceName="FindCustomerByElements" Type="System.Int32">25</DefaultValue>
  </DefaultValues>
</TypeDescriptor>

One disadvantage of specifying a low default Limit filter value is that when you create a new external list, the default view for that list uses this value and displays only that number of items. When this occurs, you can simply modify the view.

Avoid Using the FilterField Attribute on Filters

The FilterField attribute of Limit filters provides client-side filtering in offline scenarios that take advantage of the capabilities of Microsoft SharePoint Workspace 2010. SharePoint Workspace uses this attribute to render views. Because the filtering semantic used in this attribute may not be identical to the one used in the external system, it is possible that when this attribute value is evaluated in the cache, the view rendered in SharePoint Workspace will contain fewer items or items that are different from the online view. To prevent this potential discrepancy, avoid using the FilterField attribute.

The following example shows where a FilterField attribute might appear in your filter.

<FilterDescriptor Type="Wildcard" FilterField=”FirstLineName” Name="First Name">
  <Properties>
    <Property Name="CaseSensitive" Type="System.Boolean">false</Property>
    <Property Name="IsDefault" Type="System.Boolean">false</Property>
    <Property Name="UsedForDisambiguation" Type="System.Boolean">true</Property>
  </Properties>
</FilterDescriptor>

The following example shows the same filter with the FilterField attribute removed.

<FilterDescriptor Type="Wildcard" Name="First Name">
  <Properties>
    <Property Name="CaseSensitive" Type="System.Boolean">false</Property>
    <Property Name="IsDefault" Type="System.Boolean">false</Property>
    <Property Name="UsedForDisambiguation" Type="System.Boolean">true</Property>
  </Properties>
</FilterDescriptor>

One disadvantage of this approach is that different offline views of an external list can display the union of all the offline views. If this is less acceptable than the potential discrepancies between online views and offline views, you can use the FilterField attribute. To avoid offline views that consist of small subsets of the online views, take the following steps.

To make the wildcard character the default FilterField attribute value

  1. Define the wildcard character in your model.

  2. Specify the wildcard character as the default value for filters with the FilterField attribute.

Note

SharePoint Workspace 2010 does not explicitly prepend and append the filter value with wildcards when it filters against the cache. The external system might be doing this, however, in which case the results in an offline view could be a small subset of the online view.

Avoid Specifying the UsedForDisambiguation Property on Limit Filters That Are Not Meant for Use by the Entity Picker

The UsedForDisambiguation property is a keyed property instead of a value property. In other words, if the property is present, the filter is used for disambiguation, and if the property is absent, the filter is not used for disambiguation. Even if the value of the property is set to false, the filter is still used for disambiguation simply because it is present.

When the Entity Picker performs External Item resolution, it makes Finder calls that use a string entered by the user as input for each filter defined on the Finder. The Entity Picker makes an extra call for each wildcard filter, and appends and prepends the string entered by the user with the wildcard character. These calls are followed by specific Finder calls for each result that is returned. To improve external item resolution performance, avoid specifying the UsedForDisambiguation property on filters, such as CountryCode, for which you do not want disambiguation to occur. For example, it is highly unlikely that a user would type US and expect the query to resolve to a single item. A more likely scenario would involve the user selecting Country/Region Code from the filter drop-down and typing US as the country or region code. The user would then see all the returned items and select from among them.

If you unnecessarily define the UsedForDisambiguation property, you will likely see serious performance degradation, especially in cases where a large number of rows are returned.

Specify the Title Property for External Items

By default, the business data field where an associated External Item appears on external list forms displays the identifier value. You can provide a better user experience by specifying the Title property for the external content type, as shown in the following example. In this example, FirstLineName is the name of the field whose value will be set as the display value in external list forms. If you create collaboration workspaces for this external content type, the title of the site will also be set to the same value.

<Property Name="Title" Type="System.String">FirstLineName</Property>

If you add or modify this property in the external content type model, the addition or change will be reflected in existing forms.

Anticipate Business Connectivity Services Wildcard Behavior When Designing Finder Methods

When applying Wildcard filters, Business Connectivity Services appends and prepends wildcard characters to strings entered by the user before using these strings as filter values. Data source filter values for a list view are passed as specified. The Finder methods should be designed to handle both of these scenarios efficiently.

You can prevent Business Connectivity Services from appending and prepending the wildcard character to strings entered by the user by using Comparison filters instead of Wildcard filters. When Business Connectivity Services uses Comparison filters, it passes strings that are input by the user and data source filter values without any modifications. If you use this workaround, follow the guidance described in Avoid Using the FilterField Attribute on Limit Filters and do not specify the FilterField attribute for the filter.

Finder Methods Should Return Zero Rows Instead of Throwing Exceptions

Business Connectivity Services expects that Finder methods will return zero rows instead of throwing exceptions when there are no results to return after applying the filter criteria. When zero rows are in the result set, Business Connectivity Services displays a message to the user that is appropriate for the context. When an exception is thrown, Business Connectivity Services displays an error message that indicates results could not be retrieved and advising the user to try the search again later. This behavior potentially misleads users by suggesting that a technical error has occurred and that results might be available. This behavior appears on external list views and in the Entity Picker search dialog box.

See Also

Other Resources

Types of Filters Supported by the Business Data Connectivity Service (https://msdn.microsoft.com/en-us/library/ee556392.aspx)

Building Queries with the BDC Object Model (https://msdn.microsoft.com/en-us/library/ff798471.aspx)