Exercise 3: Working with BCS Data Offline

In this exercise you will use the Customers External List to populate a customer drop down in a custom Outlook Form Region. Since user’s often take Outlook offline, the offline capabilities of SharePoint Workspace will cache the customers list locally.

Task 1 – Take the Customers list offline

In this task, add the Customers list to SharePoint Workspace so customers are available when no connection to the SharePoint site exists.

1. Sync the Flat File Customers list with SharePoint Workspace
   1. In Internet Explorer navigate to https://intranet.contoso.com/sites/BCSOffice
   2. Click the Flat File Customers link in the Navigation list to view the flat file data
   3. In the List ribbon tab, click the Sync to SharePoint Workspace button located in the Connect & Export group
   4. When asked if you want to allow the sync, click Yes
   5. If you are asked if you want to install an add-in, click the Install button

Task 2 – Update the Outlook Form Region

In this task, you will update the code in the Outlook Form Region and allow it to access the cached customer list using the BCS APIs.

1. Open the starter OutlookFormRegion project in Visual Studio 2010
   1. Open the OutlookFormRegion.sln file in the %Office2010DeveloperTrainingKitPath%\Labs\BCSOffice\[language]\Source\Starter\OutlookFormRegion folder
   2. Once the solution is loaded, right click OutlookFormRegion in the Solution Explorer and select Add Reference
   3. Click the Browse tab and navigate to the C:\Program Files\Microsoft Office\Office14 folder and add references to the following assemblies
      1. Microsoft.BusinessData.dll
      2. Microsoft.Office.BusinessData.dll
      3. Microsoft.Office.BusinessApplications.Runtime.dll
   4. Right click OutlookFormRegion in the Solution Explorer and click Properties
   5. In the Application tab confirm that the Target framework is .NET Framework 4 if not, make it so. (VB, Compile tab, Advanced compile options… button)
      1. Click Yes when asked if you want to change the framework version
2. Create a new class named CustomerDataSource that will wrap all communication to the cached customer data
   1. Right click OutlookFormRegion in the Solution Explorer and click Add -> Class
   2. In the Add New Item dialog, set the Name to CustomerDataSource and click Add

   3. In the new class add the following using statements

      C#

      using Microsoft.Office.BusinessData.MetadataModel; using Microsoft.BusinessData.Runtime; using Microsoft.BusinessData.MetadataModel;

      Visual Basic

      Imports Microsoft.Office.BusinessData.MetadataModel Imports Microsoft.BusinessData.Runtime Imports Microsoft.BusinessData.MetadataModel

   4. Add the following fields to the CustomerDataSource class to track the BCS entities

      C#

      private IEntity m_entity; private ILobSystemInstance m_lobSystemInstance;

      Visual Basic

      Private m_entity As IEntity Private m_lobSystemInstance As ILobSystemInstance

   5. Add a constructor that will use the RemoteSharedFileBackedMetadataCatalog to access the metadata for the flat file customer entity

      C#

      public CustomerDataSource() { RemoteSharedFileBackedMetadataCatalog catalog = new RemoteSharedFileBackedMetadataCatalog(); m_entity = catalog.GetEntity( "CustomerExternalContentType.ExternalSystemModel", "Customer"); m_lobSystemInstance = m_entity.GetLobSystem(). GetLobSystemInstances()[0].Value; }

      Visual Basic

      Public Sub New() Dim catalog As New RemoteSharedFileBackedMetadataCatalog() m_entity = catalog.GetEntity("CustomerExternalContentType.ExternalSystemModel", "Customer") m_lobSystemInstance = m_entity.GetLobSystem().GetLobSystemInstances()(0).Value End Sub

   6. Add a GetCustomers method that returns the name of every customer in the flat file

      C#

      public IEnumerable<string> GetCustomers() { IEntityInstanceEnumerator items = m_entity.FindFiltered( m_entity.GetDefaultFinderFilters(), "ReadList", m_lobSystemInstance, OperationMode.CachedWithImmediateRefresh); List<string> results = new List<string>(); while (items.MoveNext()) results.Add(items.Current["Name"].ToString()); return results; }

      Visual Basic

      Public Function GetCustomers() As IEnumerable(Of String) Dim items As IEntityInstanceEnumerator = m_entity.FindFiltered(m_entity.GetDefaultFinderFilters(), "ReadList", m_lobSystemInstance, OperationMode.CachedWithImmediateRefresh) Dim results As New List(Of String)() Do While items.MoveNext() results.Add(items.Current("Name").ToString()) Loop Return results End Function

   7. Add an AddCustomer method that uses the BCS objects to create a new customer in the flat file

      C#

      public void AddCustomer(string name) { IFieldValueDictionary values = m_entity.GetCreatorView("Create").GetDefaultValues(); values["Name"] = name; m_entity.Create(values, m_lobSystemInstance); }

      Visual Basic

      Public Sub AddCustomer(ByVal name As String) Dim values As IFieldValueDictionary = m_entity.GetCreatorView("Create").GetDefaultValues() values("Name") = name m_entity.Create(values, m_lobSystemInstance) End Sub

