Summary

It is a common scenario to use charts in the PowerPoint presentation as a way of summarizing the data in and make it more readable and actionable. Frequently, the data used to generate the charts will often reside in an external system such as a database, CRM or an ERP system. This involves switching between the applications and is often time consuming in the getting the data. Also it may be desirable to get the up-to-date information on such charts.

For example, many sales departments need to report sales figures in a regular weekly or monthly meeting.  Typically this would be presented as a chart in a PowerPoint presentation. This data is often stored in an external database. The sales manager can use the add-in to create the chart and the add-in will in turn use the BCS API to get the data. We can develop the PowerPoint add-in using Visual Studio 2010. This add-in will connect to the back-end data using Business Connectivity Services (BCS), a set of capabilities that ship as part of Office and SharePoint 2010.Following sections explain how to develop this add in.

 Important Note:

I co-wrote this article with Eric White .Many thanks to him for providing the insights. Many thanks to Brad Stevenson, Juan Balmori Labra , Russell Palmer and Thomas Mechelke for reviewing this article. They are the program managers behind the article.

This article will be published on MSDN some time.

About the sample

The sample in the article is a PowerPoint add-in. If you follow the steps mentioned in this document you will be creating an add-in that would insert the new slide and the chart. This chart will use the data that is fetched using the BCS API to get the data. This data is stored in the SQL Server. To make the example simple we will use the data from the “SalesTerritory” table. This table contains the sales data across various territories in the United States.

This add-in contains a ribbon tab “BCS” which has a button “Add External Data to Chart”. 

When the user clicks on this button, the add-in will open the custom task pane.

This custom task pane is populated with the external content types available in the business connectivity services cache. It uses the BCS client object model to get the data from the external system. 

When you click on the button “Insert Chart” it will insert the new slide and the chart by using the values selected in the custom task pane and inserts it in the new slide like this.

Finally you will use the BCS Solution Package Tool to package and deploy the solution to ensure that the metadata model is available to the client before invoking the BCS runtime APIs.

The following section describes how to generate such a chart.

 Generating Chart in PowerPoint Add-in

In Office 2010, there is a chart object. The chart object mainly surfaces a chart on the slide and renders a graph with the supplied values. For more information about the chart object, see MSDN blog post, Chart Object.

In our sample each chart draws the trend of “Last Year Sales” to “Year to Date Sales” using the following lines of code.

public void InsertChart(ChartDataObject chartDataObject)

{

    Chart chart = null;

    Shape shape = null;

    Microsoft.Office.Interop.Excel.Workbook Workbook = null;

    Microsoft.Office.Interop.Excel.Application Application = null;

    try

    {

        //Add the new slide

        Slide slide = this.Application.ActivePresentation.Slides.Add(this.Application.ActivePresentation.Slides.Count + 1, PpSlideLayout.ppLayoutChart);

        //Insert the chart

        shape = slide.Shapes.AddChart(Office.XlChartType.xlLine);

        chart = shape.Chart;

        //Clear the chart contents

        chart.ChartArea.ClearContents();

        object[] Values = new object[chartDataObject.XValues.Count()];

        for (int i = 0; i < chartDataObject.Data.Rows.Count; i++)

        {

            for (int j = 0; j < chartDataObject.XValues.Length; j++)

            {

                Values[j] = chartDataObject.Data.Rows[i][chartDataObject.XValues[j].ToString()];

            }

            SeriesCollection SeriesCollection = chart.SeriesCollection() as SeriesCollection;

            //Create new series based on the data

            Series Series = SeriesCollection.NewSeries();

            Series.Name = chartDataObject.Data.Rows[i][chartDataObject.SeriesName].ToString();

            Series.XValues = chartDataObject.XValues;

            Series.Values = Values;

        }

        //Activate the chart to refresh with the fresh data.

        chart.ChartData.Activate();

    }

    finally

    {

        //Close the Excel Workbook and clean up resources.

        if (chart != null && chart.ChartData != null)

        {

            Workbook = chart.ChartData.Workbook as Microsoft.Office.Interop.Excel.Workbook;

            if (Workbook != null)

                Application = Workbook.Application;

            if (Application != null && Workbook!=null)

            {

                //Quit Excel Application

                Application.Quit();

                Application = null;

                Workbook = null;

                //Force the GC, this is recommended for releasing the resources.

                //Quitting Excel doesnt ensure resources are cleaned immediatly

                GC.Collect();

                GC.WaitForPendingFinalizers();

                //Repeated calls is necessary is because the memory for the Excel

                //would have survived for the first pass.

                //Hence the second try to recalim completely.

                GC.Collect();

                GC.WaitForPendingFinalizers();

            }

        }

    }

}

