Implementing a Finder

  • Article

Applies to: SharePoint Server 2010

In this article
Description
Syntax
Remarks
Examples

Description

A Finder is a special method instance that returns multiple entity instances. This stereotype is used for reading a list of items given a filtering criterion. For example, given a business object named Customer, this method can be used to obtain a list of customers whose order amount is in a certain range.

External content types can have one or more Finder methods that return multiple instances. If you do not define Finder methods, your external content type cannot be used with the presentation features of Business Connectivity Services, such as external lists and Business Data List Web Parts.

Syntax

Following is the typical method signature for a Finder method:

public static EntityDataType[] GetEntities ()

Remarks

To qualify as a Finder, the corresponding method:

  • Should take the filtering criterion as input parameter(s) to limit the number of items returned (especially when returning a large number of items) .

  • Should return collections of items of an external content type.

  • Should return the identifier of the item as part of the view returned for each item.

  • Should support rich filtering (see filtering support in Business Connectivity Services for details about what filters to support).

  • We recommended that the Finder method supports paging or batching if it returns many items.

  • The "view" for each item returned by this method must be equal to, or a subset of, the view for the specific Finder method. This is because create operations and update operations are dependent on the specific finder view. If the finder returns more fields, the extra fields cannot be updated.. Also, if a Finder method returns only a subset of the data, a SpecificFinder call is executed to return the rest, to ensure that the cached items are complete. Therefore, it is recommended that the specific finder and the finder have identical views. If the specific finder call and the finder method have identical views, Business Connectivity Services optimizes calls made to the external system.

In SharePoint 2010, an external content type can have multiple finders with different views. The following are some scenarios where multiple finders are useful:

  1. Role-based views: One Finder method can be used to present a limited view to peers and the global address book, while another finder method can be used to present the another detailed view to the employee or the employee’s manager.

  2. **Cache optimization:**Business Connectivity Services has rich support for taking business data offline to Microsoft Office clients like Outlook and SharePoint Workspace. Administrators can disable offlining for detailed views to optimize cache usage on the client side. This allows users to have a limited view offline and to access the detailed view while online.

Note

If there are multiple specific finders with different views of a business object, it is good to have at least one Finder method for each specific finder method.

Examples

Code Snippet: Implementing a Finder

See Also

Concepts

XML Snippet: Modeling a Finder Method

Code Snippet: Execute a Finder Method Instance of an External Content Type