Using the Custom Code option for BCS Meta Man

Introduction

In this tutorial I will show you how to connect to your External System using BCS Meta Man, allow BCS Meta Man to automatically generate the Model and .Net assembly for us and then we will customise the C# code of one of the methods.

Prerequisites

  • SharePoint Server 2010
  • Visual Studio 2010 Professional or higher
  • BCS Meta Man
  • AdventureWorks SQL Database

Walkthrough

  1. Open Visual Studio 2010
  2. Add a New Project
  3. Select ‘SharePoint’ > ‘Lightning Tools (2010)’ , now you can select the BCS Meta Man project type.
  4. Give your project a name i.e BCSMetaManCustomCodeDemo

    Create a BCS Meta Man SharePoint project

    [Please click the images for a larger view]

  5. Click ‘OK’
  6. On the next dialog box, enter the name of where you want to deploy your model, and make sure you select ‘Deploy as a farm solution’ , click ‘Finish’

    Deploy as a Farm Solution

  7. If prompted, click ‘OK’ on the licensing dialog

    Trial Message Box

  8. To show the ‘BCS Meta Man Data Source Explorer’ we need to enable it from the Menu item, this new window can be docked so it doesn’t get in your way.

    Open the BCS Meta Man Data Source Explorer

  9. Click the ‘Add Connection’ button to show the ‘Connection Dialog’
  10. Select the Data Source type, enter your Server name and also select whether to ‘Use Windows Authentication’ or you provide logon credentials, click ‘Connect’

    Connect to the database

  11. The Data Source Explorer will now be populated with your Server data

    See the tables and views available to use

  12. We will be working with the ‘Product’ table, to add it to the Model , just drag it from the ‘Data Source Explorer’ onto the ‘Diagram’

    Drag and drop a table onto the design surface

  13. When you drop the table you will be shown the following dialog, we want to choose ‘.Net Assembly’ , click ‘OK’
    (Database can be used if you want to create a model which connects straight to your External System without using a .Net Assembly i.e no code solution)

    Choose the model type

  14. Accept the default ‘Identifiers’ by clicking ‘Next’

    Accept the identifiers selected

  15. Accept the default 3 methods to be created, click ‘Generate’

    Accept the methods

    The default 3 methods are:

    • Finder – Returns all items
    • Specific Finder – Returns a single item by identifier
    • IdEnumerator – Returns just the Identifiers for all of the items
  16. Watch as the code is generated for you, think of the time it is saving! 🙂
  17. Right click on the Generated External Content Type (ECT) and click ‘Manage Entity’

    Manage Entity menu on External Content Type

  18. This will display the Entity Management Dialog where you want to click on the ‘Use Custom Code’ checkbox

    Entity Management Dialog - Selecting Use Custom Code

  19. Click ‘Update’ to save changes, this will change the implementation of all of the methods to use a custom class, i.e the Finder Method will change from

    [BcsMethodType(MethodType.Finder)]
    public staticIEnumerable<GetAllProductEntitysProperties> GetAllProductEntitys()
    {
       AdventureWorksContext dcontext = new AdventureWorksContext(ConnectionString);
        var records = from record in dcontext.Product
                      select newGetAllProductEntitysProperties
                    
    {
                          ProductID = record.ProductID,
                          Name = record.Name,
                          ProductNumber = record.ProductNumber,
                          Color = record.Color,
                          StandardCost = record.StandardCost,
                          ListPrice = record.ListPrice,
                          Size = record.Size,
                          Weight = record.Weight,
                          ProductCategoryID = record.ProductCategoryID,
                          ProductModelID = record.ProductModelID,
                          SellStartDate = record.SellStartDate,
                          SellEndDate = record.SellEndDate,
                          DiscontinuedDate = record.DiscontinuedDate,
                          ThumbNailPhoto = record.ThumbNailPhoto,
                          ThumbnailPhotoFileName = record.ThumbnailPhotoFileName,
                          rowguid = record.rowguid,
                          ModifiedDate = record.ModifiedDate
                      };
        return records;
    }

    To:

    [BcsMethodType(MethodType.Finder)]
    public staticIEnumerable<GetAllProductEntitysProperties> GetAllProductEntitys()
    {
        // IsCustomCode == true, calling CustomGetAllProductEntitys ()
        // Provide your custom implementation with following signature:
        // System.Collections.Generic.IEnumerable<BCSMetaManCustomCodeDemo.ProductsModel.GetAllProductEntitysProperties> CustomGetAllProductEntitys ()
        // You can call DefaultGetAllProductEntitys for the default implementation.
      
    return CustomGetAllProductEntitys();
    }

    private static IEnumerable<GetAllProductEntitysProperties> DefaultGetAllProductEntitys()
    {
        AdventureWorksContext dcontext = new AdventureWorksContext(ConnectionString);
        var records = from record in dcontext.Product
                      select new GetAllProductEntitysProperties
                    
    {
                          ProductID = record.ProductID,
                          Name = record.Name,
                          ProductNumber = record.ProductNumber,
                          Color = record.Color,
                          StandardCost = record.StandardCost,
                          ListPrice = record.ListPrice,
                          Size = record.Size,
                          Weight = record.Weight,
                          ProductCategoryID = record.ProductCategoryID,
                          ProductModelID = record.ProductModelID,
                          SellStartDate = record.SellStartDate,
                          SellEndDate = record.SellEndDate,
                          DiscontinuedDate = record.DiscontinuedDate,
                          ThumbNailPhoto = record.ThumbNailPhoto,
                          ThumbnailPhotoFileName = record.ThumbnailPhotoFileName,
                          rowguid = record.rowguid,
                          ModifiedDate = record.ModifiedDate
                      };
        return records;
    }

  20. BCS Meta Man will also create a partial class for you containing the ‘Custom’ methods

    Partial class with custom methods

  21. By default the ‘Custom’ methods will call the ‘Default’ methods for your External Content Type, which contain the original BCS Meta Man implementation.
  22. To customise a method we can copy the contents from the Default Method and insert it into our custom method and then apply our changes or we can call the default method and use Linq to alter the returned data set. In this example I am just filtering the results down again to only allow people with a Lightning Tools email address to only to view yellow Products – you can however see how this could be used to add your own security trimming of data.

    private static
    IEnumerable<GetAllSalesLT_ProductEntitysProperties> CustomGetAllSalesLT_ProductEntitys()
      {
          IEnumerable<GetAllSalesLT_ProductEntitysProperties> products = DefaultGetAllSalesLT_ProductEntitys();

          SPUser currentUser = SPContext.Current.Web.CurrentUser;

          if(currentUser.Email.Contains(“@example.com”))
          {
              products = products.Where(product => product.Color == “Yellow”);
          }

          // Finder Method: Used to return all, or filtered subset of, records
        
    return products;
      }

  23. Press F5 to deploy, this will load up your SharePoint Page once deployed
  24. Add a new Business Data List Web Part to your SharePoint page
  25. Click on the ‘Open the tool pane’ link
  26. Click on the icon to show the available External Content Types

    Select the External Content Type

  27. Select our BCSMetaManCustomCodeDemo.ProductsModel.Product External Content Type, click OK
  28. Click ‘OK’ on the tool pane
  29. Your External System data is now displayed in the SharePoint Web Part – As I am logged in with a user with a Lightning Tools email address I get the filtered data

    Filtered Business Data List by user email address

    when logged in as another user (without @lighthningtools)

    All data being returned to Business Data List

<phill/>