BCS Model in Visual Studio 2010 – SpecificFinder and IdEnumerator

Welcome back! Hopefully you managed to follow along with our first article and have successfully created your Department Entity and deployed it to SharePoint:

Business Data Model in Visual Studio 2010.

Now we are going to extend our BCS model and our department entity to create the SpecificFinder and IdEnumerator methods. First we are going to setup our SpecificFinder…

1, Right click on the Methods section of your Department Entity and choose to Add new Method. Give this method a name of GetDepartmentById

image

2, Open up our DepartmentService.cs and you’ll see a new method created for us. Change the method signature so that it accepts a parameter and also returns a Department object:

public static Department GetDepartmentById(Int16 departmentId)

3, Add the following code within your method to replace the Not Implemented Exception:

DataClasses1DataContext db = new DataClasses1DataContext(“server=localhost;database=adventureworks2000;uid=***;pwd=***”);

var dbDepartment = db.Departments.SingleOrDefault(d => d.DepartmentID == departmentId);

return new Department 
                  {
                      DepartmentId = dbDepartment.DepartmentID,
                      Name = dbDepartment.Name,
                      GroupName = dbDepartment.GroupName
                  };

 

We have to do a little more work because we want to return our own Department class rather than the one LINQ 2 SQL generates for us but as outlined in the first article I have just found this a better approach.

Now we need to fix up our BCS Model

4, Move back to our BCS model and click on the GetDepartmentById method. In the BDC Method Details window choose to add a new parameter. Now using the BDC Explorer window open up the tree until you get to your new parameter. Select it, and using the properties window change it’s name to departmentId. Also click on the Type Descriptor below it and set the following values:

Name : departmentId
Type Name : System.Int16
Identifier : DepartmentId

image

5, Now we need to create our return parameter. Back to the  BDC Method Details window and choose to create another new parameter for our GetDepartmentById method

6, Select this new parameter in the BDC Explorer window, and change it’s name to Department and the parameter direction to be Return.

7, Now this is where the BDC Explorer is pretty neat. Expand the other Method within our Department Entity called GetDepartments. Right click on the Department Type Descriptor and choose Copy. Now you can right click on the Department Parameter of our GetDepartmentById method and choose to Paste

You will be asked if you want to replace the existing Type Descriptor – press yes for this, and now you will have your Department Type Descriptor and all the field Type Descriptors copied for you saving you a bit of manual work.

image

and the nice end result:

image

Be aware that if you have any errors within the Type Descriptor(s) that you copy these will be replicated to the other method. That’s why it is always better to build the Finder method and test that before moving forward and copying and pasting Type Descriptors around.

8, Now we just need to create a MethodInstance. Back to the BDC Method Details window and choose to create a new MethodInstance for our GetDepartmentById method. Set the following properties in the Property Window:

Type : SpecificFinder
Default : True
Default Display Name : Single Department
Return Parameter Name : Department
Return Type Descriptor : Department

9, Before we can test and deploy we need to clean up our DepartmentService.cs class again.

The BCS designer expects you to define your methods, parameters and type descriptors before you right any code. This is why if you edit your method stub with the return object and input parameters and then modify your BCS method it will re-generate a new stub. I much prefer writing my C# code and then generating the BCS model second rather then having to do the BCS model first. If you do it the same way that I do, make sure you check back in your Service class to clear up any method stubs that may have been re-generated.

10, Once you have removed the extra method try to compile your solution, and if that works press F5 to build and deploy the WSP to SharePoint

You can test that your Specific Finder method is working by either adding a Business Data Item web part and configuring it, or creating an External List and clicking on a particular row to get a pop up view (as I have done in the image below)

image

11, So our Specific Finder BCS method works – Great! Now let’s go back to Visual Studio and configure our IdEnumerator method. Right click in the Methods section of our Department entity and add a new method called GetDepartmentIds

image

12, Pop into the DepartmentService.cs class and change the method signature of GetDepartmentIds to be:

public static IEnumerable<short> GetDepartmentIds()

13, Remember our IdEnumerator method is only supposed to return the primary key values of the rows we want SharePoint search to index and crawl. Therefore we only want some simple code within this method:

DataClasses1DataContext db = new DataClasses1DataContext(“server=localhost;database=adventureworks2000;uid=***;pwd=***”);

