Obtener objetos extendidos a partir de objetos nativos de Office en personalizaciones en el nivel del documento

Actualización: Julio de 2008

Se aplica a

La información de este tema sólo se aplica a los proyectos de Visual Studio Tools para Office y versiones de Microsoft Office especificados.

Tipo de proyecto

  • Proyectos de nivel de documento

Versión de Microsoft Office

  • Excel 2007

  • Word 2007

Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto.

Muchos controladores de eventos de Office reciben un objeto de Office nativo que representa el libro, la hoja de cálculo o el documento que provocó el evento. En algunos casos, le puede interesar ejecutar cierto código solo si el libro o el documento de su personalización en el nivel del documento provocó el evento. Por ejemplo, en una personalización en el nivel del documento para Excel, le podría interesar ejecutar código cuando el usuario activa uno de los elementos host Microsoft.Office.Tools.Excel.Worksheet en la personalización, pero no cuando el usuario activa una hoja de cálculo en algún otro libro que está abierto al mismo tiempo.

A partir de Visual Studio 2008 Service Pack 1 (SP1), al obtener un objeto de Office nativo, puede probar si ese objeto se ha extendido en un elemento host o control host Microsoft.Office.Tools.Excel.ListObject en una personalización en el nivel del documento.

Los elementos host y controles host son objetos de Visual Studio Tools para Office que agregan la funcionalidad a los objetos que existen de forma nativa en los modelos de objetos de Excel o de Word (llamados objetos de Office nativos). Colectivamente, los elementos y los controles host se denominan también objetos extendidos. Para obtener más información sobre los elementos y los controles host, vea Información general sobre elementos y controles Host.

Utilizar los métodos HasVstoObject y GetVstoObject

Para probar un objeto de Office nativo, utilice los métodos GetVstoObject y HasVstoObject de una instancia de uno de los objetos de Office nativos siguientes:

Si únicamente desea determinar si el objeto de Office nativo tiene un objeto extendido en la personalización, utilice el método HasVstoObject. Este método devuelve true si el objeto de Office nativo tiene un objeto extendido, y false si no lo tiene.

Si desea obtener el objeto extendido, utilice el método GetVstoObject. Este método devuelve un Microsoft.Office.Tools.Excel.ListObject, Microsoft.Office.Tools.Excel.Workbook, Microsoft.Office.Tools.Excel.Worksheet o Microsoft.Office.Tools.Word.Document si el objeto de Office nativo tiene uno. De lo contrario, GetVstoObject devuelve null. Por ejemplo, el método GetVstoObject de un objeto Microsoft.Office.Interop.Word.Document devuelve Microsoft.Office.Tools.Word.Document si Microsoft.Office.Interop.Word.Document es el objeto subyacente del documento en el proyecto de documento de Word.

No puede utilizar GetVstoObject en una solución en el nivel del documento para crear un nuevo elemento host en tiempo de ejecución. Solo puede utilizarlo para tener acceso a los elementos host existentes que se generan en tiempo de diseño en el proyecto. Para obtener más información, vea Limitaciones de programación de elementos y controles Host.

En proyectos en el nivel de la aplicación, puede utilizar el método GetVstoObject para generar nuevos elementos host en tiempo de ejecución. Para obtener más información, vea Ampliar documentos de Word y libros de Excel en complementos en el nivel de la aplicación en tiempo de ejecución.

Nota:

Para utilizar los métodos HasVstoObject y GetVstoObject, debe agregar instrucciones Imports (para Visual Basic) o using (para C#) para los espacios de nombres Microsoft.Office.Tools.Word.Extensions o Microsoft.Office.Tools.Excel.Extensions en la parte superior del archivo de código. Los métodos HasVstoObject y GetVstoObject se implementan como métodos de extensión en el motor en tiempo de ejecución de Visual Studio Tools para Office y estas instrucciones permiten llamar a estos métodos.

Determinar si un elemento host provocó un evento

En el siguiente ejemplo de código se muestran los métodos HasVstoObject y GetVstoObject. Ambos ejemplos controlan el evento SheetActivate de la clase ThisWorkbook en un proyecto de libro de Excel.

El primer ejemplo determina si uno de los elementos host Microsoft.Office.Tools.Excel.Worksheet se activó comparando el parámetro Sh con la propiedad InnerObject de cada elemento host predeterminado.

Sub ThisWorkbook_SheetActivate1(ByVal Sh As Object) Handles Me.SheetActivate
    Dim vstoWorksheet As Microsoft.Office.Tools.Excel.Worksheet = Nothing

    If Type.ReferenceEquals(Globals.Sheet1.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet1
    ElseIf Type.ReferenceEquals(Globals.Sheet2.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet2
    ElseIf Type.ReferenceEquals(Globals.Sheet3.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet3
    End If

    If vstoWorksheet IsNot Nothing Then
        ' Do something with the VSTO worksheet here.
    End If
End Sub
void ThisWorkbook_SheetActivate1(object Sh)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoWorksheet = null;

    if (Type.ReferenceEquals(Globals.Sheet1.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet1;
    else if (Type.ReferenceEquals(Globals.Sheet2.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet2;
    else if (Type.ReferenceEquals(Globals.Sheet3.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet3;

    if (vstoWorksheet != null)
    {
        // Do something with the VSTO worksheet here.
    }
}

En el ejemplo siguiente se simplifica este proceso utilizando los métodos GetVstoObject y HasVstoObject del parámetro Sh.

Sub ThisWorkbook_SheetActivate2(ByVal Sh As Object) Handles Me.SheetActivate
    Dim vstoWorksheet As Microsoft.Office.Tools.Excel.Worksheet = Nothing
    Dim interopWorksheet As Microsoft.Office.Interop.Excel.Worksheet = _
        CType(Sh, Microsoft.Office.Interop.Excel.Worksheet)

    If interopWorksheet IsNot Nothing AndAlso _
        interopWorksheet.HasVstoObject() Then
        vstoWorksheet = interopWorksheet.GetVstoObject()
    End If

    If vstoWorksheet IsNot Nothing Then
        ' Do something with the VSTO worksheet here.
    End If
End Sub
void ThisWorkbook_SheetActivate2(object Sh)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoWorksheet = null;
    Microsoft.Office.Interop.Excel.Worksheet interopWorksheet = 
        Sh as Microsoft.Office.Interop.Excel.Worksheet;

    if (interopWorksheet != null && interopWorksheet.HasVstoObject())
    {
        vstoWorksheet = interopWorksheet.GetVstoObject();
    }

    if (vstoWorksheet != null)
    {
        // Do something with the VSTO worksheet here.
    }
}

Vea también

Conceptos

Programar personalizaciones de nivel de documento

Información general sobre elementos y controles Host

Ampliar documentos de Word y libros de Excel en complementos en el nivel de la aplicación en tiempo de ejecución

Métodos de extensión (Visual Basic)

Referencia

Métodos de extensión (Guía de programación de C#)

Historial de cambios

Fecha

Historial

Motivo

Julio de 2008

Se ha agregado un tema.

Cambio de características de SP1.