Walkthrough: Using BCS Reusable Code Components in a Declarative Solution

  • Article

You can extend an intermediate declarative Outlook solution further by displaying custom external data parts, code actions, and by using custom ribbon managers. The SharePoint 2010 SDK includes the Code Sample: AdventureWorks2008 Declarative Outlook Solution Reusable Components.

Applies to: SharePoint Server 2010

This sample defines a custom ribbon manager, a custom external data part, and a code action. For the steps to create these code components, see Creating and Using Reusable Code Components in a Declarative Outlook Solution section in this topic. The first part of this topic explains how to reference and use existing code components, in an intermediate declarative Outlook solution. The second part contains the steps to create and use the reusable code components in an intermediate declarative Outlook solution.

Important

Before packaging the solution, you must copy the Microsoft .NET Framework assemblies that define these code components to the Solution Artifacts folder for the declarative solution.

At a Glance: Using Existing Code Components in an Intermediate Declarative Outlook Solution

Using a Custom Code Action

In the OIR.config file, you can use a custom code action as shown in the following example.

<Declarative:CodeMethodAction Name ="CreateTaskAction" MethodType ="Custom" 
  MethodName="NewCustomVisitTask" 
  QualifiedTypeName="ContosoCustomer.CustomCodeAction, ContosoCustomer, 
  Version=1.0.0.0, Culture=neutral, PublicKeyToken=e355b6f7ef818b12">
  <Declarative:Parameters>
    <Declarative:ConstantParameter Name="Para1" 
                                   Value="EditRelatedOrderHeader" 
                                   ValueType="System.String"/>
  </Declarative:Parameters>
</Declarative:CodeMethodAction>

Using a Custom External Data Part in a Layout

In the layout file, you can refer to a custom external data part as shown in the following code.

<?xml version="1.0" encoding="utf-8" ?>
<Container ContainerType="Stack" 
  xmlns="https://schemas.microsoft.com/office/2009/05/BusinessApplications/Layout" 
  xmlns:loc="https://schemas.microsoft.com/office/2009/05/BusinessApplications/Localization">
  <CustomProperties />
  <Children>
    <OBPart DataSourceName="PrimaryEntityNameInContext" PartType="Custom" 
            Text="Related Order" FillParent="true" 
            QualifiedTypeName="ContosoCustomer.CustomOBPart, ContosoCustomer, 
            Version=1.0.0.0, Culture=neutral, PublicKeyToken=e355b6f7ef818b12">
      <CustomProperties />
    </OBPart>
  </Children>
</Container>

Using a Custom RibbonManager

In the OIR.config file, specify the custom ribbon manager as shown in the following code.

<SolutionSettings SolutionId="ContosoSalesManager" 
                  SolutionDisplayName="Contoso Sales Manager" 
                  SolutionVersion="1.0.0.0" 
                  xsl:type="Declarative:DeclarativeSolutionSettings" 
                  CustomRibbonManager="ContosoCustomer.CustomRibbonManager, 
                  ContosoCustomer, Version=1.0.0.0, Culture=neutral, 
                  PublicKeyToken=e355b6f7ef818b12"/>

Creating and Using Reusable Code Components in a Declarative Outlook Solution

This section contains the steps to create and use reusable code components, namely a custom code action, a custom external data part, and a custom ribbon manager. To create the solution in this walkthrough, you must first follow the steps in Walkthrough: Creating an Intermediate Declarative Outlook Solution to create the solution artifacts that you will modify in this walkthrough.

The code snippets used in this walkthrough are the following:

Prerequisites

To create, build, and deploy the solution

  1. Create a C# Class Library project in Visual Studio 2010, and then name it ContosoCustomer.

  2. Add the following references to your project:

    • Microsoft.Office.Interop.Outlook

    • Office

    • System.Windows.Forms

  3. Add the following assemblies that are specific to Microsoft Business Connectivity Services (BCS) from the Office installation folder (the path is usually C:\Program Files\Microsoft Office\Office14\, but might be different in your environment):

    • Microsoft.BusinessData.dll

    • Microsoft.Office.BusinessApplications.Runtime.dll

    • Microsoft.Office.BusinessApplications.RuntimeUi.dll

  4. Add a new class file to your project and name it CustomCodeAction.cs.

  5. Replace the code in CustomCodeAction.cs with the code from Code Snippet: Custom Code Action.

  6. Add a new class file to your project and name it CustomRibbonManager.cs.

  7. Replace the code in CustomRibbonManager.cs with the code from Code Snippet: Custom Ribbon Manager.

  8. Add a new User Control to your project and name it CustomOBPart.cs.

  9. View the code of the CustomOBPart.cs file and replace its contents with the code from the first example in Code Snippet: Custom External Data Part.

  10. Replace the code of CustomOBPart.Designer.cs with the code from the second example in Code Snippet: Custom External Data Part.

  11. Sign the solution.

    In the Project properties, on the Signing tab, select Sign the assembly, and then create a key file. You can choose any key file name and password.

  12. Build the solution.

    This generates the assembly in the bin\Debug (or bin\Release) folder in your project folder.

  13. Copy the assembly to your solution artifacts folder. The assembly was generated when you built the solution in the previous step.

  14. Open the OIR.config file from your solution artifacts folder and add the following custom code action XML before the ContextDefinition end tag of OutlookContactCustomer.

    You should have a solution artifacts folder after following the steps in Walkthrough: Creating an Intermediate Declarative Outlook Solution.

    <Declarative:CodeMethodAction Name ="EditRelatedOrderHeaderAction" 
                              MethodType ="ShowTaskpaneLayout">
  <Declarative:Parameters>
    <Declarative:ConstantParameter Name="Para1" 
                                   Value="EditRelatedOrderHeader" 
                                   ValueType="System.String"/>
  </Declarative:Parameters>
