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

Artículo
08/10/2011

Puede usar un complemento en el nivel de la aplicación para personalizar documentos de Word y libros de Excel de las siguientes maneras:

Agregar controles administrados a cualquier documento u hoja de cálculo abierta.
Crear etiquetas inteligentes que se reconocen en un documento o libro concreto.

Nota

Las etiquetas inteligentes están desusadas en Excel 2010 y Word 2010. Para obtener más información, vea Información general sobre etiquetas inteligentes.
Convertir un objeto de lista de una hoja de cálculo de Excel en un objeto ListObject extendido que exponga los eventos y se pueda enlazar a datos mediante el modelo de enlace de datos de Windows Forms.
Tener acceso a los eventos en el nivel de la aplicación que exponen Word y Excel para los documentos, libros y hojas de cálculo concretos.

Para usar esta funcionalidad, genere un objeto en tiempo de ejecución que extienda el documento o el libro.

Se aplica a: la información de este tema se aplica a los proyectos de nivel de aplicación para las siguientes aplicaciones: Excel 2007 y Excel 2010; Word 2007 y Word 2010. Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto de Office.

Generar objetos extendidos en complementos

Objetos extendidos son instancias de tipos que proporciona el runtime de Visual Studio Tools para Office para agregar funcionalidad a los objetos que existen de forma nativa en los modelos de objetos de Excel o Word (denominados objetos de Office nativos). Para generar un objeto extendido para un objeto de Excel o Word, utilice el método GetVstoObject. La primera vez que se llama al método GetVstoObject de un objeto de Word o Excel especificado, devuelve un nuevo objeto que extiende el objeto especificado. Cada vez que se llama al método y se especifica el mismo objeto de Word o Excel, devuelve el mismo objeto extendido.

El tipo del objeto extendido tiene el mismo nombre que el tipo del objeto de Office nativo, pero se define en el espacio de nombres Microsoft.Office.Tools.Word o Microsoft.Office.Tools.Excel. Por ejemplo, si llama al método GetVstoObject para extender un objeto Microsoft.Office.Interop.Word.Document, el método devuelve un objeto Microsoft.Office.Tools.Word.Document.

La manera en que tiene acceso al método GetVstoObject depende de a qué versión de .NET Framework está destinado su proyecto:

En proyectos destinados a .NET Framework 3.5, utilice el método GetVstoObject de una instancia de uno de los tipos siguientes en los ensamblados de interoperabilidad primarios de Excel y Word:
En proyectos destinados a .NET Framework 4, utilice el método Globals.Factory.GetVstoObject y pase el objeto de Word o Excel nativo (como Microsoft.Office.Interop.Word.Document o Microsoft.Office.Interop.Excel.Worksheet) que desea extender.

Los métodos GetVstoObject se utilizan principalmente en proyectos en el nivel de la aplicación. También puede utilizarlos en proyectos en el nivel del documento, pero se comportan de manera diferente y tienen menos usos. Para obtener más información, vea Obtener objetos extendidos a partir de objetos nativos de Office en personalizaciones en el nivel del documento.

Para determinar si ya se ha generado un objeto extendido para un objeto de Office nativo determinado, use el método HasVstoObject. Para obtener más información, vea Determinar si se ha extendido un objeto de Office.

Nota

Para usar los métodos HasVstoObject y GetVstoObject en un archivo de código distinto de ThisAddIn.cs o ThisAddIn.vb en un proyecto destinado a .NET Framework 3.5, debe modificar el proyecto. Para obtener más información, vea Configurar el proyecto para usar los métodos HasVstoObject y GetVstoObject.

Generar elementos host

Al utilizar GetVstoObject para extender un objeto de nivel de documento (es decir, Microsoft.Office.Interop.Excel.Workbook, Microsoft.Office.Interop.Excel.Worksheet o Microsoft.Office.Interop.Word.Document), el objeto devuelto se denomina elemento host. Un elemento host es un tipo que puede contener otros objetos, incluidos otros controles y objetos extendidos. Se parece al tipo correspondiente del ensamblado de interoperabilidad primario de Word o Excel, pero tiene características adicionales. Para obtener más información acerca de los elementos de host, vea Información general sobre elementos y controles Host.

Después de generar un elemento host, puede utilizarlo para agregar etiquetas inteligentes o controles administrados al documento, libro u hoja de cálculo. Para obtener más información, vea Agregar etiquetas inteligentes a documentos y libros y Agregar controles administrados a documentos y hojas de cálculo.

Para generar un elemento host para un documento de Word

