MethodInstance Class
Describes how to call a method. It is a reference to a method, plus the default values for the input parameters the method takes.
Inheritance Hierarchy
System.Object
Microsoft.Office.Server.ApplicationRegistry.Administration.MetadataObject
Microsoft.Office.Server.ApplicationRegistry.Administration.AccessControlledMetadataObject
Microsoft.Office.Server.ApplicationRegistry.Administration.IndividuallySecurableMetadataObject
Microsoft.Office.Server.ApplicationRegistry.Administration.MethodInstance
Microsoft.Office.Server.ApplicationRegistry.Administration.Association
Namespace: Microsoft.Office.Server.ApplicationRegistry.Administration
Assembly: Microsoft.SharePoint.Portal (in Microsoft.SharePoint.Portal.dll)
Syntax
'Declaration
<SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel := True)> _
<SharePointPermissionAttribute(SecurityAction.Demand, ObjectModel := True)> _
Public Class MethodInstance _
Inherits IndividuallySecurableMetadataObject
'Usage
Dim instance As MethodInstance
[SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel = true)]
[SharePointPermissionAttribute(SecurityAction.Demand, ObjectModel = true)]
public class MethodInstance : IndividuallySecurableMetadataObject
Remarks
A single method can have multiple MethodInstance objects, with each MethodInstance object being a combination of the method signature and a set of default values. You can use MethodInstance objects to call the same method with different default values. MethodInstance objects are especially useful for complex Web services. For example, you may have a WebMethod that returns multiple outputs in several ref or out type Parameters. Business Data Catalog can process only a single return value at a time, so you would define such a WebMethod as a single Business Data Catalog Method, and then create multiple MethodInstances, each of which would point to a different parameter of the core method as the 'Return' parameter.
To completely define a MethodInstance object, you can optionally define a TypeDescriptor element along with the ReturnParameter in XML. Following is an example.
<MethodInstance Name="bla" Type="Finder" ReturnParameterName="foo" ReturnTypeDescriptorName="baz" ReturnTypeDescriptorLevel="5">
The attribute ReturnTypeDescriptorName is optional. If it is not specified, the Business Data Catalog assumes the root TypeDescriptor of the Return parameter element. The attribute ReturnTypeDescriptorLevel is also optional. If it is not specified and there are more than one similarly named TypeDescriptor, an exception is thrown. If there are more than one similarly named TypeDescriptor elements at the same level (which is rare), the first is assumed.
This flexibility is important because it allows reuse of a Web method in multiple ways. Consider a WebMethod that returns collections of Customers, and each Customer contains a collection of Addresses. Three Business Data Catalog MethodInstances that use this WebMethod: a Customer Finder, a Customer SpecificFinder and a CustomerToAddress Association (returns a Customer's Addresses). In the MethodInstance model, the metadata author must define just that portion of the Return parameter that is of relevance, by allowing a user to specify the TypeDescriptor within the ReturnParameter.
Associations are derived classes MethodInstance classes and the Association definition format also optionally takes in ReturnTypeDescriptor values.
<Association Name="CustomerToAddresses" AssociationMethodEntityName="Customer" AssociationMethodName="GetCustomerByID" AssociationMethodReturnParameterName="Customer" AssociationMethodReturnTypeDescriptorName="CustomerAddresses" AssociationMethodReturnTypeDescriptorLevel="1">
<SourceEntity Name="Customer" />
<DestinationEntity Name="Address" />
</Association>
Finally, the object model for MethodInstance also provides a ReturnTypeDescriptor accessor/property. The ReturnParameter is implicitly part of the ReturnTypeDescriptor, and because the object model works with object references, there is no further need to specify a ReturnParameter when using the object model.
Certain method instances have special purposes that enable generic clients.
Finders and SpecificFinders
A Finder is a special method that returns entity instances. A SpecificFinder returns exactly one entity instance. Finder methods are static methods and do not take a key as an input parameter. SpecificFinder methods are also static methods but they take a key (ID) explicitly.
Entities that can be reached only by association must have zero finders. Other entities should have one Finder method that returns multiple instances, and one SpecificFinder method that returns a single instance, given an ID.
For example, for the Customer entity, the Finder method might be SELECT * FROM Customers and the SpecificFinder method might be SELECT * FROM Customers WHERE CustomerID = id.
If you do not define Finders methods, your entity cannot be used in a Business Data List Web Part; if you do not define SpecificFinder methods, that entity cannot have actions on it, cannot be searched or indexed, and cannot be used in any of the Business Data features except the Related List Web Part.
To qualify for a Finder, the corresponding method must take filterable parameters as input and return collections of records, where each record must contain the key of the entity instance it represents. To qualify as a SpecificFinder, the corresponding method must take the entity instance key as one of the input parameters and must return fields, of which one of the fields is the key.
Following is a slightly more complex example of a Finder method that has filterable parameters.
SELECT ProductID, Name, ProductNumber, ListPrice FROM Product WHERE (ProductID >= @MinProductID) AND (ProductID <= @MaxProductID) AND (Name LIKE @Name) AND ProductNumber LIKE @ProductNumber)
Finder methods and SpecificFinder methods need not return the same fields. You might have scenarios where the SpecificFinder method returns more fields than the Finder method. However, they both must return the identifiers defined on the entities.
A Finder and a SpecificFinder method must have exactly one corresponding method instance.
A SpecificFinder method plays an important role in Enterprise Search and indexing. A Business Data Catalog crawl has two phases:
ID Enumeration: Fetch all entity instance IDs.
Detail fetch: Fetch details for each entity instance.
An IDEnumerator, described later in this topic, returns the IDs and the SpecificFinder method returns the details for each entity instance.
ViewAccessors
A view is a collection of fields for an entity. The default view of an entity contains the fields returned by Finder methods and SpecificFinder methods. A ViewAccessor is another special method that returns a non-default view, that is, a different set of fields from the business application. ViewAccessor methods are instance methods that take a key (ID) implicitly; that is, you do not provide the key. The Business Data Catalog provides the key automatically.
Entities have zero or more ViewAccessor methods.
Although Finder and SpecificFinder methods may have only one method instance, ViewAccessor methods may have one or more method instances. This flexibility is useful when the same method returns multiple structures, each of which makes up a view. In systems such as SAP, there are APIs (for example, BAPI_CUSTOMER_GETDETAIL2) that return multiple collections of related fields to the user. The Customer GetDetails API, for example, may return a structure containing financial data, a structure containing address data, and so on.
Note
The Business Data features such as Business Data Web Parts and lists support entity views.
IDEnumerator
A Business Data Catalog crawl has two phases:
ID Enumeration: Fetch all entity instance IDs.
Detail fetch: Fetch details for each entity instance.
An IDEnumerator method returns the list of IDs (unique key) for each entity that should be searchable, and the SpecificFinder method returns the details for each entity instance. This enables indexing of the entities whose IDs the IDEnumerator method returns.
Note
If you require incremental crawl, you must ensure that the LastModifiedDate property is one of the return fields of the SpecificFinder for the entities.
Entities have zero or one IDEnumerator Method. IDEnumerator methods are not limited to returning a list of IDs. If they return other fields in the return parameter, the Business Data Catalog ignores them during the crawl.
The LastIdSeen filter enables chunking for IDEnumerator methods. For Web services and other nonstreaming back-end applications, use the LastIdSeen filter in your IDEnumerator method to improve performance, as follows:
SELECT TOP 100 Id FROM Customers WHERE Id>=@LastIdSeen
ORDER BY Id
Use the LastIdSeen filter instead of the following
Select Id from Customers
GenericInvoker
A GenericInvoker is a method that you can invoke in the back-end line-of-business (LOB) application that is not one of the methods described previously. For example, you can use a GenericInvoker method to execute a method in the back-end application to edit an entity or to update the unit price in the Products table.
Entities have zero or more GenericInvoker methods.
GenericInvoker methods are extremely useful if you are writing a custom Web Part that must invoke logic in a back-end system, because the Business Data Catalog takes care of all the authentication, authorization, other security requirements, and so on.
Note
The Business Data features such as Business Data Web Parts and lists do not make use of GenericInvoker methods. However, the object model and the XML schema support this type of method instance.
Scalar
A Scalar is a method that returns a single value that you can invoke in the back-end LOB application. For example, you can use a Scalar method to get the total sales made to date from the back-end application.
Entities have zero or more Scalar methods.
Thread Safety
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
See Also
Reference
Microsoft.Office.Server.ApplicationRegistry.Administration Namespace