Appendix A. BCS Model Infrastructure

In this appendix, you will:

  • Review the hierarchy of Business Connectivity Services metadata objects

  • Understand commonly used metadata objects and the relationships among them

In this appendix, you will look at a Business Data Connectivity (BDC) model file to understand its structure. Not all of the features available with Microsoft Business Connectivity Services (BCS) are able to be used by Microsoft Visual Studio or SharePoint Designer. Those familiar with creating the application definition file (ADF) for SharePoint 2007 will be aware that the ADF was created manually, which meant its creators were required to know its structure inside out. Thankfully, we seldom need to delve into this file now, but it is useful to know what is going on inside.

The model that you will look at is a single external content type (ECT) inside of a model. The ECT is for displaying external data. The ECT has full create, read, update and delete (CRUD) functionality. There are two Finder methods, and there are also filters applied to one of the Finder methods. To see the roles of each element of the model, you will also examine how what you view in the XML corresponds to its usage in SharePoint.

You can obtain the complete model from the source code.

Basic Structure

Figure A-1 shows the basic structure of the model.

A simplified view of the BDC model.
Figure A-1. A simplified view of the BDC model.

In Figure A-1, you can see that a model can contain multiple entities—an entity in the model refers to an ECT. Each entity can have one or more methods that provide functionality, such as getting all records, getting one record, or creating new records.

Model

The following code illustrates the model:

<Model>
  <AccessControlList />
  <LobSystems />
</Model>

Access Control List

Permissions to the model itself are configured from the first of many AccessControlList elements found in the model. An example of an access control list entity is shown below. This example grants all authenticated users permission to execute and select the ECT. If a user doesn’t have permissions, the user will receive an “Access Denied” error message on the Web Part.

<AccessControlList>
  <AccessControlEntry Principal="NT AuthorityAuthenticated Users">
    <Right BdcRight="Execute" />
    <Right BdcRight="SelectableInClients" />
  </AccessControlEntry>
</AccessControlList>

You can view and change the settings in the Central Administration website. Navigate to a BDC model to view or set permissions, as shown in Figure A-2.

You can view the access control list inside SharePoint.
Figure A-2. You can view the access control list inside SharePoint.

LobSystems

The LobSystems element typically contains just one LobSystem. A LobSystem is the external system being accessed. You can see in the following code example that the LobSystem defined is connecting to a database. The other options available are DotNetAssembly, WCF, or Custom. The LobSystem Type affects the settings required in the LobSystem instance element.

<LobSystems>
  <LobSystem Type="Database" Name="Adventure Works">
    <Properties/>
    <AccessControlList/>
    <LobSystemInstances/>
    <Entities/>
  </LobSystem>
</LobSystems>

Properties

Most of the elements can accept properties to define behavior. An example of a behavior in the LobSystem is to set the wildcard character to use. The format is a name, a system type as attributes, and the desired value as the element’s value.

<Properties>
     <Property Name="WildcardCharacter" Type="System.String">%</Property>
</Properties>

LobSystemInstances

The LobSystemInstances element contains typically just one LobSystemInstance, which is a single external system. You can see in this element the information that defines how to connect to the external system. In the following example, the external system is Microsoft SQL Server, and simple PassThrough authentication using trusted security is used. If you explicitly set SQL credentials, they would show here, or if you had used the Secure Store, you would have the properties defined to show the Secure Store ID that should be used:

<LobSystemInstances>
    <LobSystemInstance Name="Adventure Works">
      <Properties>
        <Property Name="AuthenticationMode" Type="System.String">PassThrough</Property>
        <Property Name="DatabaseAccessProvider" Type="System.String">SqlServer</Property>
        <Property Name="RdbConnection Data Source" Type="System.String">SP2010</Property>
        <Property Name="RdbConnection Initial Catalog"
Type="System.String">AdventureWorks</Property>
        <Property Name="RdbConnection Integrated Security" Type="System.String">SSPI</Property>
        <Property Name="RdbConnection Pooling" Type="System.String">True</Property>
        <Property Name="ShowInSearchUI" Type="System.String"></Property>
      </Properties>
    </LobSystemInstance>
  </LobSystemInstances>

You can edit these settings in the Central Administration website by navigating to the BCS service application and clicking the name of the external system from the External Systems View (in the ribbon). After you click the external system, you are taken to the view of the external system instances. When you click the name of the external system instance, you see the properties, as shown in Figure A-3. Having these settings editable in Central Administration is useful if you want to make any changes once the model has been deployed.

In the external system instances section, you can edit the properties once the model has been deployed.
Figure A-3. In the external system instances section, you can edit the properties once the model has been deployed.

Entities Element

The Entities element is by far the largest of the elements. It contains the ECTs (entities):

<Entities>
  <Entity Namespace="http://www.adventureworks.com"
          Version="1.2.0.0"
          EstimatedInstanceCount="10000"
          Name="AdventureWorksProducts"
          DefaultDisplayName="Products">
  </Entity>
</Entities>

The version number is an important attribute to remember when working with a BDC model manually. SharePoint checks this version each time the model is imported. If it matches the existing version inside Central Administration, the ECT will not update with the changes. Here, you can also see the display name of the ECT for SharePoint users. For example, when you select the ECT to use on a Business Data Web Part, you will see the name, as shown in Figure A-4.

Selecting an ECT is easy when it has a useful display name.
Figure A-4. Selecting an ECT is easy when it has a useful display name.

Entity

An entity is the ECT. It contains behavior and properties for the object that is being interacted with via BCS:

<Entity>
  <Properties/>
  <AccessControlList/>
  <Identifiers/>
  <Methods/>
