Tutorial: Mostrar paneles de tareas personalizados con mensajes de correo electrónico en Outlook

Artículo
06/19/2023

En este tutorial se muestra cómo mostrar una instancia única de un panel de tareas personalizado con cada mensaje de correo electrónico que se crea o abre. Los usuarios pueden mostrar u ocultar el panel de tareas personalizado mediante un botón de la cinta de opciones de cada mensaje de correo.

Se aplica a: La información de este tema se aplica a los proyectos de complementos de VSTO para Outlook. Para obtener más información, consulte Características disponibles por aplicación de Office lication y tipo de proyecto.

Para mostrar un panel de tareas personalizado con varias ventanas de explorador o inspector, es necesario crear una instancia del panel de tareas personalizado para cada ventana que se abra. Para obtener más información sobre el comportamiento de los paneles de tareas personalizados en las ventanas de Outlook, vea Paneles de tareas personalizados.

Nota:

En este tutorial se presenta el código del complemento de VSTO en pequeñas secciones para que resulte más fácil explicar la lógica detrás del código.

En este tutorial se muestran las tareas siguientes:

Diseñar la interfaz de usuario (UI) del panel de tareas personalizado.
Crear una interfaz de usuario de cinta de opciones personalizada.
Mostrar la interfaz de usuario personalizada de la cinta de opciones con mensajes de correo electrónico.
Crear una clase para administrar ventanas de inspector y paneles de tareas personalizados.
Inicializar y limpiar los recursos usados por el complemento de VSTO.
Sincronizar el botón de alternancia de la cinta de opciones con el panel de tareas personalizado.

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 2013 o Microsoft Outlook 2010.

Creación del proyecto

Los paneles de tareas personalizados se implementan en complementos de VSTO. Empiece por crear un proyecto de complemento de VSTO para Outlook.

Para crear un nuevo proyecto

Crear un proyecto Complemento de Outlook con el nombre OutlookMailItemTaskPane. Use la plantilla de proyecto Complemento de Outlook . Para obtener más información, vea Cómo: Crear proyectos de Office en Visual Studio.

Visual Studio abre el archivo de código ThisAddIn.cs o ThisAddIn.vb y agrega el proyecto OutlookMailItemTaskPane a Explorador de soluciones.

Diseño de la interfaz de usuario del panel de tareas personalizado

No hay ningún diseñador visual para los paneles de tareas personalizados, pero puede diseñar un control de usuario con la interfaz de usuario que desee. El panel de tareas personalizado de este complemento de VSTO tiene una interfaz de usuario simple que contiene un control TextBox . Más adelante en este tutorial, agregará el control de usuario al panel de tareas personalizado.

Para diseñar la interfaz de usuario del panel de tareas personalizado

En el Explorador de soluciones, haga clic en el proyecto OutlookMailItemTaskPane .
En el menú Proyecto , haga clic en Agregar control de usuario.
En el cuadro de diálogo Agregar nuevo elemento , cambie el nombre del control de usuario a TaskPaneControly haga clic en Agregar.

Se abre el control de usuario en el diseñador.
En la pestaña Controles comunes del Cuadro de herramientas, arrastre un control TextBox hasta el control de usuario.

Diseñar la interfaz de usuario de la cinta de opciones

Uno de los objetivos de este complemento de VSTO es proporcionar a los usuarios una manera de ocultar o mostrar el panel de tareas personalizado de la cinta de opciones de cada mensaje de correo electrónico. Para proporcionar la interfaz de usuario, cree una interfaz de usuario de cinta de opciones personalizada que muestre un botón de alternancia en el que los usuarios pueden hacer clic para mostrar u ocultar el panel de tareas personalizado.

Para crear una interfaz de usuario de cinta de opciones personalizada

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 por ManageTaskPaneRibbony haga clic en Agregar.

El archivo ManageTaskPaneRibbon.cs o ManageTaskPaneRibbon.vb se abre en el diseñador de la cinta de opciones y muestra una pestaña y un grupo predeterminados.
En el diseñador de la cinta de opciones, haga clic en group1para seleccionarlo.
En la ventana Propiedades , establezca el valor de la propiedad Label en Administrador de panel de tareas.
En la pestaña Controles de la cinta de opciones de Office del Cuadro de herramientas, arrastre un control ToggleButton al grupo Administrador de panel de tareas .
Haga clic en toggleButton1.
En la ventana Propiedades , establezca el valor de la propiedad Label en Mostrar panel de tareas.