The add in will use BCS to get the data for the chart. Following section provides an overview of BCS.

Overview of BCS

Business Connectivity Services (BCS) in SharePoint 2010 is the successor of Business Data Catalog that is available in MOSS 2007, with Enterprise Client Access License. It has rich designer capabilities. 

For more information about the overview of BCS, see MSDN documentation Overview of Business Connectivity Services. Integration with Office add-ins applications is much simpler.

The following figure shows the high level architecture of BCS.

BCS is all about connecting to external data.  This external data can be viewed in the SharePoint list, Word, Outlook and SharePoint Workspace out of the box without any additional work. If you want to build a custom Word or Outlook solution, or surface the external data in applications that are not supported out of the box such as Excel or PowerPoint application, you can code against the BCS client runtime.

Following are the important components in BCS that you need to understand.

·         External Content Type

·         BCS Metadata Model (BDC Service). 

·         BCS Client Runtime.

In simple terms External content type enables us to define re-usable business entities. For more information about the External Content Types, see “External Content Types”. The BDC service models the metadata objects like the external content type and stores it in the metadata store. This essentially contains the metadata about the programmatic interfaces of the external systems. For more information about the BDC Service, see “Mechanics of Using Business Connectivity Services”.

The sample metadata model in xml format is presented in the appendix.

The BCS client runtime which is part of the Microsoft Office 2010 professional plus edition will use the metadata model to connect to the external data. This metadata will contain enough information on how to access the external system. 

We can use the SharePoint Designer 2010 to create an External Content type. Following sections describe how to create this.

Creating "SalesBCS" External Content Type for the sample

 In order to provide the required external data to our chart in the PowerPoint presentation, you need to create at least one external content type.

The name and the name space will be used to identify an external content type at runtime. In

Once an external content type it is created you can configure the type of “External Data Source”.  It can be one of the following.

1.    .NET Type.

2.    SQL Server.

3.    WCF Service.

In this example, you will use the “SQL Server” and the “SalesTerritory” table. This table contains sales details across various territories in the United States. This is the data that you will display in your PowerPoint presentation.

You can set the various operations on this table like Create, Read, Update and Delete and specify filters, if any and these will be used while accessing the data.

Save this information in SharePoint Designer 2010 for further processing.

Once the “External Content Type is created you can use SharePoint Designer 2010 to create a list and view in the browser.

You will use the SharePoint designer 2010 to create the external content type “SalesBCS”. The example presented in this article connects to the Adventure Works database. Download the AdventureWorks 2008R2 November CTP and install it. In reality this can be any database.  Once the database is installed, we can use SharePoint Designer 2010 to create an “External Content Type”.  This contains metadata about the data access capabilities of the external system.

Before creating the external content type you will need to set the permissions at the metadata store level. This will ensure that users will have appropriate permissions to get the external data.

To set the permissions

1.    Start SharePoint 2010 Central Administration.

2.    Click the Manage Service Applications link on the home page of SharePoint 2010 Central Administration.        

3.    Click the Business Connectivity Service link.

4.    In the ribbon click on the Edit tab and then click on the button Set Object Permissions.

5.    Add the account information and select all operations in the Permissions list box.

This will set the appropriate permissions at the service level.

To define a new External Content Type

1.    Launch SharePoint Designer 2010.

2.    Click on the button Open Site and specify the site address.

3.    On the left Navigation pane, point to Site Objects, and then click on the button External Content Types.

4.    Click on the ribbon button External Content Type.

5.    In the External Content Type information, specify the Name as “SalesBCS”.

6.    Specify the Namespace.

7.    Select the Office Item Type as Generic List -this is the default option.

8.    Click on the link Click here to discover external data sources and define operations.

9.    Click on the button Add Connection.

10. Select the Data Source Type as SQL Server.

11. Specify the Database Server and the Database name as Adventure Works.

12. Expand the Adventure Works database and select the Sales Territory table.

13. Right-click on the Sales Territory table and choose Create All Operations.

14. In the All Operations user interface click Finish.

15. Click on the Save button in the SharePoint designer.

This will save the External Content Type information in the BDC Metadata store.

Following figure shows the External Content Type that is created using SharePoint designer 2010.

To create the External List

1.    Launch SharePoint Designer 2010.

2.    Click on the button Open Site to connect to the site

3.    On the left pane navigate to the SalesBCS external content type.

4.    Click on ribbon button Create Lists & Forms.

5.    Choose Create New List and specify the List Name.

6.    Click Ok to create the list. - This will create the external list.

7.    Click on the ribbon button Preview in Browser to view the list in the browser.

Following section describes how to connect to the back-end using the BCS client runtime.

PowerPoint add-in will use BCS client runtime object model, which internally uses the Metadata model to connect to the back-end data. The custom task pane in our sample will use the following lines of code to populate the user control using the external data.

Connecting to back-end data using BCS client runtime:

public void PopulateControls()

{

    if (!CheckDependentDataSolution())

        return;

    RemoteSharedFileBackedMetadataCatalog Catalog = new RemoteSharedFileBackedMetadataCatalog();

    IEntityInstanceEnumerator InstanceEnumerator = null;

    INamespacedEntityDictionaryDictionary entDictDict = Catalog.GetEntities("*");

    foreach (INamedEntityDictionary entDict in entDictDict.Values)

    {

        foreach (IEntity entity in entDict.Values)

        {

            EntityLookup[entity.Name] = entity;

            ectList.Items.Add(entity.Name);

        }

    }

//    Populate the controls

}

It first begins by creating an instance of RemoteSharedFileBackedMetadataCatalog. This is the base object that uses metadata model to connect to the back-end database. The GetEntities method will return an INamespacedEntityDictionaryDictionary interface which represents the external content type’s collection from the back-end. The GetEntity method will return an IEntityInstanceEnumerator interface which represents collection or stream as “entity” instances from the back-end. The term “entity” here is the external content type. The term “entity” is used in the programmatic interfaces. The documentation and the SharePoint Designer 2010 will call this as the “External Content Type”. We obtain an instance of InstanceEnumerator based on set of filters against the LobSystemInstance, which in this case is the Adventure Works database instance. The GetMethodInstances method returns the instances of the entity. Then you can get a DataTable that contains the external data using the IRuntimeHelper interface.

The following section describe how to create the data solution to get the metadata model.

In order to get the external data using the BCS client object model in the PowerPoint add-in you need to get the metadata model to the client computer. The BCS Solution Packaging Tool helps in getting the external data to the add-in.

For more information on how to create the data solution for office add-in, download the “BCS Solution Packaging Tool”. You need to ensure that the Data Solution is functioning before invoking the BCS runtime APIs. To do this

1.    Launch the BCS Solution Packaging Tool.

2.    Navigate to the section “Package BCS Data Only Solution for Office Add-in”.

3.    Copy the “Code Example”.

You can now use it in the add-in. The “CheckDependentDataSolution” from the BCS Solution Packaging Tool will ensure that the metadata model is available before invoking the BCS runtime APIs.

In the PowerPoint add-in before invoking the external data you need to execute the following code.

 public void PopulateControls()

        {

            if (!CheckDependentDataSolution())

                return;

            //Get the external data

            //Populate the controls

        }

Packaging and Deploying the Solution

Before installing the PowerPoint add-in you need to package and deploy the solution. To do this

1.    Launch the BCS Solution Packaging Tool

2.    Specify the Solution Name.

3.    Specify the Solution Version.

4.    Select the solution type to “Data Solution for Office Add-in” from the combo box.

5.    Browse and select the  Source Folder Path

This folder will contain the PowerPoint add-in solution. Place the metadata model and the subscriptions xml file in this folder.

6.    Browse and select Output Folder Path

7.    Click on the button Package

Click on the button Deploy

This will deploy the solution package to the BCS runtime.

The subscription file is an xml file that contains the information about what gets populated in the cache. For more information about the subscriptions, see “Cache Subscriptions”. The appendix provides the information about how to export the metadata model.

  Following are the pre-requisites that are required to run the solution

1.    Install Visual Studio 2010

2.    Install Office 2010 Professional Plus edition

3.    Install SharePoint 2010

4.    Download and Install the AdventureWorks 2008R2 November CTP

Download the code and build it using Visual Studio 2010.

The following procedure explains how to run the sample.

1.    Press-F5

2.    This will launch the PowerPoint presentation

3.    Click on the ribbon tab “BCS”

4.    Click on the ribbon button “Add External Data to Chart”

5.    This will open the custom task pane

6.    Select an item from the “Select External Content Type” combo box.

7.    Select an item from the “Select Series Name” combo box.

8.    Check an item from the “Select Chart Categories” check box list control.

9.    Click on the button “Insert Chart”

This will insert the chart on the active slide like this.

To update an existing chart you need to select the existing chart. Then you need to click on the button “Update Existing Chart”. This will use the selected values in the custom task pane to update an existing chart.

When you insert a chart, it automatically adds an Excel sheet. This sheet will contain the data that chart will use to insert the chart. You need to force a Garbage Collection to ensure memory consumed by the excel application is reclaimed. The excel process will remain in memory for some indeterminate time after we quit the excel application. A repeated call to GC.Collect is necessary because the memory for the Excel reference might have survived the first pass, although it will then have been marked for collection on the next pass.

You have the following options to deploy the PowerPoint add-in.

1.    The Visual Studio publish wizard

2.    The Windows installer.

Deploying the add-in using the publish wizard is simple. For advanced deployment features like installing the add-in for all users, executing some custom actions the windows installer will be the preferable option.

To deploy the add-in using the publish wizard

1.    Launch the Visual studio 2010

2.    Open the PowerPoint add-in project.

3.    Right click on the solution explorer to open the Publish property page

4.    Specify the Publish location

5.    Click finish

6.    Double click on the VSTO deployment file.

This will install the PowerPoint add-in to the computer.

For more information on advanced deployment using the windows installer, see “Deploying Office Solutions by Using Windows Installer”.

Appendix A: SalesBCS Metadata Model 

This section provides the Metadata model for our SalesBCS external content type.

To view and export the Metadata model

1.    Launch SharePoint Designer 2010.

2.    Click on the button Open Site to connect to the site

3.    On the left Navigation pane, point to Site Objects, and then on the button External Content Types.

4.    Right-click on the SalesBCS External Content Type and select Export Application Data Model.

BCS client runtime will use this to connect to back-end. Metadata model for our SalesBCS in Xml format looks like this.

Conclusion

BCS 2010 offers a new way of integrating external data to Office applications. It handles the complicated problem of fetching and synchronizing the data between Office and one or more external systems. Without out BCS it would be very difficult to implement. This sort of rich integration to Office applications with BCS enables us to build classic Office Business Applications.

Additional Resources 

What is Microsoft Business Connectivity Services?

BCS Object Model Samples

BCS Blogs:

https://blogs.msdn.com/bcs/

Download the code

The Outlook 2010 programmability interface allows us to customize the ribbon. You can create an add-in for outlook using the Visual Studio 2010 and this will contain the ribbon. You need to supply the xml markup for the ribbon. Since ribbon is part of the add-in every outlook window will share the ribbon. Sometimes it is essential to manage the state of the ribbon to render the ribbon controls properly. This article will explain how to properly manage the state of the ribbon in outlook 2010 in order to render it properly.

About the sample

To begin with let us take a simple example of displaying the ribbon in Outlook 2010 with some toggle buttons. There is one more toggle button, when pressed, will disable all buttons. When you un-toggle it will enable all buttons. Here we are programmatically enabling/disabling these buttons like this.

State management of ribbon is useful in these scenarios .One of the common practices to address this problem is to have a Boolean variable in the ribbon class, set its value either true or false depending upon the action , call the invalidate method in the ribbon. You need to return the Boolean value appropriately in the callback function.

This at first look like it’s working. However if you open a new email again and click on the ribbon tab, you will see that the new email will also have these buttons disabled.

This is because of the fact that, when we call the invalidate method to disable the buttons, outlook will evaluate the call backs for the ribbon for all new windows.

The following section will explain how to solve this by use of the wrapper objects.

The Wrapper Objects for Inspector and Explorer windows.

The best way to maintain the state of the ribbon is to create the wrapper classes for the Inspector and Explorer windows. Eric Carter and Eric Lippert has written an excellent book on VSTO programming(Visual Studio Tools for Office 2007: VSTO for Excel, Word and Outlook)  and he has explained how to create the wrapper objects for Inspector and Explorer windows. We will extend them to use it in the context of ribbon effectively. Basically these wrapper objects help us manage the Inspector and Explorer windows. We will store any window specific information in these classes. Since these objects are specific to each window, when we call the invalidate method of the ribbon, we can use the associated wrapper object to render the ribbon properly.

We can maintain a collection of these wrapper objects and fetch the right one based on the active window.

You attach an event handler to the “NewExplorer” and in the event handler you can create the instance of the explorer wrapper and add it to the wrappers collection. Given below is the code that creates the wrapper object for the Explorer window. You will also need to add the active explorer to the wrappers collection.

private void ThisAddIn_Startup(object sender, System.EventArgs e)

        {

            explorerWrappers = new Collection<ExplorerWrapper>();

            m_explorers.NewExplorer += new ExplorersEvents_NewExplorerEventHandler(OnNewExplorer);

            Explorer ActiveExplorer = Application.ActiveExplorer();

            if (ActiveExplorer != null)

            {

                ExplorerWrappers.Add(new ExplorerWrapper(ActiveExplorer));

                ActiveExplorer.SelectionChange += new ExplorerEvents_10_SelectionChangeEventHandler(OnActiveExplorerSelectionChange);

            }

        }

You also need to do the same in the “NewExplorer” even handler like this.

private void OnNewExplorer(Explorer Explorer)

        {

            //If new explorer is opened (in open new window) we add it to Wrapper

            //This is set the togggle state. GetPressed of Outlook m_ribbon will do the

            //actual toggling/untoggling

            Explorer.SelectionChange += new ExplorerEvents_10_SelectionChangeEventHandler(OnActiveExplorerSelectionChange);

            ExplorerWrapper ExplorerWrapper = new ExplorerWrapper(Explorer);

            ExplorerWrappers.Add(ExplorerWrapper);

        }

The wrapper object can now maintain the state information by using properties. The wrapper object is automatically removed from the collection by subscribing to the close event handler.

The same pattern is applied for the inspector window.

Using the Wrapper Objects in Ribbon

These wrapper objects are used in the ribbon object while executing the callbacks. In our example when you click on the button “EnableOrDiasbleAll”, it will dynamically enable or disable all buttons. We do this by subscribing to the “GetEnabled” callback . This will be called when we call the Invalidate/Invalidate control method of the ribbon.

We will use the wrapper object enable or disable appropriately. Given below is the code on the button that retrieves the active wrapper item that can store the Boolean value.

To attach the callback function for the button you need to add the method name in the ribbon xml and the corresponding callback function in the ribbon class like this.

  <toggleButton id="toggleButton3" label="EnableOrDiableAll" onAction="OnEnableOrDisableAll" showImage="false" />

public void OnEnableOrDisableAll(Office.IRibbonControl ctrl, bool isPressed)

        {

            dynamic ActiveWrapper = GetActiveOutlookWrapperItem();

            ActiveWrapper.IsButton1Enabled = isPressed;

            ActiveWrapper.IsButton2Enabled = isPressed;

            Globals.ThisAddIn.m_RibbonUI.InvalidateControl("toggleButton1");

            Globals.ThisAddIn.m_RibbonUI.InvalidateControl("normalButton1");

        }

You will set the “IsButton1Enabled” and “IsButton2Enabled” to true/false based on the toggle button action.

The GetActiveOutlookWrapperItem will get the wrapper object for the active window. The code is shown below

private static object GetActiveOutlookWrapperItem()

        {

                //Checks the active window

                object activeWindow;

                activeWindow = Globals.ThisAddIn.Application.ActiveWindow();

                //If it is exploer, set its background

                if (activeWindow is Microsoft.Office.Interop.Outlook.Explorer)

                {

                    ExplorerWrapper ExplorerWrapper = Globals.ThisAddIn.ExplorerWrappers.FirstOrDefault(explorer => explorer.Explorer == Globals.ThisAddIn.Application.ActiveExplorer());

                    return ExplorerWrapper;

                }

                else if (activeWindow is Microsoft.Office.Interop.Outlook.Inspector)

                {

                    InspectorWrapper InspectorWrapper = Globals.ThisAddIn.InspectorWrappers.FirstOrDefault(inspector => inspector.Inspector == Globals.ThisAddIn.Application.ActiveInspector());

                    return InspectorWrapper;

                }

                return null;

        }

You need to subscribe the callback to the “GetEnabled” in the ribbon xml like this

<toggleButton id="toggleButton1" label="ToggleButton1" showImage="false" getEnabled="GetEnabled" onAction="OnToggleButton1Click" getPressed="GetPressed" />

                    <button id="normalButton1" label="NormalButton1" showImage="false" getEnabled="GetEnabled" onAction="OnNormalButton1Click" />

When you call the invalidate/invalidate control method of the ribbon it will execute the “GetEnabled” callback function. We will use the wrapper object in this callback to return the appropriate Boolean value. This callback will be repeatedly called for all registered buttons.

Given below is the code which does this.

public bool GetEnabled(Office.IRibbonControl ctrl)

        {

            if (ctrl == null)

                return false;

            object context = ctrl.Context;

            dynamic activeWindow = GetActiveOutlookWrapperItem();

            if (ctrl.Id == "toggleButton1")

            {

                return activeWindow.IsButton1Enabled;

            }

            else if (ctrl.Id == "normalButton1")

            {

                return activeWindow.IsButton2Enabled;

            }

            return true;

        }

Running the Sample

To run the sample

1.    Download the code from here

2.    Close the outlook 2010

3.    Build the sample project and then press F5 to launch the Outlook 2010

4.    Click on the ribbon tab “CustomTab”

5.    Click on the button “EnableOrDisableAll”

This will disable all buttons. Open a new email and click on the ribbon tab “CustomTab” and verify that the button controls in this ribbon are not affected.

Additional Resources

https://msdn.microsoft.com/en-us/library/ee692172.aspx