Exercise 3: Modeling BCS Applications in Visual Studio (Creating a .NET Connector)

In this exercise you will create a Business Data Connectivity Model with Visual Studio 2010 that will allow clients to access external data within a SharePoint site.

1. Start Visual Studio 2010.
2. Create a new project by selecting File » New » Project from the main menu.
3. In the New Project dialog, select the SharePoint » 2010 » Business Data Connectivity Model template.
4. Name the project ProductModel and click the OK button.
5. In the SharePoint Customization Wizard, enter https://intranet.contoso.com/sites/BCSLab as the target debugging site.

6. When the project opens, you will see the definition for a single external content type named Entity1.

   Figure 11

   Entity 1

7. First, rename the provided external content type to something more useful. Right-click Entity1 in the Designer and select Properties. Then, in the Properties window, change the name of the entity to Product.

   Figure 12

   Product entity properties

8. Now you need to make changes to the external content type. This is done using the BDC Explorer tool window.

9. First, open the BDC Explorer tool window (Visual Studio View menu » Other Windows » BDC Explorer). Expand every node in the model so that you can see the entire model.

   Figure 13

   The BDC Explorer

10. When you click on a method (i.e. the items with the “purple flying eraser” icons), you also get a BDC Method Details view at the bottom of the developer environment. From here you can edit the type descriptors, identifiers, return types, and add and modify methods.

    Figure 14

    BDC Method Details

11. First change the name of the Identifier1.
    1. Select the Product entity in the designer.
    2. Right click the Identifier1 identifier in the Product entity and select Properties.

    3. Set its Name property to ID.

       Figure 15

       The Product entity

12. Now you need to change the input value used for finding a single record in the external content type.

    1. In the BDC Explorer, click on the ReadItem » id » Identifier1 node.

       Figure 16

       The BDC Explorer

    2. In the Property tool window, change his Name and Identifier properties to ID:(Note: Identifier should already be set to ID)

       Figure 17

       Configure the Product entity

13. Now you need to make the exact same changes to the ReadList method’s returnParameter. (Note: Identifier should already be set to ID)

    Figure 18

    The Product entity in the BDC Explorer

14. Let’s also change the Message property and add a property to the entity. First make changes to the ReadList method and then we’ll copy them over to the ReadItem method.

    1. Right-click the Message node under ReadList » returnParameter » Entity1List » Entity1, select Properties and change its Name to Manufacturer.

       Figure 19

       Configure the Type Descriptors

    2. Next, right-click the Entity1 node under the ReadList method and select Add Type Descriptor. Assign the new node Name.

       Figure 20

       Configure the Type Descriptors

15. Using the same method, rename Entity1 into Product and rename Entity1List into ProductList.

    Figure 21

    The ReadList method

16. With these changes made, let’s apply them to the ReadItem method.

    1. Right-click ReadList » returnParameter » ProductList » Product node and select Copy.

       Figure 22

       Copy the Product entity

    2. Right-click the ReadItem » returnParameter and select Paste. When prompted to replace the type description, select Yes.
17. With the entity and finder methods created, it’s now time to write the code for the .NET Connector.
18. In the Solution Explorer, right-click the Entity1.cs/vb file and choose Rename. Give it the name Product.cs/vb. Answer Yes in the popup dialog.
19. In the Solution Explorer, double-click the Product.cs/vb file to open the code window.
20. Change the property definitions to appear as follows (i.e. remove the existing ones and replace them with these):

    C#

    public partial class Product { public string ID { get; set; } public string Name { get; set; } public string Manufacturer { get; set; } }

    VB.NET

    Partial Public Class Product Private _ID As String Private _Name As String Private _Manufacturer As String Public Property ID() As String Get Return _ID End Get Set(ByVal value As String) _ID = value End Set End Property Public Property Name() As String Get Return _Name End Get Set(ByVal value As String) _Name = value End Set End Property Public Property Manufacturer() As String Get Return _Manufacturer End Get Set(ByVal value As String) _Manufacturer = value End Set End Property End Class
21. In the Solution Explorer, right-click the Entity1Service.cs/vb file and rename it to ProductService.cs/vb.
22. In the Solution Explorer, open the code window for the ProductService.cs/vb file.

