TypeDescriptor

  • Article

Every Parameter object has a TypeDescriptor object that defines the data type of the parameter. It is the most complex metadata object—a hierarchical object that recursively describes an abstract data structure built up of primitives. In addition, each leaf node of the TypeDescriptor tree points to a set of possible default values specified by the MethodInstance object. Therefore, given a MethodInstance object and a parameter, the parameter's TypeDescriptor object is a recipe to instantiate a default value for that parameter.

TypeDescriptors in Input Parameters

The IdentifierName attribute on an input TypeDescriptor signals the Business Data Catalog to insert the identifier value of the entity instance of relevance before executing the method. For example, if this is part of a SpecificFinderMethodInstance, the user has probably provided the identifier value for the entity instance he or she wants to retrieve. The Business Data Catalog inserts that value into this slot after fully instantiating this parameter by using all the default values.

The AssociatedFilter attribute on an input TypeDescriptor signals the Business Data Catalog to insert the user or system provided value after instantiating the parameter and before executing the method. For example, if this is part of a FinderMethodInstance , the user has provided values for some or all filters associated with the method. These are inserted into the tagged slots before method execution.

TypeDescriptors in Return Parameters

  • For database systems, the root TypeDescriptor object of the return parameter always has the IsCollection flag set. This is because all output from a database is a record stream regardless of the semantic context—that is, whether a single record (SpecificFinder/ViewAccessor) or multiple records (Finder) are expected.

    Database systems are modeled as a stream of records. As a result, the root TypeDescriptor is a stream and the next level TypeDescriptor is a record. Even though a record is a collection of columns, the IsCollection flag is not set because we want the Business Data Catalog to treat it as a structure of strongly typed fields.

  • In Web service systems, use the IsCollection flag on a return TypeDescriptor object to indicate where there are collections within the return parameter. Consider a WebMethod object that returns collections of customers, where each customer contains a collection of Addresses. In this example, the flag must be set twice—once at the root Customer[] level and then again at the Customer[0].Address[] level. However, a TypeDescriptor collection can have only a single child TypeDescriptor object under it that represents the structure in the collection.

The TypeDescriptor objects in the return parameter represent the Fields of the IEntityInstance interface constructed by the Business Data Catalog and returned to the user for display or manipulation. The IEntityInstance interface provides an abstract access mechanism for fields and the identifier values of the instance. Because the identifier values are promoted within the IEntityInstance interface for direct access, you must identify which TypeDescriptor object actually provides these values. You do this by tagging the output/return TypeDescriptor object with the IdentifierName attribute.

TypeDescriptors in Associations

An AssociationMethodInstance object contains slots in the input for the identifier values of the source entity instance, and a slot in the output for the identifier values of the destination entity instances. Therefore, you must tag enough input TypeDescriptor objects tagged with identifiers corresponding to each identifier of each entity that is a source in the association in the Association method. The IdentifierName attribute on an input TypeDescriptor object signals the Business Data Catalog to insert the identifier value of the entity instance of relevance before executing the method. For example, in an AssociationMethodInstance, the user has probably provided the identifier values for the source entity instance that they want to retrieve. The Business Data Catalog will insert that value into this slot after fully instantiating this parameter by using all the default values.

Examples

The following examples show a simple parameter and a more complex return parameter that return an entity instance collection. The last example shows a parameter that is used to code a DataSet returned from a Web method.

Simple Parameter

<Parameter Direction="In" Name="@minCustId">
   <TypeDescriptor TypeName="System.Int32" 
   IdentifierName="CustomerID" AssociatedFilter="ID" Name="minCustId">
      <DefaultValues>
         <DefaultValue MethodInstanceName="CustFinderInstance" 
         Type="System.Int32">0</DefaultValue> 
      </DefaultValues>
   </TypeDescriptor>
</Parameter>

Complex Parameter

<Parameter Direction="Return" Name="Customers">
   <TypeDescriptor TypeName="System.Data.IDataReader, System.Data, 
   Version=2.0.3600.0, Culture=neutral, 
   PublicKeyToken=b77a5c561934e089" IsCollection="true" 
   Name=" CustomerDataReader">
      <TypeDescriptors>
         <TypeDescriptor TypeName="System.Data.IDataRecord, 
         System.Data, Version=2.0.3600.0, Culture=neutral, 
         PublicKeyToken=b77a5c561934e089" Name="CustomerDataRecord">
            <TypeDescriptors>
                <TypeDescriptor TypeName="System.Int32" 
                 IdentifierName="IndividualID" Name="IndividualID">
                 <LocalizedDisplayNames>
                    <LocalizedDisplayName LCID="1033">ID
                    </LocalizedDisplayName> 
                 </LocalizedDisplayNames>
               </TypeDescriptor>
               <TypeDescriptor TypeName="System.String" 
                 Name="FirstName">
                <Properties>
                  <Property Name="DisplayByDefault" 
                  Type="System.Boolean">true</Property> 
                </Properties>
            </TypeDescriptor>
            <TypeDescriptor TypeName="System.String" Name="LastName">
              <Properties>
                <Property Name="DisplayByDefault" 
                Type="System.Boolean">true</Property> 
              </Properties>
             </TypeDescriptor>
            </TypeDescriptors>
         </TypeDescriptor>
      </TypeDescriptors>
   </TypeDescriptor>
