Planning Step 5: Determine In, Out, and Return Parameters for each method
Applies to: SharePoint Server 2010
The Business Data Connectivity (BDC) service generates a Web service proxy to access the Web service. Therefore, for each method, determine the in, out, and return parameters by studying the appropriate Web method in the Web Services proxy. Each parameter gets a value for the Name attribute, which can be set to any meaningful name. The details of the parameter are provided by inserting a child element of type TypeDescriptor. The TypeDescriptor element has a Name attribute.
At the top level (root TypeDescriptor), the TypeDescriptor can be named anything you want.
For child TypeDescriptor, names must be the name of the .NET Framework accessor in the .NET type referenced by the parent TypeDescriptor. For example, TypeDescriptor with Name "WorkPhoneNumber" is written because "WorkPhoneNumber" is a .NET Property/Field on the type of the parent TypeDescriptor, which is SampleWebProxy.Customer.
The child TypeDescriptor of a TypeDescriptor with IsCollection set to true can also be named anything you want.
For TypeDescriptors of input parameters that represent arrays, it is possible to define metadata that fills the array with default input values. To do this, define the input parameter's TypeDescriptor that represents the array with the IsCollection flag set to false. Then create n child TypeDescriptors with default values corresponding to the n values you want added to the input array when the method is executed.
In addition, the type of the TypeDescriptor should also match the type in the proxy. If the TypeDescriptor represents the unique key of the entity, the attribute IdentifierName points to the corresponding Identifier element. The last attribute of the TypeDescriptor element is the AssociatedFilter attribute that links the with the FilterDescriptor element defined for the entity. It tells the BDC to insert the value of the filter into this part of the parameter before executing the Web method call.
The following is the definition of the GetCustomers method in the SampleWebService proxy. You can derive the input and the top-level return parameter from here.
public Customer[] GetCustomers(string name, [System.Xml.Serialization.XmlElementAttribute(IsNullable=true)] System.Nullable<int> limit) {
object[] results = this.Invoke("GetCustomers", new object[] {
name,
limit});
return ((Customer[])(results[0]));
}
For return parameters, we define what will be returned as fields of the entity instances to the BDC. The first child TypeDescriptor defines in the proxy the return type that will be returned by the method instance (Web method), in this case, an array of customers: SampleWebServiceProxy.Customer[]. The second TypeDescriptor element defines each object in that array; in our case, each object is of type SampleWebServiceProxy.Customer. Each remaining TypeDescriptor element details each of the fields of a Customer instance.
This is the Customer class definition in the SampleWebService proxy. You can derive the return parameter's child TypeDescriptors from here.
public partial class Customer {
private string customerIDField;
private string nameField;
private System.Nullable<long> workPhoneNumberField;
private System.Nullable<long> mobilePhoneNumberField;
private string industryField;
private string webSiteField;
private CustomerAddress[] customerAddressesField;
private string parentCustomerIDField;
/// <remarks/>
public string CustomerID {
get {
return this.customerIDField;
}
set {
this.customerIDField = value;
}
}
/// <remarks/>
public string Name {
get {
return this.nameField;
}
set {
this.nameField = value;
}
}
/// <remarks/>
[System.Xml.Serialization.XmlElementAttribute(IsNullable=true)]
public System.Nullable<long> WorkPhoneNumber {
get {
return this.workPhoneNumberField;
}
set {
this.workPhoneNumberField = value;
}
}
/// <remarks/>
[System.Xml.Serialization.XmlElementAttribute(IsNullable=true)]
public System.Nullable<long> MobilePhoneNumber {
get {
return this.mobilePhoneNumberField;
}
set {
this.mobilePhoneNumberField = value;
}
}
/// <remarks/>
public string Industry {
get {
return this.industryField;
}
set {
this.industryField = value;
}
}
/// <remarks/>
public string WebSite {
get {
return this.webSiteField;
}
set {
this.webSiteField = value;
}
}
/// <remarks/>
public CustomerAddress[] CustomerAddresses {
get {
return this.customerAddressesField;
}
set {
this.customerAddressesField = value;
}
}
/// <remarks/>
public string ParentCustomerID {
get {
return this.parentCustomerIDField;
}
set {
this.parentCustomerIDField = value;
}
}
}
Following is the definition of the input and return Parameter elements for the GetCustomers method in the XML metadata.
<Parameters>
<Parameter Direction="In" Name="name">
<TypeDescriptor TypeName="System.String"
AssociatedFilter="Name" Name="name" />
</Parameter>
<Parameter Direction="In" Name="limit">
<TypeDescriptor TypeName="System.Int32"
AssociatedFilter="Limit" Name="limit" />
</Parameter>
<Parameter Direction="Return" Name="Customers">
<TypeDescriptor TypeName="SampleWebServiceProxy.Customer[],
SampleWebService" IsCollection="true" Name="ArrayOfCustomer">
<TypeDescriptors>
<TypeDescriptor TypeName="SampleWebServiceProxy.Customer,
SampleWebService" Name="Customer">
<TypeDescriptors>
<TypeDescriptor TypeName="System.String"
IdentifierName="CustomerID" Name="CustomerID" />
<TypeDescriptor TypeName="System.String" Name="Name" />
<TypeDescriptor TypeName="System.Int64"
Name="WorkPhoneNumber" />
<TypeDescriptor TypeName="System.Int64"
Name="MobilePhoneNumber" />
<TypeDescriptor TypeName="System.String" Name="Industry" />
<TypeDescriptor TypeName="System.String" Name="WebSite" />
</TypeDescriptors>
</TypeDescriptor>
</TypeDescriptors>
</TypeDescriptor>
</Parameter>
</Parameters>