</Declarative:CodeMethodAction>
<Declarative:CodeMethodAction 
  Name ="CreateTaskAction" MethodType ="Custom" 
  MethodName="NewCustomVisitTask" 
  QualifiedTypeName="ContosoCustomer.CustomCodeAction, ContosoCustomer, 
  Version=1.0.0.0, Culture=neutral, PublicKeyToken=e355b6f7ef818b12">
</Declarative:CodeMethodAction>

    Edit the custom code action XML. In the CodeMethodAction element, replace the value of the QualifiedTypeName attribute with the assembly-qualified name of the CustomCodeAction type of the assembly generated when you built the solution in a previous step.

  15. Open Ribbon.xml from your solution artifacts folder and add the following tab and ribbon button definition for CreateTaskAction inside the tabs element.

    <tab idMso="TabContact">
  <group id="ContosoCustomerSalesGroupID"
         label="Contoso Customer Sales" getVisible="GetVisible" tag="Context[OutlookContactCustomer.ContosoCustomerSalesGroupID]">
    <button id="NewCustomerVisitTaskButton"
                 size="large"
                 label="New Customer Visit Task"
                 onAction="OnAction"
                 image="TaskItem.bmp"
                 getEnabled ="GetEnabled"
                 tag="Action[OutlookContactCustomer.CreateTaskAction]"
                  />
  </group>
</tab>

  16. In Ribbon.xml, add the following ribbon button definition for EditRelatedOrderHeaderAction within the ContosoCustomerSalesGroupID group of the ContosoSalesSolutionTabID tab.

    <button id="EditRelatedOrderHeaderButton"
        size="large"
        label="Edit Customer Orders"
        onAction="OnAction"
        image="ArrowGreen.jpg"
        getEnabled ="GetEnabled"
        tag="Action[OutlookContactCustomer.EditRelatedOrderHeaderAction]"
/>

  17. Add the CustomRibbonManager attribute to the SolutionSettings element in the OIR.config file as shown in the following XML example.

    <SolutionSettings 
  SolutionId="ContosoSalesManager"
  SolutionDisplayName="Contoso Sales Manager"
  SolutionVersion="1.0.0.0"
  xsl:type="Declarative:DeclarativeSolutionSettings"
  CustomRibbonManager="ContosoCustomer.CustomRibbonManager, ContosoCustomer, 
  Version=1.0.0.0, Culture=neutral, PublicKeyToken=e355b6f7ef818b12"/>

  18. Replace the value of the CustomRibbonManager attribute with the assembly-qualified name of the CustomRibbonManager type of the assembly generated when you built the solution in a previous step.

  19. Create a file named EditRelatedOrderHeader.xml in your solution artifacts folder and add the following custom external data part XML example to it. Then, save the file to the solution artifacts folder.

    <?xml version="1.0" encoding="utf-8" ?>
<Container ContainerType="Stack"
  xmlns="https://schemas.microsoft.com/office/2009/05/BusinessApplications/Layout"
  xmlns:loc="https://schemas.microsoft.com/office/2009/05/BusinessApplications/Localization">
  <CustomProperties />
  <Children>
    <OBPart DataSourceName="PrimaryEntityNameInContext" PartType="Custom"
            Text="Related Order" FillParent="true"
            QualifiedTypeName="ContosoCustomer.CustomOBPart, ContosoCustomer, 
            Version=1.0.0.0, Culture=neutral, PublicKeyToken=e355b6f7ef818b12">
      <CustomProperties />
    </OBPart>
  </Children>
</Container>

  20. Edit the EditRelatedOrderHeader.xml file. In the OBPart element, replace the value of the QualifiedTypeName attribute with the assembly-qualified name of the CustomOBPart type of the assembly generated when you built the solution in a previous step.

  21. Add the layout to the OIR.config file. In the OIR.config file, add the following inside the Layouts element before the ContextDefinition end tag of OutlookContactCustomer.

    <Declarative:Layout Name="EditRelatedOrderHeader" 
                    LayoutFileName="EditRelatedOrderHeader">
</Declarative:Layout>

  22. Package your solution and then deploy it.

    1. Start the BCS Solution Packaging Tool.

    2. Provide a name and version for your solution, and select Outlook Intermediate Declarative Solution for the solution type.

    3. Select the solution artifacts folder as the Source Folder Path.

    4. Create a folder on your local computer and select it as the Output Folder Path.

    5. Click Package to package the solution.

    6. Click Deploy to deploy the solution.

Note

The XML examples referred to previously already contain the assembly-qualified name of the CustomCodeAction, CustomRibbonManager, and CustomOBPart classes for the CodeMethodAction, CustomRibbonManager, and OBPart XML values, respectively. However, you need to update the assembly-qualified name values because the PublicKeyToken value will be different after you signed the assembly of this solution. Also, if you used a different namespace name or class names, the assembly-qualified names will be different and have to be updated.