3. Update the BillableTaskRegion code to use the customer list from BCS instead of a static list
   1. Right click BillableTaskRegion.cs(BillableTaskRegion.vb in case of VB) in the Solution Explorer and select View Code

   2. Add the following private field to the BillableTaskRegion class to initialize the CustomerDataSource object

      C#

      private CustomerDataSource m_customers = new CustomerDataSource();

      Visual Basic

      Private m_customers As New CustomerDataSource()

   3. Add the following code to the end of the BillableTaskRegion_FormRegionShowing method to initialize the lstCustomer drop down based on the BCS data

      C#

      lstCustomer.Items.Clear(); lstCustomer.Items.AddRange(m_customers.GetCustomers().ToArray());

      Visual Basic

      lstCustomer.Items.Clear() lstCustomer.Items.AddRange(m_customers.GetCustomers().ToArray())

4. Update the BillableTaskRegion code write any new customers to BCS when the form is closed
   1. Add the following code to the BillableTaskRegion_FormRegionClosed method

      C#

      private void BillableTaskRegion_FormRegionClosed(

      FakePre-d5d7e8d16b0a453682e813cf0670bcc6-fd083ccc03ae40a18fa8feb9f993b6e9FakePre-723e34dfad8d48149049a81da7a7c461-182f0bd20ab84bd1ac49afb93a423118 if (m_taskItem.Saved) if (lstCustomer.SelectedItem == null && !string.IsNullOrEmpty(lstCustomer.Text)) if (!m_customers.GetCustomers().Any( n => n == lstCustomer.Text)) m_customers.AddCustomer(lstCustomer.Text);FakePre-9662c9c4a8284d3ba76b525b00ee5eff-ae7c2715c01a495d90716dbbef42a6d2

      Visual Basic

      Private Sub BillableTaskRegion_FormRegionClosed(ByVal sender As Object, ByVal e As System.EventArgs)

      If m_taskItem.Saved Then If lstCustomer.SelectedItem Is Nothing AndAlso (Not String.IsNullOrEmpty(lstCustomer.Text)) Then If Not m_customers.GetCustomers().Any(Function(n) n = lstCustomer.Text) Then m_customers.AddCustomer(lstCustomer.Text) End If End If End IfFakePre-b1a1511b584f4f36a62004605c1317dc-c8f0595f42d04dea9340697a84ef98cd
      Note:

      This code only adds an item if the Outlook task was saved, the item that was selected is new, and the item does not already exist in the list

Exercise 3 Verification

In order to verify that you have correctly performed all steps in the above exercise, proceed as follows:

Test your work

Open Outlook and verify the customers list loads from data in BCS. Once the data is loaded, add a new value by manually entering a name in to the drop down combo box and verify the data exists in the flat file data source.

1. Start the add-in and verify the list of customers is loading from BCS
   1. Start Outlook by clicking Debug -> Start Without Debugging
   2. Create a new task in Outlook by clicking New Items -> Task in the Home ribbon tab
   3. In the new Task form, check the billable check box and open the Customer drop down

   4. Verify the following values are displayed from the flat file

      Figure 30

      Customers from Flat File

2. Add a new customer and verify it’s added to the flat file
   1. In the new task item, enter a customer of Contoso Inc.
   2. Save the task by clicking Save on the Task ribbon tab
   3. Open %Office2010DeveloperTrainingKitPath%\Labs\BCSOffice\Source\Customers.txt in notepad

   4. Verify that your company name. has been added to the end of the file

      Figure 31

      Updated Customers Flat File