SharePoint 2010 BDC Model Builder


SharePoint 2010 Business Connectivity Services (BCS)
Business Data Connectivity Models
Setting Object Permissions
Creating an External List
When Problems Occur

User Guide

1. Overview

SharePoint 2010 BDC Model Builder automates the creation of Visual Studio 2010 Business Data Connectivity Model projects for SharePoint 2010. It provides the user with a UI for easily selecting a web service (WCF or legacy SOAP 1.1 a service like ASMX), methods and objects and outputs all the required code to generate one or more BDC Models. The tool is intended for use with web services and SharePoint 2010 External Lists, although the models will work with other BCS web parts and should work with any assembly which contains entity objects and CRUD methods for them.

The application basically works by reflecting an assembly specified by the user which typically contains one one or more service references and allowing the user to pick what they want to use from the Assembly Tree which appears on most of the tabs. The application builds the Entity, BDCM XML file and Service class for each model and outputs them to a BDC project specified by the user. The model can simply be added by showing all files and adding the model folder, Visual Studio will arrange all the parts and even create a Feature for it.

In the source and template solutions, a Shim assembly is used to hold service references and keep them separate from the main BDC Model project; it is possible not to use the shim and have references direct in the model, however it may become confusing as the entities will be duplicated and appear in the same assembly (although they actually get an 'entity' suffix). The Shim could also be used to write your own method calls for services with some complexities out of the Builder's capibilitites (in theory the Builder should handle most scenarios, but you never know!). If a Shim is used remember to add it to the WSP package!

2. User Interface

When the BDC Model Builder is opened it displays the current selected model in the project or nothing if no project has been created. To begin editing either selecting:
  • Model -> Edit for an existing model
  • Model -> New for a new model in an existing project
  • File -> New for a new project

2.1 Models Tab

The Models Tab is the first tab to displayed when the application is loaded. It shows the configuration for the whole project at the top and the currently selected model at the bottom. The selected model is also detailed on the rest of the tabs.

screen1.png

2.1.1 Output Path

This is the directory to which the BDC Model Builder writes it's model folder containing the model component parts. This should be the root of the SharePoint project folder. Clicking the elipse button launches the Open Folder Dialog so a directory can be selected.

2.1.2 Models

This is a combo box containing all the models in the project. Changing the selected model changes the current model in the BDC Model Builder.

2.1.3 Target Namespace

This is the namespace of the SharePoint project (the same one located at the Output Path location

2.1.4 Current Model

This is the current model name as selected by the Models combo. It can be used to set the name of a new model or to edit the name of an existing model.

2.1.5 Assembly Path

This is the assembly associated with the model which contains the required entities and CRUD methods. This assembly can be a Shim library containing service references or other data access logic or it could be the actual SharePoint project if it has service references itself. Clicking the elipse button launches the Open File Dialog so an assembly can be selected.

2.1.6 Namespace

This is the namespace of the model. Multiple namespaces can be used in a project, each model can have it's own or they can have the same. It comes in useful if the same entity is required in more than one model.

2.1.7 Output

This allows the output of a model to be disabled in the project if it is not complete or not wanted when the Model -> Write All action is used.

2.2 Entity Tab

This tab is used to configure the Entity associated with the current model.

screen2.png

2.2.1 Entity Source

This is the full type name of the Entity object selected from the Assembly Tree. Clicking the elipse button opens the Assembly Tree which reflects the assembly defined in the Models Tab. Entities will appear at the first level in the Assembly Tree for assemblies with service references, so only one simple selection needs to be made:

tv2.png

Once the Entity is selected, it's properties will appear in the Properties grid. Only writable public properties are displayed.

2.2.2 Entity Name

This is the name of the entity used in the Model. It automatically takes the name of the entity selected plus an 'Entity' suffix so it can easily be differentiated from the original. It can be changed if required.

2.2.3 Display Name

This is the same as the Entity Name, but used as a display name in the model.

2.2.4 Property Grid

The property grid allows the selected Entity to be configured.

2.2.4.1 Property

The name of the property.

2.2.4.2 Type

The object type of the property.

2.2.4.3 Identifier

This indicates that the property is an identifier (e.g. primary key). Composite identifiers (more than one) are not currently supported but will be avaiable soon.

2.2.4.4 Include

This indicates whether a property will be available in the Entity. This can be useful if the source entity contains many properties which aren't required or if a base class property is exposed.

2.2.4.5 Read Only

This can be used to prevent the user trying to change a property in the SharePoint UI. When this is set the field will be read only in the SharePoint InfoPath forms created automatically when the model is deployed.

2.3 Methods Tab

This is used to configure the 5 CRUD methods available for a model.

screen3.png

2.3.1 Methods Grid

This displays an overview of all the methods for the current model.

2.3.1.1 Edit

Each method row has an Edit button which opens the Assembly Tree so that the method details can be selected.

2.3.1.2 Method Type

This is the BDC Model method type.

2.3.1.3 Include

This allows a model to be included in or discluded from the model. The Read List and Read Item methods MUST be included.

2.3.1.4 Method Path

This is the method name.

2.3.1.5 Return Type

This is the object type returned by the method.

2.3.2 Method Parameters Grid

When a row is selected from the Methods Grid, it's associated parameters are displayed in the Method Parameters Grid

2.3.2.1 Entity

This indicates that the parameter does not have a value and must be instantiated.

2.3.2.2 Param

This is the parameter number which is used to map parameters from the model to the source method. For example if a Read Item method takes 2 parameters, one is a just a string for a non-essential parameter and the other is an integer ID parameter, the string will keep the default 0 value, and the ID will require a 1 to indicate that the parameter from the model must be mapped to it.

2.3.2.3 Path

This is the path of the parameter. It shows the full path of nested parameters.

2.3.2.4 Value

This allows a value to be hard coded to a non-essential parameter.

2.3.3 Selecting a Read List Method

This is the main method which returns the list of entities from the data source. The method should not require parameters to select the data (although in they can actually be configured from the UI). A collection type object must be selected from under the appropriate method's return type:

tv3.png

2.3.4 Selecting a Read Item Method

This method returns a single Entity specified by the Entity identifier(s). A single entity must be selected from under the appropriate method's return type and the required parameters from the method's parameters:

tv4.png

2.3.5 Selecting a Update Method

This method is used to update an Entity. It takes an entity parameter and doesn't need to return anything. A single entity must be selected from the appropriate method's parameters:

tv5.png

2.3.6 Selecting a Create Method

This method is used to create an Entity. It takes an entity parameter and should return an entity parameter. Because the properties are reflected in and out of the entities, the parameter and return entity don't have to be exactly the same type which is useful if different types. The return entity needs to contain the ID created by the data source. A single entity must be selected from under the appropriate method's return type and a single entity must be selected from the method's parameters:

tv6.png

2.3.7 Selecting a Delete Method

This method deletes an Entity. It takes an identifier parameter and doesn't need to return anything. The required parameters must be selected from the appropriate method's parameters:

tv7.png

2.4 Data Source Tab

This is used to configure the data source object for the model. If a WCF service is used this will be a Client object from the proxy generated by Visual Studio.

screen4.png

2.4.1 Object

This is the data object selected from the Assembly Tree.

2.4.2 Namespace

This is the namespace of the selected object.

2.4.3 Constructor Grid

This is used to configure the constructors selected from the Assembly Tree.

2.4.3.1 Name

This is the name of the constructor parameter.

2.4.3.2 Value

This is the value to be assigned to a constructor parameter. It is not possible to pick sub-properties from constructor parameters not because it would be difficult to generate code for, but because it would make the user interface difficult to design. If a config key is specified, in the Config Key column, the value must contain the @param key word which will be substituted with the config value.

2.4.3.3 Config Key

The config key column is used to substitute the @param key word used in the Value column with an application configuration setting in the web.config. This is useful as it means BDC Models don't need to be reconfigured at runtime when they are moved to different servers.

2.4.4 Properties Grid

This is used to configure the properties selected from the Assembly Tree.

2.4.4.1 Path

This is the name of the property.

2.4.4.2 Value

This is the value to be assigned to a property. It is possible to pick sub-properties from the Assembly Tree and these will be indicated with a full path. If a config key is specified, in the Config Key column, the value must contain the @param key word which will be substituted with the config value.

2.4.4.3 Config Key

The config key column is used to substitute the @param key word used in the Value column with an application configuration setting in the web.config.

2.4.5 Selecting the Required Settings

In general WCF services require only constructors for the client proxy, however ASMX services can be configured with just properties. This is an example of the selections for a WCF service:

tv8.png

This example shows selections for an ASMX service:

tv9.png

Of course it is possible to use constructors and properties. It is a good idea to test out the client proxy in a test application (like a simple Console Application) to check the configuration required.

2.5 Keyboard Shortcuts

Keyboard shortcuts (only in source at the moment):
  • Ctrl + S - Save
  • Ctrl + E - Edit Model
  • Ctrl + R - Refresh Previews
  • Ctrl + W - Write Current Model
  • Ctrl + L - Write All Models

Last edited Jun 4, 2011 at 6:45 PM by geoff_cross, version 17

Comments

No comments yet.