En el siguiente ejemplo de código se muestra cómo generar un elemento host para el documento activo en un proyecto destinado a .NET Framework 4.

If Globals.ThisAddIn.Application.Documents.Count > 0 Then
    Dim NativeDocument As Microsoft.Office.Interop.Word.Document = _
        Globals.ThisAddIn.Application.ActiveDocument
    Dim VstoDocument As Microsoft.Office.Tools.Word.Document = _
        Globals.Factory.GetVstoObject(NativeDocument)
End If

if (Globals.ThisAddIn.Application.Documents.Count > 0)
{
    Microsoft.Office.Interop.Word.Document nativeDocument =
        Globals.ThisAddIn.Application.ActiveDocument;
    Microsoft.Office.Tools.Word.Document vstoDocument =
        Globals.Factory.GetVstoObject(nativeDocument);
}

En el siguiente ejemplo de código se muestra la misma tarea en un proyecto destinado a .NET Framework 3.5.

If Globals.ThisAddIn.Application.Documents.Count > 0 Then
    Dim NativeDocument As Microsoft.Office.Interop.Word.Document =
        Globals.ThisAddIn.Application.ActiveDocument
    If NativeDocument IsNot Nothing Then
        Dim vstoDocument As Microsoft.Office.Tools.Word.Document =
            NativeDocument.GetVstoObject()
    End If
End If

if (Globals.ThisAddIn.Application.Documents.Count > 0)
{
    Microsoft.Office.Interop.Word.Document nativeDocument =
        Globals.ThisAddIn.Application.ActiveDocument;
    Microsoft.Office.Tools.Word.Document vstoDocument =
        nativeDocument.GetVstoObject();
}

Para generar un elemento host para un libro de Excel

En el siguiente ejemplo de código se muestra cómo generar un elemento host para el libro activo en un proyecto destinado a .NET Framework 4.

Dim NativeWorkbook As Microsoft.Office.Interop.Excel.Workbook =
    Globals.ThisAddIn.Application.ActiveWorkbook
If NativeWorkbook IsNot Nothing Then
    Dim vstoWorkbook As Microsoft.Office.Tools.Excel.Workbook =
        Globals.Factory.GetVstoObject(NativeWorkbook)
End If

Microsoft.Office.Interop.Excel.Workbook nativeWorkbook = 
    Globals.ThisAddIn.Application.ActiveWorkbook;
if (nativeWorkbook != null)
{
    Microsoft.Office.Tools.Excel.Workbook vstoWorkbook = 
        Globals.Factory.GetVstoObject(nativeWorkbook);
}

En el siguiente ejemplo de código se muestra la misma tarea en un proyecto destinado a .NET Framework 3.5.

Dim NativeWorkbook As Microsoft.Office.Interop.Excel.Workbook = _
    Globals.ThisAddIn.Application.ActiveWorkbook

If NativeWorkbook IsNot Nothing Then
    Dim VstoWorkbook As Microsoft.Office.Tools.Excel.Workbook = _
        NativeWorkbook.GetVstoObject()
End If

Microsoft.Office.Interop.Excel.Workbook nativeWorkbook =
    Globals.ThisAddIn.Application.ActiveWorkbook;

if (nativeWorkbook != null)
{
    Microsoft.Office.Tools.Excel.Workbook vstoWorkbook =
        nativeWorkbook.GetVstoObject();
}

Para generar un elemento host para una hoja de cálculo de Excel

En el siguiente ejemplo de código se muestra cómo generar un elemento host para la hoja de cálculo activa en un proyecto destinado a .NET Framework 4.

Dim NativeWorksheet As Microsoft.Office.Interop.Excel.Worksheet =
    Globals.ThisAddIn.Application.ActiveSheet
If NativeWorksheet IsNot Nothing Then
    Dim vstoSheet As Microsoft.Office.Tools.Excel.Worksheet =
        Globals.Factory.GetVstoObject(NativeWorksheet)
End If

Microsoft.Office.Interop.Excel.Worksheet nativeWorksheet =
    Globals.ThisAddIn.Application.ActiveSheet;
if (nativeWorksheet != null)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoSheet = 
        Globals.Factory.GetVstoObject(nativeWorksheet);
}

En el siguiente ejemplo de código se muestra la misma tarea en un proyecto destinado a .NET Framework 3.5.

Dim NativeSheet As Microsoft.Office.Interop.Excel.Worksheet = _
    TryCast(Globals.ThisAddIn.Application.ActiveSheet,  _
    Microsoft.Office.Interop.Excel.Worksheet)

If NativeSheet IsNot Nothing Then
    Dim VstoSheet As Microsoft.Office.Tools.Excel.Worksheet = _
        NativeSheet.GetVstoObject()
End If

Microsoft.Office.Interop.Excel.Worksheet nativeSheet =
    Globals.ThisAddIn.Application.ActiveSheet as
    Microsoft.Office.Interop.Excel.Worksheet;

if (nativeSheet != null)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoSheet =
        nativeSheet.GetVstoObject();
}

Generar controles host ListObject

Al utilizar el método GetVstoObject para extender Microsoft.Office.Interop.Excel.ListObject, el método devuelve Microsoft.Office.Tools.Excel.ListObject. Microsoft.Office.Tools.Excel.ListObject tiene todas las características del Microsoft.Office.Interop.Excel.ListObject original, pero también tiene funcionalidad adicional, como la capacidad de enlazarse a datos utilizando el modelo de enlace de datos de Windows Forms. Para obtener más información, vea ListObject (Control).

Para generar un control host para un ListObject

El siguiente ejemplo de código muestra cómo generar un Microsoft.Office.Tools.Excel.ListObject para el primer Microsoft.Office.Interop.Excel.ListObject de la hoja de cálculo activa en un proyecto destinado a .NET Framework 4.

Dim sheet As Microsoft.Office.Interop.Excel.Worksheet =
    Globals.ThisAddIn.Application.ActiveSheet
If sheet.ListObjects.Count > 0 Then
    Dim listObject As Excel.ListObject = sheet.ListObjects(1)
    Dim vstoListObject As Microsoft.Office.Tools.Excel.ListObject =
        Globals.Factory.GetVstoObject(listObject)
End If

Microsoft.Office.Interop.Excel.Worksheet sheet =
    Globals.ThisAddIn.Application.ActiveSheet;
if (sheet.ListObjects.Count > 0)
{
    Excel.ListObject listObject = 
        sheet.ListObjects[1];
    Microsoft.Office.Tools.Excel.ListObject vstoListObject =
        Globals.Factory.GetVstoObject(listObject);
}

En el siguiente ejemplo de código se muestra la misma tarea en un proyecto destinado a .NET Framework 3.5.

Dim sheet As Excel.Worksheet = Globals.ThisAddIn.Application.ActiveSheet

If sheet.ListObjects.Count > 0 Then
    Dim listObject As Excel.ListObject = sheet.ListObjects(1)
    Dim vstoListObject As Microsoft.Office.Tools.Excel.ListObject = _
        listObject.GetVstoObject()
End If

Microsoft.Office.Interop.Excel.Worksheet sheet =
    Globals.ThisAddIn.Application.ActiveSheet as
    Microsoft.Office.Interop.Excel.Worksheet;

if (sheet.ListObjects.Count > 0)
{
    Excel.ListObject listObject = sheet.ListObjects[1];
    Microsoft.Office.Tools.Excel.ListObject vstoListObject =
        listObject.GetVstoObject();
}

Agregar etiquetas inteligentes a documentos y libros

Después de generar un Microsoft.Office.Tools.Word.Document o un Microsoft.Office.Tools.Excel.Workbook, puede crear una etiqueta inteligente que se reconozca en el contexto del documento o del libro que estos objetos representan. Para ello, use la propiedad VstoSmartTags de Microsoft.Office.Tools.Word.Document o Microsoft.Office.Tools.Excel.Workbook. Para obtener más información, vea los temas siguientes:

Agregar controles administrados a documentos y hojas de cálculo

Después de generar un Microsoft.Office.Tools.Word.Document o un Microsoft.Office.Tools.Excel.Worksheet, puede agregar controles al documento u hoja de cálculo que estos objetos extendidos representan. Para ello, use la propiedad Controls de Microsoft.Office.Tools.Word.Document o Microsoft.Office.Tools.Excel.Worksheet. Para obtener más información, vea Agregar controles a documentos de Office en tiempo de ejecución.

Puede agregar controles de formularios Windows Forms o controles host. Un control host es un control que proporciona Motor en tiempo de ejecución de Microsoft Visual Studio Tools para Office y que encapsula el control correspondiente en el ensamblado de interoperabilidad primario de Word o Excel. Un control host expone todo el comportamiento del objeto de Office nativo subyacente, pero también provoca eventos y se puede enlazar a datos utilizando el modelo de enlace de datos de los formularios Windows Forms. Para obtener más información, vea Información general sobre elementos y controles Host.