Mostrar la interfaz de usuario personalizada de la cinta de opciones con mensajes de correo electrónico

El panel de tareas personalizado que va a crear en este tutorial se ha diseñado para que aparezca únicamente con las ventanas de inspector que contienen mensajes de correo. Por lo tanto, debe definir las propiedades de forma que la interfaz de usuario de la cinta de opciones personalizada solo aparezca con estas ventanas.

Para mostrar la interfaz de usuario personalizada de la cinta de opciones con mensajes de correo electrónico

En el diseñador de la cinta de opciones, haga clic en la cinta ManageTaskPaneRibbon .
En la ventana Propiedades , haga clic en la lista desplegable situada junto a RibbonTypey seleccione Microsoft.Outlook.Mail.Compose y Microsoft.Outlook.Mail.Read.

Creación de una clase para administrar ventanas de inspector y paneles de tareas personalizados

Hay varios casos en los que el complemento de VSTO debe identificar qué panel de tareas personalizado está asociado a un mensaje de correo electrónico específico. Estos casos son los siguientes:

Cuando el usuario cierra un mensaje de correo electrónico. En este caso, el complemento de VSTO debe quitar el panel de tareas personalizado correspondiente para garantizar que los recursos usados por el complemento de VSTO se limpian correctamente.
Cuando el usuario cierra el panel de tareas personalizado. En este caso, el complemento VSTO debe actualizar el estado del botón de alternancia en la cinta de opciones del mensaje de correo electrónico.
Cuando el usuario hace clic en el botón de alternancia de la cinta de opciones. En este caso, el complemento de VSTO debe ocultar o mostrar el panel de tareas correspondiente.

Para permitir que el complemento de VSTO realice un seguimiento del panel de tareas personalizado asociado a cada mensaje de correo electrónico abierto, cree una clase personalizada que encapsula pares de Inspector objetos y CustomTaskPane . Esta clase crea un nuevo objeto de panel de tareas personalizado para cada mensaje de correo electrónico y elimina el panel de tareas personalizado cuando se cierra el mensaje de correo electrónico correspondiente.

Para crear una clase para administrar ventanas de inspector y paneles de tareas personalizados

En el Explorador de soluciones, haga clic con el botón derecho en el archivo ThisAddIn.vb o ThisAddIn.cs y luego haga clic en Ver código.

Agregue las siguientes instrucciones en la parte superior del archivo.

using Microsoft.Office.Tools;

Imports System.Collections.Generic
Imports Microsoft.Office.Tools
Imports Office = Microsoft.Office.Core
Imports Outlook = Microsoft.Office.Interop.Outlook