23. Delete all of the existing code within the class and replace it with the following

    C#

    public class ProductService { private static string GetData() { StringBuilder xml = new StringBuilder(); xml.Append("<Products>"); xml.Append("<Product ID=\"1\" Manufacturer=\"Microsoft\" Name=\"XBox-360\" />"); xml.Append("<Product ID=\"2\" Manufacturer=\"Seagate\" Name=\"Harddrive\" />"); xml.Append("<Product ID=\"3\" Manufacturer=\"Dell\" Name=\"Laptop\" />"); xml.Append("<Product ID=\"4\" Manufacturer=\"Microsoft\" Name=\"Zune\" />"); xml.Append("</Products>"); return xml.ToString(); } public static Product ReadItem(string id) { XDocument d = XDocument.Parse(GetData()); var q = from c in d.Descendants("Product") where c.Attribute("ID").Equals(id) select new { ID = c.Attribute("ID").Value, Name = c.Attribute("Name").Value, Manufacturer = c.Attribute("Manufacturer").Value }; Product product = new Product(); product.ID = q.First().ID; product.Name = q.First().Name; product.Manufacturer = q.First().Manufacturer; return product; } public static IEnumerable<Product> ReadList() { XDocument d = XDocument.Parse(GetData()); var q = from c in d.Descendants("Product") select new { ID = c.Attribute("ID").Value, Name = c.Attribute("Name").Value, Manufacturer = c.Attribute("Manufacturer").Value }; List<Product> products = new List<Product>(); foreach (var p in q) { Product product = new Product(); product.ID = p.ID; product.Name = p.Name; product.Manufacturer = p.Manufacturer; products.Add(product); } return products; } }

    VB.NET

    Public Class ProductService Private Shared Function GetData() As String Dim xml As New StringBuilder() xml.Append("<Products>") xml.Append( _ "<Product ID=""1"" Manufacturer=""Microsoft"" Name=""XBox-360"" />") xml.Append( _ "<Product ID=""2"" Manufacturer=""Seagate"" Name=""Harddrive"" />") xml.Append( _ "<Product ID=""3"" Manufacturer=""Dell"" Name=""Laptop"" />") xml.Append( _

    "<Product ID=""4"" Manufacturer=""Microsoft"" Name=""Zune"" />") xml.Append("</Products>") Return xml.ToString() End Function Public Shared Function ReadItem(ByVal id As String) As Product Dim d As XDocument = XDocument.Parse(GetData()) Dim q = From c In d.Descendants("Product") _ Where c.Attribute("ID").Equals(id) _ Select New With { _ .ID = c.Attribute("ID").Value, _ .Name = c.Attribute("Name").Value, _ .Manufacturer = c.Attribute("Manufacturer").Value _ } Dim product As New Product() product.ID = q.First().ID product.Name = q.First().Name product.Manufacturer = q.First().Manufacturer Return product End Function Public Shared Function ReadList() As IEnumerable(Of Product) Dim d As XDocument = XDocument.Parse(GetData()) Dim q = From c In d.Descendants("Product") _ Select New With { _ .ID = c.Attribute("ID").Value, _ .Name = c.Attribute("Name").Value, _ .Manufacturer = c.Attribute("Manufacturer").Value _ } Dim products As New List(Of Product)() For Each p In q Dim product As New Product() product.ID = p.ID product.Name = p.Name product.Manufacturer = p.Manufacturer products.Add(product) Next Return products End Function End Class
24. When the project is complete, try to build the project.
25. Once the project builds successfully, right click the project in the Solution Explorer and select Deploy from the context menu.
26. In the browser go back to the https://intranet.contoso.com/sites/BCSLab site and create a new External List based on the deployed Product model using the same process as the previous exercise.
    1. Create a list based on the External List type with the Name: set to VSProducts and the External Content Type: set to ProductModel.Product (BdcModel1).
    2. Although the new list was created, you have been denied access by Business Data Connectivity.
27. Next we must configure the security settings on the new BCS application we just created:
    1. Open SharePoint 2010 Central Administration
    2. In the Application Management section select Manage service applications
    3. Underneath the Name column click on the Business Data Connectivity Service hyperlink
    4. On the Service Application Information screen, expand the Product application’s dropdown arrow and select Set Permissions
    5. First we will add the Contoso\Administrator account to grant SetPermissions rights to the appropriate person. (Note: If we did not grant an account SetPermissions rights, we could very well create a non-manageable object. SharePoint will error out if you do not do this on the Set Object Permissions Page).
    6. On the Set Object Permissions dialog box type Administrator into the first text box and click Add.
    7. Now in the Permissions for All Authenticated Users: area, place a check in the Set Permissions permission check box.
    8. On the Set Object Permissions dialog box type All Authenticated Users into the first text box and click Add.
    9. Now in the Permissions for All Authenticated Users: area, place a check in the Execute permission check box and click OK.(Note: the minimum permission anyone needs to access the data contained in a BCS application is Execute. Users MUST have this BCS right regardless of their level of access to the site where the application data is being surfaced or they will be denied access to the data.)

28. Now that permissions are configured, return to the BCSLab VSProducts List: https://intranet.contoso.com/sites/BCSLab/Lists/VSProducts

    Figure 23

    The VSProducts list

    Note:

    In this exercise you created a custom .NET Connector external content type in Visual Studio and an External Lists based off this external content type.