return from d in db.Departments
                    select d.DepartmentID;

14, Now we need to build up our BCS model to reflect the data we are returning so switch back to the BCS model view. Select the GetDepartmentIds method and in the BDC Details window create a new parameter.

15, In the BDC Explorer, expand the tree so you can select the parameter just created. Change it’s direction in the Properties window to be Return.

16, Select the parameterTypeDescriptor below our parameter. Set its values to:

Name : DepartmentIds
Type Name : System.Collections.Generic.IEnumerable`1[[System.Int16]]
IsCollection : True

17, Right click on the DepartmentIds Type Descriptor in the tree and choose to Add new Type Descriptor. Set this type descriptors properties to be:

Name : DepartmentId
Type Name : System.Int16
Identifier : DepartmentId

18, Finally we need to add a MethodInstance for our method, so in the BDC Method details window click to add a new MethodInstance. With the method instance selected set the following property values:

Type : IdEnumerator
Default : True
Return Parameter Name : parameter
Return Type Descriptor : DepartmentIds

 

Remember to clear up the GetDepartmentIds method our model will have created again in DepartmentService.cs.

19, There is a new property we need to set for our LobSystemInstance to get it to show as an application that can be crawled by the SharePoint 2010 indexer. This property is called ShowInSearchUI.

To set this, expand the BCS model in the BDC Explorer until you see the LobSystemInstance node

image

20, In the Properties window, set a Custom Property to be ShowInSearchUI and to have a type of System.String. The property doesn’t actually need to have a value, it just needs to exist

image

21, And that is it, we can now press F5 to package our model into a WSP and deploy it to SharePoint. We do have a few extra steps to do within the SharePoint UI however to get our Departments appearing in our Search results.

22, Previously in the Business Data Catalog a Profile Page for your Entity was created automatically. Using the steps above this doesn’t happen automatically in the BCS so we need to do a manual step to get it to work. Open up SharePoint 2010 Central Administration, click on Manage Service Applications. In the Service Applications screen click on the Business Data Connectivity Service Application link to open up it’s administration page.

23, On the Ribbon, click the Edit tab, and then the Configure button. A form will pop up that asks us to enter a URL for the profile pages. As the page explains it would be good to create a place specifically for these pages, but for now lets just enter the same url as our SharePoint site – for me it’s http://localhost.

image

Click OK to close the form.

24, Now we need to get our External Content Type to create its profile page. Hover the mouse over our department ECT and from the content drop down pick ‘Create/Upgrade Profile Page’

image

Click OK on the dialog message that shows up. Now our profile page will be created under the site we set in step 23.

25, Now we want to check our Entity is crawlable, click on our Department External Content Type and check the Crawlable property is set to Yes

image

26, Now we need to set our BCS application as a Search Content Source. Go back to the Manage Service Applications page and click the Search Service Application link

27, In the left hand sidebar menu click the Content Sources link, then in the next page click the New Content Source link

28, Give your new Content Source a name, and select it’s type to be Line of Business Data. Upon selecting this the UI will refresh and the next section down will refresh to show External Data Sources. Select BCS application you want to crawl in our case BdcModel1

image

If your application doesn’t appear here then you need to check the ShowInSearchUI has been properly set.

29, Setup the Crawl Schedules if you wish, and finally tick the last box to perform a full crawl now, then click the OK button.

30, Once the crawl has finished, check the Crawl Log for your BCS content source

image

You should have 18 successful crawl entries – one for each department.

31, If you’ve created a Team Site as the root site in your Site Collection you’ll need to go and create a Basic Search Center site for it. Once this has been done you can go to your Search Center site, search for Engineering and you’ll see our the Engineering department being returned from our Department External Content Type.

image

32, You can hook up this new Search Center to your Team Site by moving back to your Team Site and going

Site Actions –> Site Settings –> Search Settings

and you can add in the URL of your Search Center Site for the results page

 

Wow – quite a few steps – hopefully you’ve followed along and have this all working nicely. Keep checking back as we’ll have plenty more blog posts coming, next steps will be writing back and creating associations.

If you’re looking for a way of setting this up with a few less steps make sure you check out BCS Meta Man!

<nick/>

[The information contained above is correct as of 04th December 2009. As of writing we are currently working with beta products and although we will do our best to update this post where necessary please note that by the time you are reading this some things will have changed]