Nota

No puede agregar un control XmlMappedRange a una hoja de cálculo, ni un control XMLNodes o XMLNode a un documento utilizando un complemento. Estos controles host no pueden agregarse mediante programación. Para obtener más información, vea Limitaciones de programación de elementos y controles Host.

Conservar y quitar controles

Cuando se agregan controles administrados a un documento o a una hoja de cálculo, éstos no se conservan cuando se guarda y se cierra el documento. Se quitan todos los controles host y únicamente se dejan los objetos de Office nativos subyacentes (por ejemplo, un Microsoft.Office.Tools.Excel.ListObject se convierte en un Microsoft.Office.Interop.Excel.ListObject). También se quitan todos los controles de formularios Windows Forms, pero se dejan en el documento los contenedores de ActiveX para los controles. Debe incluir código en el complemento para limpiar los controles o volver a crearlos la próxima vez que se abra el documento. Para obtener más información, vea Guardar controles dinámicos en documentos de Office.

Acceso a eventos en el nivel de la aplicación en documentos y libros

Algunos eventos de documento, libro y hoja de cálculo de los modelos de objetos nativos de Word y de Excel solo se provocan en el nivel de la aplicación. Por ejemplo, se provoca el evento DocumentBeforeSave cuando un documento se abre en Word, pero este evento se define en la clase Microsoft.Office.Interop.Word.Application, en lugar de en la clase Microsoft.Office.Interop.Word.Document.

Cuando solo se utilizan objetos de Office nativos en el complemento, debe administrar estos eventos en el nivel de la aplicación y escribir el código adicional para determinar si el documento que provocó el evento es un documento que ha personalizado. Los elementos host proporcionan estos eventos en el nivel del documento, para que sea más fácil controlar los eventos para un documento concreto. Puede generar un elemento host y, a continuación, controlar el evento para dicho elemento host.

Ejemplo que utiliza objetos de Word nativos

En el ejemplo de código siguiente se muestra cómo administrar un evento en el nivel de la aplicación para los documentos de Word. El método CreateDocument crea un nuevo documento y, a continuación, define un controlador de eventos DocumentBeforeSave que evita que se guarde el documento. Dado que éste es un evento en el nivel de la aplicación que se provoca para el objeto Microsoft.Office.Interop.Word.Application, el controlador de eventos debe comparar el parámetro Doc con el objeto document1 para determinar si document1 representa el documento guardado.

Private document1 As Word.Document = Nothing

Private Sub CreateDocument1()
    document1 = Me.Application.Documents.Add()
End Sub

Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
    ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) _
    Handles Application.DocumentBeforeSave
    If Type.ReferenceEquals(Doc, document1) Then
        Cancel = True
    End If
End Sub

private Word.Document document1 = null;

private void CreateDocument1()
{
    document1 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    this.Application.DocumentBeforeSave += 
        new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
        Application_DocumentBeforeSave);
}

private void Application_DocumentBeforeSave(Word.Document Doc, 
    ref bool SaveAsUI, ref bool Cancel)
{
    if (Type.ReferenceEquals(Doc, document1)) 
    {
        Cancel = true;
    }
}

Ejemplos que utilizan un elemento host

En los ejemplos de código siguientes se simplifica este proceso controlando el evento BeforeSave de un elemento host Microsoft.Office.Tools.Word.Document. En estos ejemplos, el método CreateDocument2 genera un Microsoft.Office.Tools.Word.Document que extiende el objeto document2 y, a continuación, define un controlador de eventos BeforeSave que evita que el documento se guarde. Dado que solo se llama a este controlador de eventos cuando se guarda document2, el controlador puede cancelar la acción de guardado sin hacer tareas adicionales para comprobar qué documento se guardó.

En el siguiente ejemplo de código se muestra esta tarea en un proyecto destinado a .NET Framework 4.

Private document2 As Word.Document = Nothing
Private WithEvents vstoDocument As Microsoft.Office.Tools.Word.Document = Nothing

Private Sub CreateDocument2()
    document2 = Me.Application.Documents.Add()
    vstoDocument = Globals.Factory.GetVstoObject(document2)
End Sub

Private Sub vstoDocument_BeforeSave(ByVal sender As Object, _
    ByVal e As SaveEventArgs) Handles vstoDocument.BeforeSave
    e.Cancel = True
End Sub

private Word.Document document2 = null;
private Microsoft.Office.Tools.Word.Document vstoDocument = null;

private void CreateDocument2()
{
    document2 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    vstoDocument = Globals.Factory.GetVstoObject(document2);
    vstoDocument.BeforeSave += new SaveEventHandler(vstoDocument_BeforeSave);
}

private void vstoDocument_BeforeSave(object sender, SaveEventArgs e)
{
    e.Cancel = true;
}

En el siguiente ejemplo de código se muestra esta tarea en un proyecto destinado a .NET Framework 3.5.

Private document2 As Microsoft.Office.Interop.Word.Document = Nothing
Private WithEvents vstoDocument As Microsoft.Office.Tools.Word.Document = Nothing

Private Sub CreateDocument2()
    document2 = Me.Application.Documents.Add()
    vstoDocument = document2.GetVstoObject()
End Sub

Private Sub vstoDocument_BeforeSave(ByVal sender As Object,
    ByVal e As SaveEventArgs) Handles vstoDocument.BeforeSave
    e.Cancel = True
End Sub

private Word.Document document2 = null;
private Microsoft.Office.Tools.Word.Document vstoDocument = null;

private void CreateDocument2()
{
    document2 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    vstoDocument = document2.GetVstoObject();
    vstoDocument.BeforeSave += new SaveEventHandler(vstoDocument_BeforeSave);
}

private void vstoDocument_BeforeSave(object sender, SaveEventArgs e)
{
    e.Cancel = true;
}

Determinar si se ha extendido un objeto de Office

Para determinar si ya se ha generado un objeto extendido para un objeto de Office nativo determinado, use el método HasVstoObject. Este método devuelve true si ya se ha generado un objeto extendido; de lo contrario, devuelve false.

En proyectos destinados a .NET Framework 3.5, el método HasVstoObject está disponible en instancias de uno de los tipos siguientes en los ensamblados de interoperabilidad primarios de Excel y Word:

En proyectos destinados a .NET Framework 4, utilice el método Globals.Factory.HasVstoMethod. Pase el objeto de Word o Excel nativo (como Microsoft.Office.Interop.Word.Document o Microsoft.Office.Interop.Excel.Worksheet) que desea probar para un objeto extendido.

El método HasVstoObject es útil si desea ejecutar el código únicamente cuando un objeto de Office especificado tiene un objeto extendido. Por ejemplo, si tiene un complemento de Word que controla el evento DocumentBeforeSave para quitar controles administrados de un documento antes de guardarlo, puede utilizar el método HasVstoObject para determinar si se ha extendido el documento. Si no se ha extendido el documento, no puede contener los controles administrados y, por consiguiente, el controlador de eventos simplemente puede volver sin intentar limpiar los controles del documento.

Configurar proyectos de .NET Framework 3.5 para usar los métodos HasVstoObject y GetVstoObject

Cuando se crea un proyecto de nivel de aplicación destinado a .NET Framework 3.5, el proyecto se configura automáticamente para poder usar los métodos HasVstoObject y GetVstoObject del archivo de código ThisAddIn.cs o ThisAddIn.vb. Para utilizar estos métodos en un archivo de código distinto de ThisAddIn.cs o ThisAddIn.vb, debe hacer los cambios siguientes en el archivo de código.

Para modificar un archivo de código en un proyecto de Excel para crear objetos extendidos

Agregue las siguientes instrucciones using (para C#) o Imports (para Visual Basic) al principio del archivo de código en el que desee usar los métodos GetVstoObject y HasVstoObject.
```
Imports Microsoft.Office.Tools.Excel.Extensions
```
```
using Microsoft.Office.Tools.Excel.Extensions;
```

Para modificar un archivo de código en un proyecto de Word para crear objetos extendidos

Agregue las siguientes instrucciones using (para C#) o Imports (para Visual Basic) al principio del archivo de código en el que desee usar los métodos GetVstoObject y HasVstoObject.
```
Imports Microsoft.Office.Tools.Word.Extensions
```
```
using Microsoft.Office.Tools.Word.Extensions;
```

Se requieren estos cambios porque los métodos HasVstoObject y GetVstoObject se implementan como métodos de extensión. Aunque use los métodos HasVstoObject y GetVstoObject como si se definieran en tipos de los ensamblados de interoperabilidad primarios de Word o Excel, realmente se definen en tipos en los espacios de nombres Microsoft.Office.Tools.Word.Extensions y Microsoft.Office.Tools.Excel.Extensions de Motor en tiempo de ejecución de Microsoft Visual Studio Tools para Office. Para obtener más información sobre los métodos de extensión, vea Métodos de extensión (Guía de programación de C#) y Métodos de extensión (Visual Basic).