</Parameter>

DataSet

<Parameter Direction="Return" Name="Customers">
<TypeDescriptor Name=""DataSet"" TypeName=""System.Data.DataSet, System.Data, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"">
                                                <TypeDescriptors>
                                                    <TypeDescriptor Name=""Tables"" TypeName=""System.Data.DataTableCollection, System.Data, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"" IsCollection=""true"">
                                                        <TypeDescriptors>
                                                            <TypeDescriptor Name=""Table"" TypeName=""System.Data.DataTable, System.Data, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"" >
                                                                <TypeDescriptors>
                                                                    <TypeDescriptor Name=""Rows"" TypeName=""System.Data.DataRowCollection, System.Data, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"" IsCollection=""true"">
                                                                        <TypeDescriptors>
                                                                            <TypeDescriptor Name=""DataRow"" TypeName=""System.Data.DataRow, System.Data, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"">
                                                                                <TypeDescriptors>
                                                                                    <TypeDescriptor Name=""field1"" TypeName=""System.String"" IdentifierName=""f1"" />
                                                                                    <TypeDescriptor Name=""field2"" TypeName=""System.String"" />
                                                                                    <TypeDescriptor Name=""field3"" TypeName=""System.String"" />
                                                                                </TypeDescriptors>
                                                                            </TypeDescriptor>
                                                                        </TypeDescriptors>
                                                                    </TypeDescriptor>
                                                                </TypeDescriptors>
                                                            </TypeDescriptor>
                                                        </TypeDescriptors>
                                                    </TypeDescriptor>
                                                </TypeDescriptors>
                                            </TypeDescriptor>
</Parameter>

Schema

Child Type Occurs Default Limits / Accepted Values Description

TypeName

Attribute (String)

1..1

Min. length: 1

Max. length: 255

Name of the type in the LOB system's type system that is described by this TypeDescriptor object.

The ITypeReflector associated with the Parameter object of this TypeDescriptor object that is responsible for resolving this LOB system type into a .NET Type.

In the case of both Web services and databases (ADO.NET), the "LOB system type system" is the .NET Type System, so the value of TypeName is a .NET Type name.

IdentifierName

Attribute (String)

0..1

Name of the identifier represented by this TypeDescriptor object.

If this TypeDecsriptor object describes an input parameter of a SpecificFinder method, the parameter is populated with the identifier's value when you call the FindSpecific method.

If this TypeDescriptor object describes an output parameter or a Finder or SpecificFinder method, the value of the parameter is included in the identifier values collection of returned entity instances when you call FindFiltered or FindSpecific.

IdentifierEntityName

Attribute (String)

0..1

The entity containing this TypeDescriptor object

Name of the entity that contains the identifier represented by this TypeDescriptor object.

IdentifierEntityName is necessary when you model an association as a method on a source entity. In this case, the source entity returns instances of the destination entity, so you must set IdentifierEntityName property to the name of the destination entity.

AssociatedFilter

Attribute (String)

0..1

Max. TypeDescriptor objects per FilterDescriptor object: 10

Name of the filter associated with this TypeDescriptor object.

IsCollection

Attribute (Boolean)

0..1

false

Specifies whether the TypeDescriptor object represents a collection. If true, the TypeDescriptor must contain exactly one child TypeDescriptor that describes an element in the collection.

The return parameter of a Finder method must have a TypeDescriptor with IsCollection = true.

DefaultValues

Element

0..1

Max. default values per TypeDescriptor: 10

Container element for DefaultValue.

TypeDescriptors

Element

0..1

Max. TypeDescriptor objects per TypeDescriptor object: 300

Container element for TypeDescriptor.

Properties

The TypeDescriptor object accepts the following property in the fields of a return parameter.

Important

Properties are case-sensitive.

Property Type Required Default Value Limits/ Accepted Values Comments

ShowInPicker

System.Boolean

No

false

true

false

If this property is set to true in a field of a return parameter, then that field is displayed in the business data picker. Business Data Catalog displays all fields that have the "ShowInPicker" property defined, plus the title field in the business data picker. If there are none, it displays only the identifier field.

See Also

Tasks

AdventureWorks SQL Server 2000 Sample
How to: Get Started with Using the Runtime Object Model
How to: Get Started with Using the Administration Object Model

Concepts

FAQ: Business Data Catalog
Business Data Catalog: Glossary