Walkthrough: Update the controls on a ribbon at run time

Article
02/02/2017

Applies to: Visual Studio Visual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

This walkthrough demonstrates how to use the Ribbon object model to update the controls on a ribbon after the ribbon is loaded into the Office application.

Applies to: The information in this topic applies to document-level projects and VSTO Add-in projects for the following applications: Excel; InfoPath 2013 and InfoPath 2010; Outlook; PowerPoint; Project; Visio; Word. For more information, see Features available by Office application and project type.

The example pulls data from the Northwind sample database to populate a combo box and menu in Microsoft Office Outlook. Items that you select in these controls automatically populate fields such as To and Subject in an email message.

This walkthrough illustrates the following tasks:

Create a new Outlook VSTO Add-in project.
Design a custom Ribbon group.
Add the custom group to a built-in tab.
Update controls on the ribbon at run time.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Personalize the Visual Studio IDE.

Prerequisites

You need the following components to complete this walkthrough:

An edition of Visual Studio that includes the Microsoft Office developer tools. For more information, see Configure a computer to develop Office solutions.
Microsoft Outlook

Create a new Outlook VSTO Add-in project

First, create an Outlook VSTO Add-in project.

To create a new Outlook VSTO Add-in project

In Visual Studio, create an Outlook VSTO Add-in project with the name Ribbon_Update_At_Runtime.
In the New Project dialog box, select Create directory for solution.
Save the project to the default project directory.

For more information, see How to: Create Office projects in Visual Studio.

Design a custom Ribbon group

The ribbon for this example will appear when a user composes a new mail message. To create a custom group for the ribbon, first add a Ribbon item to your project, and then design the group in the Ribbon Designer. This custom group will help you generate follow-up email messages to customers by pulling names and order histories from a database.

To design a custom group

On the Project menu, click Add New Item.
In the Add New Item dialog box, select Ribbon (Visual Designer).
Change the name of the new Ribbon to CustomerRibbon, and then click Add.

The CustomerRibbon.cs or CustomerRibbon.vb file opens in the Ribbon Designer and displays a default tab and group.
Click the Ribbon Designer to select it.
In the Properties window, click the drop-down arrow next to the RibbonType property, and then click Microsoft.Outlook.Mail.Compose.

This enables the ribbon to appear when the user composes a new mail message in Outlook.
In the Ribbon Designer, click Group1 to select it.
In the Properties window, set Label to Customer Purchases.
From the Office Ribbon Controls tab of the Toolbox, drag a ComboBox onto the Customer Purchases group.
Click ComboBox1 to select it.
In the Properties window, set Label to Customers.
From the Office Ribbon Controls tab of the Toolbox, drag a Menu onto the Customer Purchases group.
In the Properties window, set Label to Product Purchased.
Set Dynamic to true.

This enables you to add and remove controls on the menu at run time after the ribbon is loaded into the Office application.

Add the custom group to a built-in tab

A built-in tab is a tab that is already on the ribbon of an Outlook Explorer or Inspector. In this procedure, you will add the custom group to a built-in tab, and then specify the position of the custom group on the tab.

To add the custom group to a built-in tab

Click the TabAddins (Built-In) tab to select it.
In the Properties window, expand the ControlId property, and then set OfficeId to TabNewMailMessage.

This adds the Customer Purchases group to the Messages tab of the ribbon that appears in a new mail message.
Click the Customer Purchases group to select it.
In the Properties window, expand the Position property, click the drop-down arrow next to the PositionType property, and then click BeforeOfficeId.
Set the OfficeId property to GroupClipboard.

This positions the Customer Purchases group before the Clipboard group of the Messages tab.

Create the data source

Use the Data Sources window to add a typed dataset to your project.

To create the data source

On the Data menu, click Add New Data Source.

This starts the Data Source Configuration Wizard.
Select Database, and then click Next.
Select Dataset, and then click Next.
Select a data connection to the Northwind sample Microsoft SQL Server Compact 4.0 database, or add a new connection by using the New Connection button.
After a connection has been selected or created, click Next.
Click Next to save the connection string.
On the Choose Your Database Objects page, expand Tables.
Select the check box next to each of the following tables:
1. Customers
2. Order Details
3. Orders
4. Products
Click Finish.

Update controls in the custom group at run time

Use the Ribbon object model to perform the following tasks:

Add customer names to the Customers combo box.
Add menu and button controls to the Products Purchased menu that represent sales orders and products sold.
Populate the To, Subject, and Body fields of new mail messages by using data from the Customers combo box and Products Purchased menu.

To update controls in the custom group by using the Ribbon object model

On the Project menu, click Add Reference.
In the Add Reference dialog box, click the .NET tab, select the System.Data.Linq assembly, and then click OK.

This assembly contains classes for using Language-Integrated Queries (LINQ). You will use LINQ to populate controls in the custom group with data from the Northwind database.
In Solution Explorer, click CustomerRibbon.cs or CustomerRibbon.vb to select it.
On the View menu, click Code.

The Ribbon code file opens in the Code Editor.

Add the following statements to the top of the Ribbon code file. These statements provide easy access to LINQ namespaces and to the namespace of the Outlook primary interop assembly (PIA).

using System.Data.Linq;
using System.Data.Linq.Mapping;
using System.Linq.Expressions;
using Outlook = Microsoft.Office.Interop.Outlook;
using System.Data;
using System.IO;
using Ribbon_Update_At_Runtime.Northwind40DataSetTableAdapters;

Imports System.Data.Linq
Imports System.Linq
Imports System.Data.Linq.Mapping
Imports System.Linq.Expressions
Imports Outlook = Microsoft.Office.Interop.Outlook
Imports Ribbon_Update_At_Runtime.Northwind40DataSetTableAdapters

Add the following code inside the CustomerRibbon class. This code declares the data table and table adapters that you will use to store information from the Customer, Orders, Order Details, and Product tables of the Northwind database.

//Declare the Northwind dataset.
Northwind40DataSet nwDataSet = new Northwind40DataSet();

//Declare the data tables.

Northwind40DataSet.CustomersDataTable customerTable;
Northwind40DataSet.OrdersDataTable orderTable;
Northwind40DataSet.Order_DetailsDataTable orderDetailsTable;
Northwind40DataSet.ProductsDataTable productsTable;

//Declare the data table adapters for each table.

CustomersTableAdapter customerTableAdapter = new CustomersTableAdapter();
OrdersTableAdapter ordersTableAdapter = new OrdersTableAdapter();
Order_DetailsTableAdapter detailsTableAdapter = new Order_DetailsTableAdapter();
ProductsTableAdapter productsTableAdapter = new ProductsTableAdapter();

'Declare the Northwind data set.

Dim nwDataSet As Northwind40DataSet = New Northwind40DataSet()

'Declare the data tables.

Dim customerTable As Northwind40DataSet.CustomersDataTable
Dim orderTable As Northwind40DataSet.OrdersDataTable
Dim orderDetailsTable As Northwind40DataSet.Order_DetailsDataTable
Dim productsTable As Northwind40DataSet.ProductsDataTable

'Declare the data table adapters for each table.

Dim customersTableAdapter As CustomersTableAdapter = New CustomersTableAdapter()
Dim ordersTableAdapter As OrdersTableAdapter = New OrdersTableAdapter()
Dim detailsTableAdapter As Order_DetailsTableAdapter = New Order_DetailsTableAdapter()
Dim productsTableAdapter As ProductsTableAdapter = New ProductsTableAdapter()

Add the following block of code to the CustomerRibbon class. This code adds three helper methods that create controls for the ribbon at run time.

private RibbonDropDownItem CreateRibbonDropDownItem()
{
    return this.Factory.CreateRibbonDropDownItem();
}
private RibbonMenu CreateRibbonMenu()
{
    return this.Factory.CreateRibbonMenu();
}
private RibbonButton CreateRibbonButton()
{
    RibbonButton button = this.Factory.CreateRibbonButton();
    button.Click += new RibbonControlEventHandler(button_Click);
    return button;
}


Private Function CreateRibbonDropDownItem() As RibbonDropDownItem
    Return Me.Factory.CreateRibbonDropDownItem()
End Function

Private Function CreateRibbonMenu() As RibbonMenu
    Return Me.Factory.CreateRibbonMenu()
End Function

Private Function CreateRibbonButton() As RibbonButton
    Dim button As RibbonButton = Me.Factory.CreateRibbonButton()
    AddHandler (button.Click), AddressOf Button_Click
    Return button
End Function

Replace the CustomerRibbon_Load event handler method with the following code. This code uses a LINQ query to perform the following tasks:

Populate the Customers combo box by using the ID and name of 20 customers in the Northwind database.

Calls the PopulateSalesOrderInfo helper method. This method updates the ProductsPurchased menu with sales order numbers that pertain to the currently selected customer.

private void CustomerRibbon_Load(object sender, RibbonUIEventArgs e)
{
    customerTable = nwDataSet.Customers;
    customerTableAdapter.Fill(customerTable);

    var customerQuery = from customers in customerTable.AsEnumerable().Take(20)
                        select new
                        {
                            CustomerID = customers.Field<string>("Customer ID"),
                            CustomerName = customers.Field<string>("Contact Name")
                        };


    // Execute the query.
    foreach (var item in customerQuery)
    {
        this.comboBox1.Items.Add(CreateRibbonDropDownItem());
        this.comboBox1.Items.Last().Label =
        item.CustomerName + "|" + item.CustomerID.ToString();
    }
    this.comboBox1.Text = this.comboBox1.Items.First().Label;
    PopulateSalesOrderInfo();
}

 Private Sub CustomerRibbon_Load(ByVal sender As System.Object, _
ByVal e As Microsoft.Office.Tools.Ribbon.RibbonUIEventArgs) _
    Handles MyBase.Load

     customerTable = nwDataSet.Customers
     customersTableAdapter.Fill(customerTable)

     Dim customerQuery = From customers In customerTable.AsEnumerable.Take(20) _
             Select CustomerID = customers.Customer_ID, _
             CustomerName = customers.Contact_Name

     ' Execute the query.
     For Each item In customerQuery
         Me.ComboBox1.Items.Add(CreateRibbonDropDownItem())

         Me.ComboBox1.Items.Last().Label = item.CustomerID.ToString() _
             + "|" + item.CustomerName
     Next item

     Me.ComboBox1.Text = Me.ComboBox1.Items.First().Label
     PopulateSalesOrderInfo()
 End Sub

Add the following code to the CustomerRibbon class. This code uses LINQ queries to perform the following tasks:

Adds a submenu to the ProductsPurchased menu for each sales order related to the selected customer.
Adds buttons to each submenu for the products related to the sales order.

Adds event handlers to each button.

private void PopulateSalesOrderInfo()
{
    String[] tempArray = comboBox1.Text.Split(new Char[] { '|' });
    menu1.Items.Clear();

    orderTable = nwDataSet.Orders;
    orderDetailsTable = nwDataSet.Order_Details;
    productsTable = nwDataSet.Products;

    ordersTableAdapter.Fill(orderTable);
    detailsTableAdapter.Fill(orderDetailsTable);
    productsTableAdapter.Fill(productsTable);

    var orderQuery = from orders in orderTable.AsEnumerable()
                     where orders.Field<string>("Customer ID") == tempArray[1]
                     select new { OrderID = orders.Field<int>("Order ID") };

    foreach (var orderItem in orderQuery)
    {
        menu1.Items.Add(CreateRibbonMenu());

        RibbonMenu orderMenu = (RibbonMenu)menu1.Items.Last();
        orderMenu.Dynamic = true;
        orderMenu.Label = orderItem.OrderID.ToString();
        orderMenu.Tag = orderItem.OrderID;

        var productQuery = from orderDetail in orderDetailsTable.AsEnumerable()
                           join product in productsTable.AsEnumerable() on
                               orderDetail.Field<int>("Product ID")
                           equals product.Field<int>("Product ID")
                           where orderDetail.Field<int>("Order ID") ==
                               orderItem.OrderID
                           select new { ProductName = product.Field<string>("Product Name") };

        foreach (var productItem in productQuery)
        {
            RibbonButton button = CreateRibbonButton();
            button.Label = productItem.ProductName;
            orderMenu.Items.Add(button);
        }
    }
}

Private Sub PopulateSalesOrderInfo()

    Dim tempArray As [String]() = comboBox1.Text.Split(New [Char]() {"|"c})
    Menu1.Items.Clear()

    orderTable = nwDataSet.Orders
    orderDetailsTable = nwDataSet.Order_Details
    productsTable = nwDataSet.Products

    ordersTableAdapter.Fill(orderTable)
    detailsTableAdapter.Fill(orderDetailsTable)
    productsTableAdapter.Fill(productsTable)

    Dim orderQuery = From order In orderTable.AsEnumerable() _
                     Where order.Customer_ID.ToString() = tempArray(0) _
                     Select New With {.SalesOrderID = order.Order_ID}

    For Each orderItem In orderQuery
        Me.Menu1.Items.Add(CreateRibbonMenu())

        Dim orderMenu As RibbonMenu = CType(Menu1.Items.Last(), RibbonMenu)
        orderMenu.Dynamic = True
        orderMenu.Label = orderItem.SalesOrderID.ToString()
        orderMenu.Tag = orderItem.SalesOrderID

        Dim productQuery = From orderDetail In orderDetailsTable.AsEnumerable(), _
                               product In productsTable.AsEnumerable() _
                           Where orderDetail.Product_ID = _
                               product.Product_ID _
                           And orderDetail.Order_ID = _
                           orderMenu.Tag _
        Select productName = product.Product_Name

        For Each productItem In productQuery
            Dim button As RibbonButton = CreateRibbonButton()
            button.Label = productItem
            orderMenu.Items.Add(button)
        Next productItem
    Next orderItem
End Sub

In Solution Explorer, double-click the Ribbon code file.

The Ribbon Designer opens.
In the Ribbon Designer, double-click the Customers combo box.

The Ribbon code file opens in the Code Editor, and the ComboBox1_TextChanged event handler appears.
Replace the ComboBox1_TextChanged event handler with the following code. This code performs the following tasks:
- Calls the PopulateSalesOrderInfo helper method. This method updates the Products Purchased menu with sales orders that relate to the selected customer.
- Calls the PopulateMailItem helper method and passes in the current text, which is the selected customer name. This method populates the To, Subject, and Body fields of new mail messages.
```
private void comboBox1_TextChanged(object sender,
    RibbonControlEventArgs e)
{
    PopulateSalesOrderInfo();
    PopulateMailItem(comboBox1.Text);
}
```
```
Private Sub ComboBox1_TextChanged(ByVal sender As System.Object, _
    ByVal e As Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs) _
        Handles ComboBox1.TextChanged
    PopulateSalesOrderInfo()
    PopulateMailItem(ComboBox1.Text)
End Sub
```

Add the following Click event handler to the CustomerRibbon class. This code adds the name of selected products to the Body field of new mail messages.

void button_Click(object sender, RibbonControlEventArgs e)
{
    Outlook.Application application = Globals.ThisAddIn.Application;
    Outlook.Inspector inspector = application.ActiveInspector();
    Outlook.MailItem myMailItem = (Outlook.MailItem)inspector.CurrentItem;
    RibbonButton myCheckBox = (RibbonButton)sender;
    myMailItem.Subject = "Following up on your order";
    myMailItem.Body = myMailItem.Body + "\n" + "* " + myCheckBox.Label;
}

Private Sub Button_Click(ByVal sender As System.Object, _
    ByVal e As Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs)
    Dim application As Outlook.Application = Globals.ThisAddIn.Application
    Dim inspector As Outlook.Inspector = application.ActiveInspector()
    Dim myMailItem As Outlook.MailItem = CType(inspector.CurrentItem,  _
        Outlook.MailItem)
    Dim myButton As RibbonButton = CType(sender, RibbonButton)
    myMailItem.Subject = "Following up on your order"
    myMailItem.Body = myMailItem.Body + ControlChars.Lf + "* " _
        + myButton.Label
End Sub

Add the following code to the CustomerRibbon class. This code performs the following tasks:

Populates the To line of new mail messages by using the email address of the currently selected customer.

Adds text to the Subject and Body fields of new mail messages.

private void PopulateMailItem(string addressToLine)
{
    Outlook.Application application = Globals.ThisAddIn.Application;
    Outlook.Inspector inspector = application.ActiveInspector();
    Outlook.MailItem myMailItem = (Outlook.MailItem)inspector.CurrentItem;

    myMailItem.To = "";
    String[] tempArray = addressToLine.Split(new Char[] { '|' });
    myMailItem.To = tempArray[0] + "@example.com";
    myMailItem.Subject = "Following up on your order";
    myMailItem.Body = "Hello " + tempArray[0] + "," +
        "\n" + "We would like to get your feedback on the " +
        "following products that you recently ordered: ";
}

Private Sub PopulateMailItem(ByVal addressToLine As String)
    Dim application As Outlook.Application = Globals.ThisAddIn.Application
    Dim inspector As Outlook.Inspector = application.ActiveInspector()
    Dim myMailItem As Outlook.MailItem = _
        CType(inspector.CurrentItem, Outlook.MailItem)

    myMailItem.To = ""
    Dim tempArray As [String]() = addressToLine.Split(New [Char]() {"|"c})
    myMailItem.To = tempArray(1) + "@example.com"
    myMailItem.Subject = "Following up on your order"
    myMailItem.Body = "Hello " + tempArray(1) + "," _
        + ControlChars.Lf + "We would like to get your feedback" + _
        "on the following products that you recently ordered: "
End Sub

Test the controls in the custom group

When you open a new mail form in Outlook, a custom group named Customer Purchases appears on the Messages tab of the Ribbon.

To create a customer follow-up email message, select a customer, and then select products purchased by the customer. The controls in the Customer Purchases group are updated at run time with data from the Northwind database.

To test the controls in the custom group

Press F5 to run your project.

Outlook starts.
In Outlook, on the File menu, point to New, and then click Mail Message.

The following actions occur:
- A new mail message Inspector window appears.
- On the Message tab of the ribbon, the Customer Purchases group appears before the Clipboard group.
- The Customers combo box in the group is updated with the names of customers in the Northwind database.
On the Message tab of the ribbon, in the Customer Purchases group, select a customer from the Customers combo box.

The following actions occur:
- The Products Purchased menu is updated to show each sales order for the selected customer.
- Each sales order submenu is updated to show the products purchased in that order.
- The selected customer's email address is added to the To line of the mail message, and the subject and body of the mail message are populated with text.
Click the Products Purchases menu, point to any sales order, and then click a product from the sales order.

The product name is added to the body of the mail message.

Next steps

You can learn more about how to customize the Office UI from these topics:

Add context-based UI to any document-level customization. For more information, see Actions pane overview.
Extend a standard or custom Microsoft Office Outlook form. For more information, see Walkthrough: Design an Outlook form region.
Add a custom task pane to Outlook. For more information, see Custom task panes.

Share via