</Entity>

The entity contains properties for functionality, such as setting the Title column:

<Properties>
      <Property Name="Title" Type="System.String">Name</Property>
</Properties>

Identifiers

To uniquely identify a record for the ECT, you need to have an identifier. The Identifiers element defines the TypeName and Name of the identifier:

<Identifiers>
    <Identifier TypeName="System.Int32" Name="ProductID" />
</Identifiers>

Methods Element

The Methods element contains the behavior of the ECT and, as the name implies, it contains all of the methods. For each method, such as Finder, SpecificFinder, Creator, Updater, and Delete, there is a method defined in the Methods element:

<Methods>
      <Method Name="Get Product Detail" DefaultDisplayName=" Get Product Detail ">
      <Method Name="Get All Products" DefaultDisplayName="Get All Products">
</Methods>

Method

A Method element contains all the necessary information to let SharePoint know how to handle the method, what type of method it is, if any filters are used, and what information gets passed in and out of the method. The following code illustrates an example:

<Method>
  <Properties/>
  <AccessControlList/>
  <FilterDescriptors/>
  <Parameters/>
  <MethodInstance/>
</Method>

Method Properties

The properties of the method define what needs to be called on the external system to perform the method’s functionality. For example, the following properties define the required information for the method to select the product information from the SQL table:

<Properties>
    <Property Name="BackEndObject" Type="System.String">Product</Property>
    <Property Name="BackEndObjectType" Type="System.String">SqlServerTable</Property>
    <Property Name="RdbCommandText" Type="System.String">SELECT TOP(@ProductID) [ProductID] ,
[Name] , [Color] , [StandardCost] , [ModifiedDate] FROM [Production].[Product] WHERE [Name] LIKE
@Name) ORDER BY [ProductID]</Property>
    <Property Name="RdbCommandType" Type="System.Data.CommandType, System.Data, Version=2.0.0.0,
Culture=neutral, PublicKeyToken=b77a5c561934e089">Text</Property>
    <Property Name="Schema" Type="System.String">Production</Property>
  </Properties>

Filter Descriptors

Notice in the previous SQL statement the two parameters being passed in. The first is selecting the top X items, TOP(@ProductID), and the second is using a where clause to find records matching the name, WHERE [Name] LIKE @Name. You can use a FilterDescriptors element to tell SharePoint that these values are filter values. The FilterDescriptors element defines the values’ behavior with information such as filter type (Limit and Wildcard, in this case):

<FilterDescriptors>
   <FilterDescriptor Type="Wildcard" FilterField="Name" Name="Product Name">
     <Properties>
       <Property Name="CaseSensitive" Type="System.Boolean">false</Property>
       <Property Name="IsDefault" Type="System.Boolean">true</Property>
       <Property Name="UsedForDisambiguation" Type="System.Boolean">false</Property>
       <Property Name="UseValueAsDontCare" Type="System.Boolean">false</Property>
     </Properties>
   </FilterDescriptor>
   <FilterDescriptor Type="Limit" FilterField="ProductID" Name="Limit">
     <Properties>
       <Property Name="CaseSensitive" Type="System.Boolean">false</Property>
       <Property Name="IsDefault" Type="System.Boolean">false</Property>
       <Property Name="UsedForDisambiguation" Type="System.Boolean">false</Property>
     </Properties>
   </FilterDescriptor>
 </FilterDescriptors>

A filter will be shown in SharePoint depending on its type. In Figure A-5, you can see how to use the Wildcard filter on the business data list.

The Wildcard filter is a useful way to get the information you want.
Figure A-5. The Wildcard filter is a useful way to get the information you want.

You can change the Limit filter, which allows you to define how many records you want returned at a time for the external system, from the Edit View link on the Web Part (see Figure A-6).

The Limit filter has a default value that can be changed to limit the records returned by the query.
Figure A-6. The Limit filter has a default value that can be changed to limit the records returned by the query.

Parameters

The parameters represent a very important piece of the BCS puzzle. The parameters describe the components being passed in and out of the method. A Finder method without any filters will contain just a return parameter. If a filter is defined, then the method needs to contain the information on the values that need to be passed into the method, so an additional In parameter will need to be defined, too.

This large section shows the parameters for the Finder method of the model. There are two In parameters, one for each filter, and also the Return parameter, which returns the matching records:

<Parameters>
  <Parameter Direction="In" Name="@Name">
    <TypeDescriptor>
  </Parameter>
  <Parameter Direction="In" Name="@ProductID">
    <TypeDescriptor>
  </Parameter>
  <Parameter Direction="Return" Name="Get All Products">
    <TypeDescriptor>
    </TypeDescriptor>
  </Parameter>
</Parameters>

Type Descriptor

A type descriptor defines the data going in and out of the methods and usually has a TypeName and a Name. You can add numerous properties to the type descriptor to alter its behavior:

<TypeDescriptor TypeName="System.String" Name="Name">
  <Properties>
    <Property Name="RequiredInForms" Type="System.Boolean">true</Property>
    <Property Name="ShowInPicker" Type="System.Boolean">true</Property>
    <Property Name="Size" Type="System.Int32">50</Property>
  </Properties>
  <Interpretation>
    <NormalizeString FromLOB="NormalizeToNull" ToLOB="NormalizeToEmptyString" />
  </Interpretation>
</TypeDescriptor>

Method Instance

The method instance is where the model defines the role of the method and its role for the ECT:

<MethodInstances>
  <MethodInstance Type="Finder" ReturnParameterName="Get All Products (Detailed)" Name="Get All
Products (Detailed)">
    <AccessControlList />
  </MethodInstance>
</MethodInstances>
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset