BCS model – some basics

To create a BCS model in Visual Studio, create a new project based on the template ‘Business Data Connectivity Model’ and give the project a name. In the next screen you can see a BSC model can be deployed only as a farm solution, not a sandboxed solution, and select the site for debugging. 

Visual Studio now creates a couple of things for you: 

1.    Entity1.cs – describes the schema for the entity; also known as External Content Type in Central Administration, Business Data Connectivity Service page; a class with properties.
2.    EntityService1.cs – implementation for CRUD methods. These methods, Create, Read, Update, Delete, can be implemented by the following BCS operations:   

• Finder (e.g. ReadList)
• SpecificFinder (e.g. ReadItem)
• Creator (e.g. CreateItem)
• Deleter (e.g. DeleteItem)
• Updater (regular update and synchronize offline content back to the store)

Visual Studio creates ReadList and ReadItem example methods for you. 

3.    BdcModel1.bdcm – the model definition (diagram) in design view, the BDC Designer.
4.    BdcModel1.bdcm.diagram – the xml definition of the design layout of the model diagram. 

When you open the .bdcm file in Visual Studio a new Explorer window is available: the BDC Explorer (View, Other Windows, BDC Explorer).  The layout of this explorer can also be seen when you open the .bdcm file e.g. in Notepad. It is just an xml file which described the whole model: LobInstances, Entities, Methods and MethodInstances, everything. Of course Visual Studio is using this xml file to generate the contents of the BDC Explorer. 

Another new window can be used when viewing the .bdcm file: BDC Method Details. As the name suggests the details of the methods of the selected entity are displayed: the mapping to the method name and parameters with the Direction (In, Out, InOut, Return) and the Type Descriptor (e.g. Entity1 at ReadItem and IEnumerable<Entity1> at ReadList for the return parameters). You can select an entity on the designer window or the BDC Explorer. 

When you don’t like the default names for e.g. Entity1, I don’t, you can rename the entity. After renaming the entity switch to the design view of the model. Here the entities name still is Entity1. So make sure you keep in mind there’s no automatic update between the entity definition and the entity design (the model), because the entity on the design represents the metadata and it’s our responsibility to provide the mapping between the code and the metadata. 

The entity on the design has a custom property which points to the entity service. With this connection the code in the service can be adjusted to the changes made in the design surface or BDC Method Details. 

Keep in mind that the initially generated ReadList and ReadItem methods in the service are not deleted when you delete the methods at the design surface or BDC Method Details. I don’t know why, loosely coupled? The methods you create yourself are updated very well. 

Just delete the generated methods in the BDC Method Details and update the service file. 

Let’s create a Specific Finder method ourselves by selecting ‘Add a method’ in the BDC Method Details pane and select ‘Create Specific Finder Method’. A method is created with the default name ‘ReadItem’ with a return parameter with the name ‘person’ and Type Descriptor ‘Person’. Remember that the Type Descriptor displayed here is just a name; it doesn’t tell you the type of the return parameter. At the properties window of the Type Descriptor you will find a property ‘Type Name’, that’s your type. The default type here is System.String, change this to your type. The format will be <namespace>.<class>, <External System Name> 

When you create the project the model is named BdcModel1. This name seems to appear on different places. Can I rename this without punishment? 

In the BDC Explorer the name BdcModel1 appears three times:

I guess the name of the LobSystemInstances can be changed without punishment at this time, because it is an instance name I don’t use it anywhere because I have basic code. So I start a brand new project and I change the LobSystemInstance name from BdcModel1 to BdcLobInstance. Where can I find this change after deployment? 

Central Administration, Business Data Connectivity Service page: no changes at all. I expected a rename to happen on the External System Instance name:
 

And when creating an external list based on the external content type I expected the name of the datasource to change, but no renaming done… 

Well, allright then, let’s rename the model itself in the BDC Explorer from BdcModel1 to BdcModelChanged:
 

The model is renamed as expected:
 

And the Lob instance name is also renamed!
 

And when creating an external list based on the external content type:
 

So, something is wrong with my system or the model itself has to be renamed in order to rename the LobSystemInstance name in the browser. 

We still have two items with the same name, let’s rename them too:
 

The BDC Model name is BdcModelMain, the External System Name is BdcModelSub and the External System Instance Name is BdcLobInstance. All renamed! 

A summary in the following picture: