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

Artículo
04/28/2010

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 aplicación 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.

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 aplicación

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.

A partir de Visual Studio 2008 Service Pack 1 (SP1), puede utilizar un complemento en el nivel de la aplicación para personalizar documentos y libros de las maneras siguientes:

Agregar controles administrados a cualquier documento u hoja de cálculo abierta.
Crear etiquetas inteligentes que se reconocen en un documento o libro concreto.
Convertir un objeto de lista existente en una hoja de cálculo de Excel en un objeto de lista de Visual Studio Tools para Office que expone los eventos y se puede enlazar a datos utilizando el modelo de enlace de datos de los formularios 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 utilizar esta funcionalidad, genere un objeto de Visual Studio Tools para Office en tiempo de ejecución que extienda el documento o el libro.

Generar objetos extendidos en complementos

Los objetos extendidos son objetos de Visual Studio Tools para Office que agregan funcionalidad a los objetos que existen de manera nativa en los modelos de objetos de Word o Excel (llamados objetos de Office nativos). Para generar un objeto extendido en un complemento, utilice el método GetVstoObject de una instancia de uno de los tipos siguientes de los ensamblados de interoperabilidad primarios de Excel y Word:

La primera vez que llama al método GetVstoObject de un objeto nativo de Office, devuelve un nuevo objeto de Visual Studio Tools para Office que extiende el objeto. Cada vez que llama al método en el mismo un objeto de Office nativo, 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, el método GetVstoObject de un objeto Microsoft.Office.Interop.Word.Document devuelve Microsoft.Office.Tools.Word.Document.

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

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.

Nota:
Para utilizar métodos HasVstoObject y GetVstoObject en un archivo de código distinto de ThisAddIn.cs o ThisAddIn.vb, o en un proyecto creado antes de instalar el SP1, 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 el método GetVstoObject de un objeto en el nivel del documento, es decir, un 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

Use el método GetVstoObject de un Microsoft.Office.Interop.Word.Document. En el ejemplo de código siguiente se genera un elemento host para el documento activo.

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 = _
        NativeDocument.GetVstoObject()
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

Use el método GetVstoObject de un Microsoft.Office.Interop.Excel.Workbook. En el ejemplo de código siguiente se genera un elemento host para el libro activo.

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

Use el método GetVstoObject de un Microsoft.Office.Interop.Excel.Worksheet. En el ejemplo de código siguiente se genera un elemento host para la hoja activa.

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 de Microsoft.Office.Interop.Excel.ListObject, el método devuelve Microsoft.Office.Tools.Excel.ListObject. El Microsoft.Office.Tools.Excel.ListObject generado 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 los formularios Windows Forms. Para obtener más información, vea ListObject (Control).

Para generar un control host para un ListObject

Use el método GetVstoObject de un Microsoft.Office.Interop.Excel.ListObject. En el ejemplo de código siguiente se genera un Microsoft.Office.Tools.Excel.ListObject para el primer Microsoft.Office.Interop.Excel.ListObject de la hoja de cálculo activa.

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 de Visual Studio Tools para Office que contiene un 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 CreateDocument1 de este ejemplo 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;
    }
}

Ejemplo que utiliza un elemento host

En el ejemplo de código siguiente se simplifica este proceso administrando el evento BeforeSave de un elemento host Microsoft.Office.Tools.Word.Document. En este ejemplo, 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ó.

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 = 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 de Visual Studio Tools para Office para un objeto de Office nativo determinado, utilice el método HasVstoObject del objeto de Office. Este método devuelve true si ya se ha generado un objeto extendido; de lo contrario, devuelve false.

Esto es útil si se 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 el proyecto para utilizar los métodos HasVstoObject y GetVstoObject

Cuando crea un proyecto en el nivel de la aplicación después de instalar Visual Studio 2008 SP1, el proyecto se configura automáticamente para que pueda utilizar los métodos HasVstoObject y GetVstoObject en los archivos 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.Excel.Extensions
```
```
using Microsoft.Office.Tools.Excel.Extensions;
```

Para utilizar estos métodos en un proyecto en el nivel de la aplicación creado antes de instalar el SP1, debe realizar los cambios siguientes en el proyecto.

Para modificar un complemento de Excel existente para crear objetos extendidos

Agregue una referencia al ensamblado Microsoft.Office.Tools.Excel.v9.0.dll.
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 complemento de Word existente para crear objetos extendidos

Agregue una referencia al ensamblado Microsoft.Office.Tools.Word.v9.0.dll.
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 utilice 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 del motor en tiempo de ejecución de 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).