Agregue el código siguiente al archivo ThisAddIn.cs o ThisAddIn.vb , fuera la clase ThisAddIn (para Visual C#, agregue este código dentro del espacio de nombres OutlookMailItemTaskPane ). La clase InspectorWrapper administra un par de objetos Inspector y CustomTaskPane . Completará la definición de esta clase en los pasos siguientes.
- C#
- VB
```
public class InspectorWrapper
{
    private Outlook.Inspector inspector;
    private CustomTaskPane taskPane;
```
```
Public Class InspectorWrapper
    Private inspector As Outlook.Inspector
    Private WithEvents inspectorEvents As Outlook.InspectorEvents_Event
    Private WithEvents taskPane As CustomTaskPane
```

Agregue el constructor siguiente después del código que agregó en el paso anterior. Este constructor crea e inicializa un nuevo panel de tareas personalizado que está asociado al objeto Inspector que se pasa. En C#, el constructor asocia también controladores de eventos al evento Close del objeto Inspector y al evento VisibleChanged del objeto CustomTaskPane .

public InspectorWrapper(Outlook.Inspector Inspector)
{
    inspector = Inspector;
    ((Outlook.InspectorEvents_Event)inspector).Close +=
        new Outlook.InspectorEvents_CloseEventHandler(InspectorWrapper_Close);
    
    taskPane = Globals.ThisAddIn.CustomTaskPanes.Add(
        new TaskPaneControl(), "My task pane", inspector);
    taskPane.VisibleChanged += new EventHandler(TaskPane_VisibleChanged);
}

Public Sub New(ByVal Inspector As Outlook.Inspector)
    Me.inspector = Inspector
    inspectorEvents = TryCast(Me.inspector, Outlook.InspectorEvents_Event)
    taskPane = Globals.ThisAddIn.CustomTaskPanes.Add(New TaskPaneControl(), _
        "My task pane", Inspector)
End Sub

Agregue el método siguiente después del código que agregó en el paso anterior. Este método es un controlador de eventos para el evento VisibleChanged de objeto CustomTaskPane que se encuentra en la clase InspectorWrapper . Este código actualiza el estado del botón de alternancia cada vez que el usuario abre o cierra el panel de tareas personalizado.

void TaskPane_VisibleChanged(object sender, EventArgs e)
{
    Globals.Ribbons[inspector].ManageTaskPaneRibbon.toggleButton1.Checked = 
        taskPane.Visible;
}

Private Sub TaskPane_VisibleChanged(ByVal sender As Object, ByVal e As EventArgs) _
    Handles taskPane.VisibleChanged
    Globals.Ribbons(inspector).ManageTaskPaneRibbon.ToggleButton1.Checked = taskPane.Visible
End Sub

Agregue el método siguiente después del código que agregó en el paso anterior. Este método es un controlador de eventos para el Close evento del objeto que contiene el mensaje de Inspector correo electrónico actual. El controlador de eventos libera recursos cuando se cierra el mensaje de correo electrónico. El controlador de eventos también quita el panel de tareas personalizado actual desde la colección CustomTaskPanes . Esto ayuda a evitar varias instancias del panel de tareas personalizado cuando se abre el siguiente mensaje de correo electrónico.

void InspectorWrapper_Close()
{
    if (taskPane != null)
    {
        Globals.ThisAddIn.CustomTaskPanes.Remove(taskPane);
    }

    taskPane = null;
    Globals.ThisAddIn.InspectorWrappers.Remove(inspector);
    ((Outlook.InspectorEvents_Event)inspector).Close -=
        new Outlook.InspectorEvents_CloseEventHandler(InspectorWrapper_Close);
    inspector = null;
}

Sub InspectorWrapper_Close() Handles inspectorEvents.Close
    If Not (taskPane Is Nothing) Then
        Globals.ThisAddIn.CustomTaskPanes.Remove(taskPane)
    End If

    taskPane = Nothing
    Globals.ThisAddIn.InspectorWrappers.Remove(inspector)
    RemoveHandler inspectorEvents.Close, AddressOf InspectorWrapper_Close
    inspector = Nothing
End Sub

Agregue el código siguiente después del código que agregó en el paso anterior. Más adelante en este tutorial, llamará a esta propiedad desde un método de la interfaz de usuario de la cinta de opciones para mostrar u ocultar el panel de tareas personalizado.

    public CustomTaskPane CustomTaskPane
    {
        get
        {
            return taskPane;
        }
    }
}

    Public ReadOnly Property CustomTaskPane() As CustomTaskPane
        Get
            Return taskPane
        End Get
    End Property
End Class

Inicialización y limpieza de recursos usados por el complemento

Agregue código a la clase ThisAddIn para inicializar el complemento de VSTO cuando este se cargue y para limpiar los recursos cuando dicho complemento se descargue. Para inicializar el complemento de VSTO, configure un controlador de eventos para el NewInspector evento y pase todos los mensajes de correo electrónico existentes a este controlador de eventos. Una vez que se descargue el complemento de VSTO, desasocie el controlador de eventos y limpie los objetos utilizados por el complemento de VSTO.

Para inicializar y limpiar los recursos usados por el complemento de VSTO

En el archivo ThisAddIn.cs o ThisAddIn.vb , busque la definición de la clase ThisAddIn .
Agregue las declaraciones siguientes a la clase ThisAddIn :
- El campo inspectorWrappersValue contiene todos los objetos Inspector y InspectorWrapper que administra el complemento de VSTO.
- El campo inspectors mantiene una referencia a la colección de ventanas de Inspector en la instancia actual de Outlook. Esta referencia impide que el recolector de elementos no usados libere la memoria que contiene el controlador de evento del evento NewInspector , que declarará en el paso siguiente.
  - C#
  - VB
```
private Dictionary<Outlook.Inspector, InspectorWrapper> inspectorWrappersValue =
    new Dictionary<Outlook.Inspector, InspectorWrapper>();
private Outlook.Inspectors inspectors;
```
```
Private inspectorWrappersValue As New Dictionary(Of Outlook.Inspector, InspectorWrapper)
Private WithEvents inspectors As Outlook.Inspectors
```

Reemplace el método ThisAddIn_Startup por el código siguiente. Este código asocia un controlador de eventos al evento NewInspector y pasa cada objeto Inspector existente al controlador de eventos. Si el usuario carga el complemento VSTO después de que Outlook ya se esté ejecutando, el complemento vsto usa esta información para crear paneles de tareas personalizados para todos los mensajes de correo electrónico que ya están abiertos.

private void ThisAddIn_Startup(object sender, System.EventArgs e)
{
    inspectors = this.Application.Inspectors;
    inspectors.NewInspector +=
        new Outlook.InspectorsEvents_NewInspectorEventHandler(
        Inspectors_NewInspector);

    foreach (Outlook.Inspector inspector in inspectors)
    {
        Inspectors_NewInspector(inspector);
    }
}

Private Sub ThisAddIn_Startup(ByVal sender As Object, ByVal e As System.EventArgs) _
    Handles Me.Startup

    inspectors = Me.Application.Inspectors
    Dim inspector As Outlook.Inspector
    For Each inspector In inspectors
        Inspectors_NewInspector(inspector)
    Next inspector
End Sub

Reemplace el método ThisAddIn_ShutDown por el código siguiente. Este código desasocia el controlador de eventos NewInspector y limpia los objetos usados por el complemento de VSTO.

private void ThisAddIn_Shutdown(object sender, System.EventArgs e)
{
    inspectors.NewInspector -=
        new Outlook.InspectorsEvents_NewInspectorEventHandler(
        Inspectors_NewInspector);
    inspectors = null;
    inspectorWrappersValue = null;
}

Private Sub ThisAddIn_Shutdown(ByVal sender As Object, ByVal e As System.EventArgs) _
    Handles Me.Shutdown

    RemoveHandler inspectors.NewInspector, AddressOf Inspectors_NewInspector
    inspectors = Nothing
    inspectorWrappersValue = Nothing
End Sub

Agregue el siguiente controlador de eventos NewInspector a la clase ThisAddIn . Si un nuevo Inspector contiene un mensaje de correo electrónico, el método crea una instancia de un nuevo InspectorWrapper objeto para administrar la relación entre el mensaje de correo electrónico y el panel de tareas correspondiente.

void Inspectors_NewInspector(Outlook.Inspector Inspector)
{
    if (Inspector.CurrentItem is Outlook.MailItem)
    {
        inspectorWrappersValue.Add(Inspector, new InspectorWrapper(Inspector));
    }
}

Sub Inspectors_NewInspector(ByVal Inspector As Outlook.Inspector) _
    Handles inspectors.NewInspector

    If TypeOf Inspector.CurrentItem Is Outlook.MailItem Then
        inspectorWrappersValue.Add(Inspector, New InspectorWrapper(Inspector))
    End If
End Sub

Agregue la siguiente propiedad a la clase ThisAddIn . Esta propiedad expone el campo inspectorWrappersValue privado al código que está fuera de la clase ThisAddIn .

public Dictionary<Outlook.Inspector, InspectorWrapper> InspectorWrappers
{
    get
    {
        return inspectorWrappersValue;
    }
}

Public ReadOnly Property InspectorWrappers() As Dictionary(Of Outlook.Inspector, InspectorWrapper)
    Get
        Return inspectorWrappersValue
    End Get
End Property

Punto de control

Compile el proyecto para asegurarse de que se compila sin errores.

Para compilar el proyecto

En el Explorador de soluciones, haga clic con el botón derecho en el proyecto OutlookMailItemTaskPane y luego haga clic en Compilar. Compruebe que el proyecto se compila sin errores.

Sincronizar el botón de alternancia cinta de opciones con el panel de tareas personalizado

Cuando el panel de tareas esté visible, el botón de alternancia aparecerá presionado y cuando el panel de tareas esté oculto, aparecerá sin presionar. Para sincronizar el estado del botón con el panel de tareas personalizado, modifique el controlador de eventos Click del botón de alternancia.

Para sincronizar el panel de tareas personalizado con el botón de alternancia

En el diseñador de la cinta de opciones, haga doble clic en el botón de alternancia Mostrar panel de tareas .

Visual Studio genera automáticamente un controlador de eventos denominado toggleButton1_Click, que controla el evento Click del botón de alternancia. Visual Studio también abre el archivo ManageTaskPaneRibbon.cs o ManageTaskPaneRibbon.vb en el Editor de código.

Agregue las instrucciones siguientes al comienzo del archivo ManageTaskPaneRibbon.cs o ManageTaskPaneRibbon.vb .

using Outlook = Microsoft.Office.Interop.Outlook;
using Microsoft.Office.Tools;

Imports Microsoft.Office.Tools.Ribbon
Imports Outlook = Microsoft.Office.Interop.Outlook
Imports Microsoft.Office.Tools

Reemplace el controlador de eventos toggleButton1_Click por el siguiente código: Cuando el usuario hace clic en el botón de alternancia, este método muestra u oculta el panel de tareas personalizado que está asociado a la ventana de inspector actual.

private void toggleButton1_Click(object sender, RibbonControlEventArgs e)
{
    Outlook.Inspector inspector = (Outlook.Inspector)e.Control.Context;
    InspectorWrapper inspectorWrapper = Globals.ThisAddIn.InspectorWrappers[inspector];
    CustomTaskPane taskPane = inspectorWrapper.CustomTaskPane;
    if (taskPane != null)
    {
        taskPane.Visible = ((RibbonToggleButton)sender).Checked;
    }
}

Private Sub ToggleButton1_Click(ByVal sender As System.Object, _
    ByVal e As Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs) _
    Handles ToggleButton1.Click

    Dim inspector As Outlook.Inspector = e.Control.Context
    Dim inspectorWrapper As InspectorWrapper = Globals.ThisAddIn.InspectorWrappers(inspector)
    Dim taskPane As CustomTaskPane = inspectorWrapper.CustomTaskPane
    If Not (taskPane Is Nothing) Then
        taskPane.Visible = TryCast(sender, RibbonToggleButton).Checked
    End If
End Sub

Prueba del proyecto

Cuando empiece a depurar el proyecto, Outlook se abrirá y se cargará el complemento de VSTO. El complemento VSTO muestra una instancia única del panel de tareas personalizado con cada mensaje de correo electrónico que se abre. Cree varios mensajes de correo electrónico para probar el código.

Para probar el complemento de VSTO

Presione F5.
En Outlook, haga clic en Nuevo para crear un nuevo mensaje de correo electrónico.
En la cinta de opciones del mensaje de correo electrónico, haga clic en la pestaña Complementos y, a continuación, haga clic en el botón Mostrar panel de tareas.

Compruebe que se muestra un panel de tareas con el título Mi panel de tareas con el mensaje de correo electrónico.
En el panel de tareas, escriba Primer panel de tareas en el cuadro de texto.
Cierre el panel de tareas.

Compruebe que el estado del botón Mostrar panel de tareas cambia y ya no aparece presionado.
Haga clic en el botón Mostrar panel de tareas de nuevo.

Compruebe que se abre el panel de tareas y que el cuadro de texto todavía contiene la cadena Primer panel de tareas.
En Outlook, haga clic en Nuevo para crear un segundo mensaje de correo electrónico.
En la cinta de opciones del mensaje de correo electrónico, haga clic en la pestaña Complementos y, a continuación, haga clic en el botón Mostrar panel de tareas.

Compruebe que se muestra un panel de tareas con el título Mi panel de tareas con el mensaje de correo electrónico y el cuadro de texto de este panel de tareas está vacío.
En el panel de tareas, escriba Segundo panel de tareas en el cuadro de texto.
Cambie el foco al primer mensaje de correo electrónico.

Compruebe que el panel de tareas asociado a este mensaje de correo electrónico sigue mostrando el primer panel de tareas en el cuadro de texto.

Este complemento de VSTO también administra escenarios más avanzados que puede probar. Por ejemplo, puede probar el comportamiento al ver correos electrónicos mediante los botones Elemento siguiente y Elemento anterior. También puede probar el comportamiento al descargar el complemento VSTO, abrir varios mensajes de correo electrónico y, a continuación, volver a cargar el complemento vsTO.

Pasos siguientes

En estos temas puede obtener más información sobre cómo crear paneles de tareas personalizados:

Cree un panel de tareas personalizado en un complemento de VSTO para una aplicación diferente. Para obtener más información sobre las aplicaciones que admiten paneles de tareas personalizados, consulte Paneles de tareas personalizados.
Automatizar una aplicación de Microsoft Office mediante un panel de tareas personalizado. Para obtener más información, consulte Tutorial: Automatización de una aplicación desde un panel de tareas personalizado.
Crear un botón de cinta de opciones en Excel que se puede usar para ocultar o mostrar un panel de tareas personalizado. Para obtener más información, vea Tutorial: Sincronizar un panel de tareas personalizado con un botón de cinta de opciones.