Implementing a SpecificFinder
Applies to: SharePoint Server 2010
In this article
Description
Syntax
Remarks
Examples
Description
A SpecificFinder returns exactly one external item. This stereotype is used to read an item, given its identifier. For example, given a Customer business object, this stereotype can be used to obtain detailed customer information for a given customer ID.
External content types should have at least one SpecificFinder method instance that returns a single instance, given an identifier. If you do not define a SpecificFinder method instance for an external content type, it cannot have actions on it, cannot be searched or indexed, and cannot be used in any of the Business Connectivity Services presentation features, except with the Related List Web Part.
Syntax
Following is the typical method signature for a SpecificFinder:
EntityDataType GetEntityById(IdType1 id1, ...)
Remarks
To qualify as a SpecificFinder, the corresponding method should do the following:
Take all the identifiers of an external content type as input.
Return a structure that has a set of fields (called a View in Business Connectivity Services; see definition in this topic).
To qualify as a SpecificFinder, the corresponding method must do the following:
Return a single external item of one external content type.
Return fields that must contain all the external item identifiers.
Note
Usually, the read operation queries the external system to get data. Ensure that you properly handle null values in the SpecificFinder method. It is likely that some fields are null in the external system (for example, hobbies or address). Having proper error handling and exception handling is essential. Therefore, check for null and empty strings in your code, and then fix them. Also consider using NormalizeString interpretation on type descriptors.
Throw the exceptions shown in Table 1 for the given conditions in a .NET Connectivity Assembly.
Table 1. Exceptions
Exception Name |
Use It When…. |
|---|---|
ObjectNotFoundException |
The item was not found on the external system (may be deleted). |
ObjectDeletedException |
The item was deleted from the external system. You should throw this exception when the deletion of items can be distinguished from not having items. |
Note
In a Web service, the SpecificFinder should return null when the item is not found.
A View is a collection of fields, where each field has a name, a type, and, optionally, localized display names. It is a schematic definition—unlike views in SQL databases, which include the schematic definition and the data returned as part of the query.
For example, if Employee is an external content type, then a view of Employee may contain the following fields:
ID
Name
Address
Designation
It is possible to have multiple views of the same business object in Business Connectivity Services. For example, another view of Employee may contain the following fields:
ID
Name
Address
Designation
AnnualIncome
StartDate
SeniorityLevel
EmergencyContact
In SharePoint 2010, an external content type can have multiple specific finders with different views. Following are some scenarios where multiple specific finders are useful:
Role-based views: Given an EmployeeId, one specific finder method can be used to present a limited view to peers, while another specific finder method can be used to present the another detailed view to the employee or the employee’s manager.
**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 performance 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.
Note
The following are some additional notes about BDC and external lists.
-
BDC supports read-only fields.
-
External lists do not support complex types.
-
The default forms created for external lists need to be replaced with Microsoft InfoPath 2010 forms to work with complex types.
Examples
Code Snippet: Implementing a SpecificFinder