Tutorial: Actualización de los controles de una cinta en tiempo de ejecución

Artículo
10/10/2023

En este tutorial se muestra cómo usar el modelo de objetos de la cinta de opciones para actualizar los controles de una cinta después de cargar la cinta en la aplicación de Office lication.

Se aplica a: La información de este tema se aplica a proyectos de nivel de documento y proyectos de complementos de VSTO para las siguientes aplicaciones: Excel; InfoPath 2013 e InfoPath 2010; Outlook; Powerpoint; Proyecto; Visio; Palabra. Para obtener más información, consulte Características disponibles por aplicación de Office lication y tipo de proyecto.

En el ejemplo, se extraen los datos de la base de datos de ejemplo Northwind para rellenar un cuadro combinado y un menú en Microsoft Office Outlook. Los elementos que seleccione en estos controles rellenan automáticamente campos como To y Subject en un mensaje de correo electrónico.

En este tutorial se muestran las tareas siguientes:

Cree un nuevo proyecto de complemento VSTO de Outlook.
Diseñar un grupo personalizado de cinta de opciones.
Agregue el grupo personalizado a una pestaña integrada.
Actualice los controles de la cinta de opciones en tiempo de ejecución.

Nota:

Es posible que tu equipo muestre nombres o ubicaciones diferentes para algunos de los elementos de la interfaz de usuario de Visual Studio en las siguientes instrucciones. La edición de Visual Studio que se tenga y la configuración que se utilice determinan estos elementos. Para más información, vea Personalizar el IDE de Visual Studio.

Requisitos previos

Necesitará los componentes siguientes para completar este tutorial:

Una edición de Visual Studio que incluye las herramientas para desarrolladores de Microsoft Office. Para obtener más información, vea Configurar un equipo para desarrollar soluciones de Office.
Microsoft Outlook

Crear un nuevo proyecto de complemento VSTO de Outlook

En primer lugar, cree un proyecto de complemento de VSTO de Outlook.

Para crear un proyecto de complemento de VSTO de Outlook

En Visual Studio, cree un proyecto de complemento vsto de Outlook con el nombre Ribbon_Update_At_Runtime.
En el cuadro de diálogo Nuevo proyecto , seleccione Crear directorio para la solución.
Guarde el proyecto en el directorio de proyecto predeterminado.

Para obtener más información, vea Cómo: Crear proyectos de Office en Visual Studio.

Diseño de un grupo de cintas personalizado

La cinta de opciones de este ejemplo aparecerá cuando un usuario redacte un nuevo mensaje de correo. Para crear un grupo personalizado para la cinta de opciones, agregue primero un elemento ribbon al proyecto y, a continuación, diseñe el grupo en el Diseñador de cintas. Este grupo personalizado le ayudará a generar mensajes de correo electrónico de seguimiento a los clientes mediante la extracción de nombres y historiales de pedidos de una base de datos.

Para diseñar un grupo personalizado

En el menú Proyecto , haga clic en Agregar nuevo elemento.
En el cuadro de diálogo Agregar nuevo elemento , seleccione Cinta (diseñador visual).
Cambie el nombre de la nueva cinta de opciones a CustomerRibbon y, a continuación, haga clic en Agregar.

El archivo CustomerRibbon.cs o CustomerRibbon.vb se abre en el Diseñador de cintas de opciones y muestra una pestaña y un grupo predeterminados.
Haga clic en el Diseñador de la cinta de opciones para seleccionarlo.
En la ventana Propiedades , haga clic en la flecha desplegable situada junto a la propiedad RibbonType y, a continuación, haga clic en Microsoft.Outlook.Mail.Compose.

Esto permite que la cinta aparezca cuando el usuario redacta un nuevo mensaje de correo en Outlook.
En el Diseñador de cinta de opciones, haga clic en Group1 para seleccionarlo.
En la ventana Propiedades, establezca Etiqueta en Compras de clientes.
En la pestaña Controles de cinta de Office del Cuadro de herramientas, arrastre un ComboBox al grupo Compras de clientes.
Haga clic en ComboBox1 para seleccionarlo.
En la ventana Propiedades, establezca Etiqueta en Clientes.
En la pestaña Controles de la cinta de opciones de Office del Cuadro de herramientas, arrastre un menú al grupo Compras de clientes.
En la ventana Propiedades , establezca Etiqueta en Producto comprado.
Establezca Dynamic en true.

Esto le permite agregar y quitar controles en el menú en tiempo de ejecución después de cargar la cinta de opciones en la aplicación de Office lication.

Agregar el grupo personalizado a una pestaña integrada

Una pestaña integrada es una pestaña que ya está en la cinta de opciones de un Explorador o inspector de Outlook. En este procedimiento agregará el grupo personalizado a una pestaña integrada y especificará la posición del grupo personalizado en la pestaña.

Para agregar el grupo personalizado a una pestaña integrada

Haga clic en la pestaña TabAddins (integrado) para seleccionarla.
En la ventana Propiedades , expanda la propiedad ControlId y, a continuación, establezca OfficeId en TabNewMailMessage.

Esto agrega el grupo Compras de clientes a la pestaña Mensajes de la cinta de opciones que aparece en un nuevo mensaje de correo.
Haga clic en el grupo Compras de clientes para seleccionarlo.
En la ventana Propiedades , expanda la propiedad Position , haga clic en la flecha desplegable situada junto a la propiedad PositionType y, a continuación, haga clic en BeforeOfficeId.
Establezca la propiedad OfficeId en GroupClipboard.

Esto coloca el grupo Compras de clientes delante del grupo Portapapeles de la pestaña Mensajes .

Creación del origen de datos

Use la ventana Orígenes de datos para agregar un conjunto de datos con tipo al proyecto.

Para crear el origen de datos

En el menú Datos , haga clic en Agregar nuevo elemento.

Esto inicia el Asistente para configuración del origen de datos.
Seleccione Base de datos y, a continuación, haga clic en Siguiente.
Seleccione Conjunto de datos y, a continuación, haga clic en Siguiente.
Seleccione una conexión de datos a la base de datos northwind de ejemplo Microsoft SQL Server Compact 4.0 o agregue una nueva conexión mediante el botón Nueva Conectar ion.
Una vez seleccionada o creada una conexión, haga clic en Siguiente.
Haga clic en Siguiente para guardar el cadena de conexión.
En la página Elegir los objetos de base de datos, expanda Tablas.
Active la casilla situada al lado de cada una de las siguientes tablas:
1. Clientes
2. Detalles de pedido
3. Pedidos
4. Productos
Haga clic en Finalizar

Actualizar controles en el grupo personalizado en tiempo de ejecución

Use el modelo de objetos de la cinta de opciones para llevar a cabo las siguientes tareas:

Agregue nombres de cliente al cuadro combinado Clientes .
Agregue controles de menú y botón al menú Productos comprados que representan pedidos de ventas y productos vendidos.
Rellene los campos To, Subject y Body de los nuevos mensajes de correo mediante datos del cuadro combinado Clientes y el menú Productos comprados.

Para actualizar los controles del grupo personalizado mediante el modelo de objetos de la cinta de opciones

En el menú Proyecto, haga clic en Agregar referencia.
En el cuadro de diálogo Agregar referencia , haga clic en la pestaña .NET , seleccione el ensamblado System.Data.Linq y, a continuación, haga clic en Aceptar.

Este ensamblado contiene las clases para usar Language-Integrated Queries (LINQ). Va a usar LINQ para rellenar los controles del grupo personalizado con datos de la base de datos Northwind.
En Explorador de soluciones, haga clic en CustomerRibbon.cs o CustomerRibbon.vb para seleccionarlo.
En el menú Ver , haga clic en Código.

Se abre el archivo de código de la cinta de opciones en el editor de código.

Agregue las siguientes instrucciones a la parte superior del archivo de código de la cinta. Estas instrucciones proporcionan acceso fácil a los espacios de nombres LINQ y al espacio de nombres del ensamblado de interoperabilidad primario (PIA) de Outlook.

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

Agregue el código siguiente dentro de la CustomerRibbon clase . Este código declara los adaptadores de tabla y tabla de datos que usará para almacenar la información de las tablas de clientes, pedidos, detalles de pedidos y productos de la base de datos Northwind.

//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()

Agregue el siguiente bloque de código a la clase CustomerRibbon. Este código agrega tres métodos auxiliares que crean controles para la cinta de opciones en tiempo de ejecución.

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

Reemplace el método del controlador de eventos CustomerRibbon_Load por el siguiente código. Este código usa una consulta LINQ para efectuar las siguientes tareas:

