Second Life of a Hungarian SharePoint Geek

August 23, 2010

Creating external lists from code

Filed under: BCS, External list, SP 2010 — Tags: , , — Peter Holpar @ 20:30

You can create an external list based on an entity (external content type) defined in SharePoint Business Connectivity Services programmatically. All you need to do is to use the SPListDataSource class that describes the entity to be bound to the external list instance.

When creating an external list, you should use the Add method overload of the SPListCollection that has the SPListDataSource type parameter. You can find a sample for that from Frederik Prijck here.

A similar method replacing the strings with the string constants defined in the SPListDataSource.BDCProperties class:

  1. private void CreateExternalList(SPWeb web)
  2. {
  3.     SPListCollection lists = web.Lists;
  4.     SPListDataSource listDataSource = new SPListDataSource();
  5.     // set up the list data source
  6.     listDataSource.SetProperty(SPListDataSource.BDCProperties.Entity, "YourBdcEntity");
  7.     listDataSource.SetProperty(SPListDataSource.BDCProperties.EntityNamespace, "YourBdc.EntityNamespace");
  8.     listDataSource.SetProperty(SPListDataSource.BDCProperties.LobSystemInstance, "YourLobSystemInstancece");
  9.     listDataSource.SetProperty(SPListDataSource.BDCProperties.SpecificFinder, "ReadItem");
  10.     // create list
  11.     Guid extListGuid = lists.Add("External list title", "External list description", "extlist", listDataSource);
  12.     SPList extList = lists[extListGuid];
  13.     // set other list properties
  14.     extList.OnQuickLaunch = true;
  15.     extList.Update();
  16. }

As you can see the properties of the SPListDataSource class are not real .NET properties. Instead of calling the setter of the property, you can set the their values by calling the SetProperty method.

I felt initializing the SPListDataSource through the SetProperty method a bit cumbersome, so I’ve created an extension method for the SPListDataSource class:

  1. public static class Extensions
  2.     {
  3.         public static void Initialize(this SPListDataSource listDataSource, String entity, String entityNamespace, String lobSystemInstance, String specificFinder)
  4.         {
  5.             listDataSource.SetProperty(SPListDataSource.BDCProperties.Entity, entity);
  6.             listDataSource.SetProperty(SPListDataSource.BDCProperties.EntityNamespace, entityNamespace);
  7.             listDataSource.SetProperty(SPListDataSource.BDCProperties.LobSystemInstance, lobSystemInstance);
  8.             listDataSource.SetProperty(SPListDataSource.BDCProperties.SpecificFinder, specificFinder);
  9.         }
  10.     }

Using the new extension method makes the original code a bit more readable:

  1. private void CreateExternalListEx(SPWeb web)
  2. {
  3.     SPListCollection lists = web.Lists;
  4.     SPListDataSource listDataSource = new SPListDataSource();
  5.     // set up the list data source using the extension method
  6.     listDataSource.Initialize("YourBdcEntity", "YourBdc.EntityNamespace", "YourLobSystemInstancece", "ReadItem");
  7.     // create list
  8.     Guid extListGuid = lists.Add("External list title2", "External list description", "extlist2", listDataSource);
  9.     // set other list properties
  10.     SPList extList = lists[extListGuid];
  11.     extList.OnQuickLaunch = true;
  12.     extList.Update();
  13. }

Remark: I found that creating the external list from code takes considerably more time than creating one from the SharePoint UI. In my test environment it was about 30 secs vs. 5 secs that is quite a big difference. Probably I should launch Reflector to see that quicker method of external list creation.


  1. Hi,

    Thank you the great post.
    I have one issue related to the External Content Type List.
    In my case i need to read data from the text file and need to populate this external content type list. I created list from the sharepoint designer 2010 and added the list to the SP Site.

    Now i am trying to add the list item to the list then it is not adding.

    Can u plz guide me?

    With Regards
    Akhilesh Rao

    Comment by akhilesh Rao — December 12, 2010 @ 06:20

    • Hi Akhilesh,

      Have you implemented the external content type as a managed assembly in Visual Studio?

      I suggest you to read my other post that I feel is closer to you problem. If you still face the problem, check the SharePoint log for errors.

      Be prepared, that using text files for such purpose in a multiuser environment may cause issues when concurrent users would like to update the content of the same file at the very same time.


      Comment by Peter Holpar — December 21, 2010 @ 22:38

  2. Great post, but I found (in SP 2010) that I had to change the settings from

    listDataSource.SetProperty(SPListDataSource.BDCProperties.EntityNamespace, “YourBdc.EntityNamespace”);

    to just

    listDataSource.SetProperty(SPListDataSource.BDCProperties.EntityNamespace, “YourEntityNamespace”);

    Or I would get the following error when attempting to execute lists.Add:

    Microsoft.SharePoint.SPException was unhandled by user code
    Message=Entity (External Content Type) cannot be found with Namespace = ‘YourBdc.EntityNamespace’, Name = ‘YourBdcEntity’.

    In other words: DO NOT put a period and DO NOT prefix the EntityNamespace with “YourBdc.”

    It took me ages to figure this out. I knew it was something simple, because the list could be created from the GUI, just not in code by following these instructions.

    Hopefully this helps the next person…

    Comment by Daryl Rasmussen — February 17, 2012 @ 19:08

RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

Blog at

%d bloggers like this: