Creating a SharePoint 2010 External Content Type with CRUD Methods using LINQ and a SQL LOB System 50


Synopsis:

First, this lab builds on an article I saw on MSDN which discussed how to create an External List using Business Data. I noticed that they showed methods for the code but showed no foundation or a Use Case, nor did it discuss the LOB System and how the class entity relationship is defined.

In this Lab/Demo we will show a SQL LOB system which holds Personnel data. Imagine if you will, a system such as SAP, PeopleSoft, Dynamics, etc.  Imagine also that this LOB system is the Source of Record for your organization for things such as Human Resource related data which may be consumed by Active Directory, Sales, Marketing, Finance(Payroll) etc.  How can we surface that data in a Read, Create, Update and Delete fashion maintaining fidelity and ease of use?  here is how…

UPDATE: – On 10/14/2012 I have added another blog post Series that will extend this post for SharePoint 2013 employing WCF, .Net Assembly and OData with SharePoint Apps see it HERE

 

First

  • Check out your Database and pay special to the Columns which will be your fields in your Class Definition, also document your data types.
  • Create a Visual Studio Project using the Business Data Connectivity Model Template
  • Connect to your Database
  • Model the Entity
  • Use LINQ to create the methods to LOB Systems
  • Create the External List
  • Test and Verify

clip_image001

Above: First we need to have our database ready. Above we can infer that we will be going against a server called “Tico”, a Database called “FabianPlayPen” and a Table called “Employee” please take time to notice the current data records currently in there. Once you are done, crack open your Visual Studio 2010 Beta 2.

clip_image002

Note: To work with the Beta 2 bits of SharePoint 2010 you MUST use Visual Studio 2010 Beta 2 for the Templates to work.

clip_image003

Above:  Create a new Project of type “Business Data Connectivity Model” the guy you need for BCS.  I have my VS 2010 set for C# only but you can do this with VB.NET also. I have named my Project “SPSDCEmployees”; this is important because I will be using this name in conjunction with the Entity Class to be created later on in this demo/lab.

clip_image004

Above:  Once you have selected and named your Project you are prompted to choose the site for debugging. I have already created a site called “http://tico/sites/BCSAlpha” for this venture and i have so identified it in my dialog box.

clip_image005

Above:  Once the Project is created, the first order of business is to create a connection to our database.  We are doing this as the means to:

  1. Create a connection to our LOB System
  2. Use it through LINQ to SQL as our model to abstract our Class/Entity

image

Above:  Once you click on Add Connection you will be presented with the dialog box above, please indicate your Server Name and the Database you are interested in.  In my example my Server is my doggie’s name “Tico” and the Database is called “FabianPlayPen” very apropos wouldn’t you say?

image

Above:  After connecting your Database we need to include another  Template to our project. This time we are including a “LINQ to SQL” Template as a means to create our Entity

image

Above:  By default and design, when you create a BCS Project an Entity called “Entity1” will be created, shortly we will remove that entity because as part of that process two classes are also created which we will subsequently delete. Reason being, there is a lot of code already inplace that we will need tie into, by deleting the Entity Object and the related Classes and subsequently recreating our own, we have  better control over our build process. In our example we named our New Item “FabianPlayPen” and a file called FabianPlayPen.dbml is crated in our solution.

image

Above:  The blank design window is what you are initially presented with and is the framework where we will model our Entity Class.

image

Above:  I followed the steps below:

  • On the View menu, click Server Explorer.
  • In Server Explorer, expand the node that represents the Employee database, and then expand the Tables node.
  • Drag the Employee table onto the O/R Designer.

image

Above:  The newly created entity is now present in the OR designer nomenclature is the name of the table in the LOB System.  An entity class is created and appears on the design surface. The entity class has properties that map to the columns in the Employee table.  Now that that process is complete, we need to do some clean-up to aid our design process.

image

Above:  In Solution Explorer we dobule click on BdcModel1.bdcm and we get the desing pane above.

  • In Solution Explorer, expand the BdcModel1 node, and then double-click the BdcModel1.bdcm file.
  • The Business Data Connectivity model file opens in the BDC designer.
  • In the designer, right-click Entity1, and then click Delete.
  • In Solution Explorer, right-click Entity1.cs, and then click Delete.
  • Right-click Entity1Service.cs, and then click Delete.

as you see below…

image

Above and Below: The process to delete the associated .cs files.

image

—————————————————————————————–

image

Above: We will now create our new entity which will abstract our Employee LOB System table from our FabianPlayPen database.

  • On the View menu, click Toolbox.
  • From the BusinessDataConnectivity tab of the Toolbox, drag an Entity onto the BDC designer.
  • The new entity appears on the designer. Visual Studio adds a file to the project named EntityService.cs
  • On the View menu, click Properties Window.
  • In the Properties window, set Name to Employee
  • On the designer, right-click the entity, click Add, and then click Identifier.
  • A new identifier appears on the entity.
  • In the Properties window, change the name of the identifier to EmployeeID

See Below

image

imageimage

Below is a representation of our work so far, it includes the newly created Entity and our Identifier. Next we will create our Methods to Create, Read, Update and Delete.

image

Above:  We will begin the process to create a Finder Method. This method is used to basically surface a List of “ALL” items in the database

  1. On the BDC designer, select the Employee entity.
  2. On the View menu, click Other Windows, and then click BDC Method Details.
  3. In the BDC Method Details window, from the Add a Method drop-down list, select Create Finder Method.

image

  1. Visual Studio adds a method, a return parameter, and a type descriptor.
  2. In the BDC Method Details window, click the drop-down list that appears for the EmployeeList type descriptor, and then click Edit as seen below

image

  1. The BDC Explorer opens. The BDC Explorer provides a hierarchical view of the model.
  2. In the Properties window, set the Type Name property to System.Collections.Generic.IEnumerable`1[SPSDCEmployees.Employee, BdcModel1] as seen below

image

image

  • In the BDC Explorer, expand the EmployeeList node and select the Contact node.
  • In the Properties window, set the Type Name property to SPSDCEmployees.Employee, BdcModel1.
  • In the BDC Explorer, right-click the Employee, and then click Add Type Descriptor.
  • A new type descriptor named TypeDescriptor1 appears in the BDC Explorer.
  • In the Properties window, set the Name property to EmployeeID.
  • Set the Type Name property to System.Int32.
  • From the Identifier drop-down list, select ContactID.
  • Repeat step 8 to create a type descriptor for each of the following fieldsAs seen in the below 3 ScreenShots.

    image

    Screen Shot 1

    image

    Screen Shot 2

    image

    Screen Shot 3

    Now we need to create the remainder of the Type Descriptors for the Employee Entity; here is where we go back to our LOB System or our Entity Class created earlier and get the Names and Data Type of the columns to create our TypeDescriptors. Once we have done that it is time to add the code for our  ReadList Method

    image

    Above:  Double-Click on the ReadList in the Employee Entity to enter the code view as seen below.  By default a method is created and we need to remove the entry in the method and replace with our own.

    image

    image

    Above:  Our code is inserted in the ReadList Method

    • A connection string is created to attach to our LOB System
    • An Instance of the Employee List is created and populated with all the data from the LOB System

    That it. Easy isnt it! Next we need to create a Specific Finder Method which is responsible for returning a single item as requested in the SharePoint UX. As before we go back to the BCS Designer to add the Method and add our code… see below next three screen shots.

    image

    image

    image

    1. In the BDC designer, select the Employee entity.
    2. In the BDC Method Details window, collapse the ReadList node.
    3. From the Add a Method drop-down list that appears below the ReadList method, select Create Specific Finder Method.
    4. Visual Studio adds the following elements to the model. These elements appear in the BDC Method Details window.
      1. A method named ReadItem.
      2. An input parameter for the method.
      3. A return parameter for the method.
      4. A type descriptor for each parameter.
      5. A method instance for the method.
    5. In the BDC designer, on the Employee entity, double-click the Readitem method and add the code you see in the second (2nd) screen shot.

    image

    image

    We will create two additional method Create and Update.. lets go with Create first then the Update Method.  As before we begin from the Entity and select new method from the BDC Method Details Pane. Click the Method and add the code as reflected the screen shot.

    image

    image

    image

    image

    image

    Next we create the Update Method

    image

    image

    TEST AND VERIFY

    Finally we get to deploy our solution and see it in action. Click build then Deploy Solution to get our code up to our Farm.

    image

    Above:  Click Build then Deploy Solution…

    image

    Above:  To verify that the solution is uploaded we go to Central Admin under Application Management, Click on Business Data Connectivity to see if the Build was uploaded to the server Farm, see below…

    image

    Above:  Evidenced that our External Content Type is on the Server Farm, we now move to creating our External List to surface the information abstracted by the External Content Type.

    image

    Above:  Under Site Actions, click Create More, then choose External List.

    image

    Above:  Select the External Content Type we created as above…

    image

    Above:  Create a name and ensure that we have the correct Data Source Configuration

    image

    Above:  So… Viola! we have our external content type representative of the SQL Database Table called Employee, neat huh!

    image

    Above:  as part of our verification process we have confirmation that our columns are consistent to the Entity and LOB System. Now lets kick the tires on the newly created methods..

    image

    Above:  Lets click “Add New Item” this will instantiate and fire off the Create Method of our External Content Type. The next four screen shots represent the new form, the entered values, the post and final resultant Read List with the created item.

    image

    Above: The blank auto-generate form when you click Add New Item

    image

    Above:  Filling in the form with what will be the new data

    image

    Above:  Awesomness! we have our newly created item in our List… later we will do a SQL query to validate the record. Next, let us investigate the Update Method…

    image

    Above:  In this example we click on the custom action by the Picker field and we elect the “Edit Item” Once we click it we see the below…

    image

    Above:  The item in question is noted in the Update Form… I am picking  on my buddy Todd Baginski here, he does and awesome work on BCS and other SharePoint 2010 elements. Visit him here

    image

    Above:  Well because his name is synonymous to  good ol Frodo I relocated Todd to the Shire…

    image

    Above:  Confirm the changes above…

    image

    Above:  Finally we check the LOB system and we can see our Create, and Our Update, come to the SPS DC for the Delete… LOL


  • Leave a Comment

    Your email address will not be published. Required fields are marked *

    You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

    50 thoughts on “Creating a SharePoint 2010 External Content Type with CRUD Methods using LINQ and a SQL LOB System

    • Reply
      Brian bedard

      You can do this same work using Designer. Not sure why you used Visual Studio? I haven’t met one person that cares how to create a BDC model. I think it’s cool but I’m a geek.

      • Reply
        fabiangwilliams

        Well, this is just part 1 of a series, i have been blogging and tweeting about making relationships between disparate LOB systems i.e. Flat File and SQL, Web Service and SQL, and that story is easier well, lets say it is more extinsible in VS rather than SPD. also to more accurately answer your question, it allows for a proper SDLC if designed here and extended in SPD 2010 under the same WSP/ dll.

        • Reply
          fabiangwilliams

          yes you can create a deployable soln with designer, you can use designer for just about anything except aggregated classes (entities)

    • Reply
      Tommy Kristoffersen

      Great work posting about BCS on your blog!

      I have been trying to figure out how columns must be required. In your example I see that only EmployeeHireDate is required. How would you make this field required, and have a friendly message if not filled in? I have seen one example with adding “RequiredInForms” in the TypeDescriptor, creating the model from SPD, but it is not working from VS. Any ideas?

    • Reply
      Lam

      Great articles,let me have more concepts about the BDC.

      Do have any example about retreive the data by the parameter(input by user or userid)

      Thanks you very much

    • Reply
      Justin

      so far so good. any update on the retrieving data on a per user (logged in) basis?

      HR Group Members = view/edit all employee data
      Employee = view only his or her data

      thanks

      • Reply
        fabiangwilliams

        well you can certainly handle that in the Security Model in BCS on the ECT or in code on the Entity itself, or using Secure Store Service. Several options available to you. I have done some work with Secure Store, i will blog it soon

    • Reply
      Fred Morrison

      Where is the source code for your example? Forgive me a link to a zip file of the code is somewhere on this rather busy page, but I cannot seem to find it.

    • Reply
      Vijay Arora

      I am getting an error while creating new record via BCS.

      The error is: Failed to get value of the “ID” column from the “Single line of text” field type control. See details in log. Exception message: This field cannot be updated + BCS

      Could you please help in this…

      • Reply
        fabiangwilliams

        Could you send me an email with a screen shot of the error, i want to see exactly when you get it, then i should be able to find out what caused it. If this is when you are using the Create method, then it could trace back to be one of the following (1) datatype mismatch (2) primary or foreign key mistmatch (3) data validation error e.g. date time etc (4) or just something inthe code…

        • Reply
          Vijay Arora

          Thanks for your reply

          What is your email id? Once you give it to me then I will send you the screen shot. but you are right I am getting datatype error.

          The exact error message is given below:
          Failed to get value of “ID” column from the “Integer” field type control. See details in log. Exception Message: This field cannot be updated..

      • Reply
        Lieven

        I have the same issue. It seems that external lists have diffuculties with identifiers from BCS with the name ‘ID’. Changing the name of the identifier in the model will solve the problem.

      • Reply
        fabiangwilliams

        So what BCS gives you is External Content Type and External List as a high level artificat to work with. In List view for the external list you will have paging built in. If you want to take an external content type to create a Web Part to consume the data withing then Paging is your responsibility. Now that said, i think alot can be done with Silverlight and using the paging features inherent to Silverlight may be easier to do. Hope this helps.

    • Reply
      adari

      Hi, nice post, Can some tell me how to data related from two table like products(product related columns & Customer Id) and customer(customer related columns with customerId), in the DB these two has relations, then how to maintain relations in model design.

      And explain if possible, in bcs design what is Foreign Identifier Association Entity and other detials like association betwen two entities..

      Thanks…

      • Reply
        fabiangwilliams

        So, the answer to that is that it must be done in Visual Studio using the BCM Model. I have sucessfully done it with LINQ to SQL and creating an associated class representitive of a JOIN between the tables. Then use that Aggregated class as my Entity. All the joins and database magic happens in the LINQ to SQL class.

    • Reply
      Karine Bosch

      Hi Fabian,
      Really like your posts! I tried this solution out using the Department table of the AdventureWorks database, but I have problems viewing the external list (got that “Unable to display this Web Part” error). I debugged the LINQ code and the ReadList method retrieves the departments, but it seems the error occurs after executing the return. No errors in the LOGS nor Event Log. Is it possible I forgot to set a permission somewhere?
      Karine

      • Reply
        fabiangwilliams

        so, the most simpliest reason for that error is returning too much records at once. do a filter and see if it fixes the issue. if not send me ur code..

        • Reply
          Arnie Lugo

          Hi Fabian,

          I too have the same issue as Karine (issue #14). I do not see any errors in the logs or the event logs either. Am I missing a setting? I have checked on the SQL backend and the SQL query has run correctly. My External List breaks after the fact with the dreaded “Unable to display this webpart” error. This is very frustrating. Your example code is excellent. Any help would be truly appreciated.

          Thanks

          • Reply
            fabiangwilliams

            unable to display this web part is common, but i urge you to check the 14 hive log agian, if a correlation id was thrown search for that and/or use the ULS viewer… do this, take the same actions, then look i the log, you may not see the error number but look around the same time stamp and you will see somthing to point you in the right direction. all else fails email me the log to fabian@adotob.com

    • Reply
      Guruprasad marathe

      Like you said I have created all,i have issue when we add “Add New Item” ..
      I am consuming service from SAP about employee information. I have created the entity in BDC, its a external contain type.

      I have created CRUD method for Employee, but while creating a new item in share point screen , I am getting the text boxes to save employee details but i need to flush (or pre-populate) few information such as empid, name,competency and have to make it readonly, and also for category i need to give a drop down box, and and also i have no of experiance NoOfExp identifier in Employee Entity how can provide drop down for this? atleast hardcoded values.
      help me.

      I am using share point 2010 and doing this thru Visual studio 2010, not using designer

      guruprasadmarathe@gmail.com

      • Reply
        fabiangwilliams

        The Model OOB creates Text Boxes, I have not done what you are asking but it is worth a try. I will take a stab at it.

    • Reply
      guru

      Hi fabian,

      i have created a external list with below code.

      Everything works, but when I try to update an item, I get this error (shown below). The item is updated successfully, which is odd. I’ve searched the forums for this error, and found nothing.

      error:”The instance cannot be updated, because there have been changes to the original instance data.

      code:

      using System;

      using System.Collections.Generic;

      using System.Linq;

      using System.Text;

      namespace BDCGuruEx.BdcModel1

      {

      public partial class CustomerService

      {

      public static List TotalCustomer;

      static CustomerService()

      {

      TotalCustomer = new List();

      for (int i = 0; i < 5; i++)

      {

      Customer e = new Customer();

      e.CustomerId = i;

      e.FirstName = e.CustomerId + " First Name";

      e.LastName = e.CustomerId + " Last Name";

      TotalCustomer.Add(e);

      }

      }

      public static IEnumerable ReadList()

      {

      return TotalCustomer;

      }

      public static Customer ReadItem(int customerId)

      {

      foreach (Customer cust in TotalCustomer)

      {

      if (cust.CustomerId == customerId)

      {

      return cust;

      }

      }

      return null;

      }

      public static Customer Create(Customer newCustomer)

      {

      TotalCustomer.Add(newCustomer);

      return newCustomer;

      }

      public static void Update(Customer customer)

      {

      foreach (Customer cust in TotalCustomer)

      {

      if (cust.CustomerId == customer.CustomerId)

      {

      cust.FirstName = customer.FirstName;

      cust.LastName = customer.LastName;

      break;

      }

      }

      }

      public static void Delete(int customerId)

      {

      foreach (Customer cust in TotalCustomer)

      {

      if (cust.CustomerId == customerId)

      {

      TotalCustomer.Remove(cust);

      break;

      }

      }

      }

      }

      }

      • Reply
        fabiangwilliams

        Surprisinlgy I have seen that before too and I think it has to do with the event postback refresh. It happens to me in SPD 2010 ETC when I link to Outlook and try to update in Outlook client. I havent seen anything on it and it happens only sporadically. not all the times.

    • Reply
      guru

      while debugging it the control not comes to update method only.. i had put break points every where..
      readitem method called 3 times and the record is updated.
      please can you use my Code which i have given to u and let me know.. please check in your machine with my code. tel whether u r getting the same or wat. please try this n let me know

    • Reply
      Jcastaneda

      Hi Mr. Williams, I’m hoping you can help me.

      Information regarding my environment: I’m trying to connect a MySQL database to SharePoint using BCS. windows server 2008 R2 standard. I figured I could use your guide and just change the some of your code (the code specific to SQL) to allow queries/inserts to the aforementioned MySQL Database.

      I’m not too sure how to explain my problem because SharePoint won’t help me out with a better description of an error than “Creating new items is not supported.”

      Another error I get is “could not save the list changes to the server” when I try to create a new form (after I’ve already determined that creating new items is not supported-not surprisingly.)

      What’s odd to me is that the NewForm form appears straight after deployment but when I open a new form it shows up blank as in there is no fields present whatsoever.

      Then when I try to configure the Create Operation in the External Content Types option from my Document “external content type” and make it so that it matches the input and return parameters and save the Content Type, it says that “creating is not supported” and upon creating a new External List, I find that the NewForm.aspx has disappeared.

      I’ve done much research and check input parameters and return parameters and code and the insert string to no avail.

      Could it possibly be because I have the project on the .NET 4.0 Framework? and sharepoint is on 3.5? because I’ve just recently noticed that the aforementioned “blank form” has “incompatibilities” I haven’t had much time to investigate since I stumbled upon your blog and I’m not too good with xhtml/aspx. But if I solve the problem then cool but I probably will have difficulty so I beseech you to assist me!

      Thank you.

      • Reply
        fabiangwilliams

        I think you have hit a couple of the potential issue already
        1. build in .net 3.5 not 4
        2. the LOB system shouldnt matter as long as you are using the right connectivity class
        3. send me screen shots to fabian@adotob.com

    • Reply
      Vighnesh

      Hi Fabian,
      First of all thank you very much for the detailed post. I have implemented your steps on suppliers table in northwind. but when I refresh the site, it throws an error – “Unable to display this Web Part”. And when I see the log, I found this error…

      Microsoft.BusinessData.MetadataModel.InvalidMetadataObjectException: Cannot find Property with name ‘SupplierID’ on the parent object. The parent object may be returned by the LobSystem (External System) or it is created to be sent to LobSystem as input. This Property is referred to by child TypeDescriptor with Name ‘SupplierID’ and Id ’1358′ on Parameter with Name ‘supplierList’ on Method with Name ‘ReadList’ on Entity (External Content Type) with Name ‘Supplier’ in Namespace ‘MVBdcModelProject.BdcModel1′.

      I have created a input param for ReadItem and created Filter Descriptor.

      Please help me in solving this issue…

      -Vighnesh

    • Reply
      Erik

      Where you first create your ReadList() the variable name
      similarities has confused me. For instance, “Employee” may be referring to the FabianPlayPenDataContenxt.Employee entity, or the BDCModel1.Employee, or the BDCModel1.employeeList.Employee. Could you rework the ReadList() using explicit types?

      public static IEnumerable ReadList()
      {
      FabianPlayPenDataContext dataContext = new FabianPlayPenDataContext
      (“Data Source=tico; Initial Catalog=FabianPlayPen; Integrated Security=True”);

      IEnumerable Employees =
      from e in dataContext.Employees
      select e;

      return Employees;
      }

    • Reply
      山田 由紀子

      Thank you very much for the detailed post.
      The post does not contain the Create code, Could you help me

    • Reply
      danieladeniji

      Nice work and beautiful community participation, as well.

      It is always good to see someone learn so deeply and turn-around and freely share with all.

      Continue to live well,

      Daniel Adeniji