Rellene el cuadro combinado Clientes con el identificador y el nombre de 20 clientes en la base de datos Northwind.

Llama al método del asistente PopulateSalesOrderInfo. Este método actualiza el menú ProductsPurchased con números de pedido de venta que pertenecen al cliente seleccionado actualmente.

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

Agregue el siguiente código a la clase CustomerRibbon . Este código usa consultas LINQ para efectuar las siguientes tareas:

Agrega un submenú al menú ProductsPurchased para cada pedido de ventas relacionado con el cliente seleccionado.
Agregar botones a cada submenú para los productos relacionados con el pedido.

Agregar controladores de eventos a cada botón.

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

En Explorador de soluciones, haga doble clic en el archivo de código de la cinta de opciones.

Se abre el Diseñador de la cinta de opciones.
En el Diseñador de la cinta de opciones, haga doble clic en el cuadro combinado Clientes .

El archivo de código de la cinta de opciones se abre en el editor de código y aparece el controlador de eventos ComboBox1_TextChanged.
Reemplace el controlador de eventos ComboBox1_TextChanged por el siguiente código: Este código realiza las tareas siguientes:
- Llama al método del asistente PopulateSalesOrderInfo. Este método actualiza el menú Productos comprados con pedidos de ventas relacionados con el cliente seleccionado.
- Llama al método del asistente PopulateMailItem y pasa el texto actual, que es el nombre del cliente seleccionado. Este método rellena los campos To, Subject y Body de nuevos mensajes de correo.
  - C#
  - VB
```
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
```

Agregue el siguiente controlador de eventos Click a la clase CustomerRibbon . Este código agrega el nombre de los productos seleccionados al campo Cuerpo de los nuevos mensajes de correo.

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

Agregue el siguiente código a la clase CustomerRibbon . Este código realiza las tareas siguientes:

Rellena la línea Para de nuevos mensajes de correo mediante la dirección de correo electrónico del cliente seleccionado actualmente.

Agrega texto a los campos Asunto y Cuerpo de los nuevos mensajes de correo.

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

Prueba de los controles del grupo personalizado

Al abrir un nuevo formulario de correo en Outlook, aparece un grupo personalizado denominado Compras de clientes en la pestaña Mensajes de la cinta de opciones.

Para crear un mensaje de correo electrónico de seguimiento del cliente, seleccione un cliente y, a continuación, seleccione productos adquiridos por el cliente. Los controles del grupo Compras de clientes se actualizan en tiempo de ejecución con datos de la base de datos Northwind.

Para probar los controles en el grupo personalizado

Presione F5 para ejecutar el proyecto.

Se inicia Outlook.
En Outlook, en el menú Archivo , seleccione Nuevo y, a continuación, haga clic en Mensaje de correo.

Se producen las siguientes acciones:
- Aparece una nueva ventana del inspector de mensajes de correo.
- En la pestaña Mensaje de la cinta de opciones, el grupo Compras de clientes aparece antes del grupo Portapapeles .
- El cuadro combinado Clientes del grupo se actualiza con los nombres de los clientes de la base de datos Northwind.
En la pestaña Mensaje de la cinta de opciones, en el grupo Compras de clientes, seleccione un cliente en el cuadro combinado Clientes .

Se producen las siguientes acciones:
- El menú Productos comprados se actualiza para mostrar cada pedido de ventas para el cliente seleccionado.
- Cada submenú del pedido se actualiza para mostrar los productos comprados en ese pedido.
- La dirección de correo electrónico del cliente seleccionada se agrega a la línea Para del mensaje de correo y el asunto y el cuerpo del mensaje de correo se rellenan con texto.
Haga clic en el menú Compras de productos, seleccione cualquier pedido de ventas y, a continuación, haga clic en un producto desde el pedido de ventas.

El nombre del producto se agrega al cuerpo del mensaje de correo.

Pasos siguientes

Puede aprender más acerca de la personalización de la interfaz de usuario de Office en estos temas:

Agregar una interfaz de usuario basada en contexto a cualquier personalización de nivel de documento. Para obtener más información, vea Información general sobre el panel Acciones.
Extender un formulario estándar o personalizado de Microsoft Office Outlook. Para obtener más información, vea Tutorial: Diseño de un área de formulario de Outlook.
Agregar un panel de tareas personalizado a Outlook. Para obtener más información, consulte Paneles de tareas personalizados.