Limitaciones de programación de elementos y controles Host

Actualización: Julio de 2008

Los elementos y controles host están diseñados para comportarse como los objetos de Microsoft Office Excel o de Microsoft Office Word nativos correspondientes, pero con funcionalidad adicional. También hay algunas diferencias fundamentales entre el comportamiento de los elementos y controles host, y los objetos de Office nativos en tiempo de ejecución.

Para obtener información general sobre los elementos y los controles host, vea Información general sobre elementos y controles Host.

Crear elementos host mediante programación

Cuando crea o abre mediante programación un documento, un libro o una hoja de cálculo en tiempo de ejecución, el elemento no es un elemento host, sino que el nuevo objeto es un objeto de Office nativo. Por ejemplo, si utiliza el método Add para crear en tiempo de ejecución un nuevo documento de Word, será un objeto Microsoft.Office.Interop.Word.Document nativo en lugar de un elemento host Microsoft.Office.Tools.Word.Document. De igual forma, cuando crea una nueva hoja de cálculo en tiempo de ejecución usando el método Add, obtiene un objeto Microsoft.Office.Interop.Excel.Worksheet nativo en lugar de un elemento host Microsoft.Office.Tools.Excel.Worksheet.

En proyectos en el nivel del documento, no puede crear elementos host en tiempo de ejecución. Estos elementos solo se pueden crear en tiempo de diseño en proyectos en el nivel del documento. Para obtener más información, vea Elemento host Document, Elemento host Workbook e Elemento host Worksheet.

A partir de Visual Studio 2008 Service Pack 1 (SP1), puede crear en tiempo de ejecución elementos host Microsoft.Office.Tools.Word.Document, Microsoft.Office.Tools.Excel.Workbook o Microsoft.Office.Tools.Excel.Worksheet en complementos en el nivel de la aplicación para Excel 2007 y Word 2007. 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.

Crear controles host mediante programación

Puede agregar mediante programación controles host a un elemento host Microsoft.Office.Tools.Word.Document o Microsoft.Office.Tools.Excel.Worksheet en tiempo de ejecución. Para obtener más información, vea Agregar controles a documentos de Office en tiempo de ejecución.

No puede agregar controles host a un Microsoft.Office.Interop.Word.Document o Microsoft.Office.Interop.Excel.Worksheet nativo.

Nota:
Los controles host siguientes no se pueden agregar mediante programación a hojas de cálculo ni a documentos: XmlMappedRange, XMLNode y XMLNodes.

Diferencias de tipos entre los elementos y controles host, y los objetos de Office nativos

Existe un objeto nativo subyacente de Microsoft Office Word o Microsoft Office Excel por cada elemento y control host. Para obtener acceso al objeto subyacente, utilice la propiedad InnerObject del elemento o control host. Sin embargo, no hay forma de convertir un objeto de Office nativo en el elemento o control host correspondiente. Se produce una InvalidCastException cuando intenta convertir un objeto nativo de Office en elemento o control host.

Hay varios escenarios donde las diferencias entre los tipos de elementos y controles host, y los objetos de Office nativos subyacentes pueden afectar al código.

Pasar controles host a métodos y propiedades

En Word, no se puede pasar un control host a un método o una propiedad que requiera un objeto nativo de Word como parámetro. Se debe utilizar la propiedad InnerObject del control host para que se devuelva el objeto nativo subyacente de Word. Por ejemplo, se puede pasar un objeto Microsoft.Office.Interop.Word.Bookmark a un método pasando la propiedad InnerObject del control host Microsoft.Office.Tools.Word.Bookmark al método.

En Excel, hay dos casos en los que se debe utilizar la propiedad InnerObject del control host:

• Cuando el método o la propiedad espera el objeto subyacente de Excel.

• Cuando el atributo ExcelLocale1033Attribute tiene el valor false y el método o la propiedad espera un Object en lugar del objeto subyacente de Excel.

En el ejemplo siguiente se crea un control Microsoft.Office.Tools.Excel.NamedRange para pasarlo al método AutoFill. El código utiliza la propiedad InnerObject del rango con nombre para devolver el Microsoft.Office.Interop.Excel.Range de Office subyacente necesario para el método AutoFill.

Me.Range("A1").Value2 = "Monday"
Me.Range("A2").Value2 = "Tuesday"

Dim dayRange As Microsoft.Office.Tools.Excel.NamedRange = _
    Me.Controls.AddNamedRange(Me.Range("A1", "A7"), "dayRange")

Me.Range("A1", "A2").AutoFill(dayRange.InnerObject, Excel.XlAutoFillType.xlFillDays)

this.Range["A1", missing].Value2 = "Monday";
this.Range["A2", missing].Value2 = "Tuesday";

Microsoft.Office.Tools.Excel.NamedRange dayRange 
    = this.Controls.AddNamedRange(this.Range["A1", "A7"], "dayRange");

this.Range["A1", "A2"].AutoFill(dayRange.InnerObject, Excel.XlAutoFillType.xlFillDays);

Devolver tipos de métodos y propiedades de Office nativos

La mayoría de métodos y propiedades de los elementos de host devuelven el objeto de Office nativo subyacente en que se basa el elemento. Por ejemplo, la propiedad Parent de un control host NamedRange en Excel devuelve un objeto Microsoft.Office.Interop.Excel.Worksheet en lugar de un elemento host Microsoft.Office.Tools.Excel.Worksheet. De igual forma, la propiedad Parent de un control host RichTextContentControl en Word devuelve un objeto Microsoft.Office.Interop.Word.Document en lugar de un elemento host Microsoft.Office.Tools.Word.Document.

Acceso a las colecciones de controles host

Visual Studio Tools para Office no proporciona colecciones individuales para cada tipo de control host. Por ejemplo, no se puede enumerar cada control Microsoft.Office.Tools.Word.Bookmark del documento mediante la colección Microsoft.Office.Interop.Word.Bookmarks. La colección Microsoft.Office.Interop.Word.Bookmarks incluye todos los marcadores del documento; no distingue entre un control Microsoft.Office.Tools.Word.Bookmark y un Microsoft.Office.Interop.Word.Bookmark.

Puede utilizar las propiedades Document.Controls o Worksheet.Controls para recorrer en iteración todos los controles (los controles host y los controles de formularios Windows Forms) del documento u hoja de cálculo y después buscar elementos que coinciden con el tipo del control host que le interesa. En el ejemplo de código siguiente se examina cada control de un documento de Word y se determina si el control es Microsoft.Office.Tools.Word.Bookmark.

Dim targetControl As Object
For Each targetControl In Me.Controls

    If TypeOf (targetControl) Is Microsoft.Office.Tools.Word.Bookmark Then
        Dim bookMark As Microsoft.Office.Tools.Word.Bookmark = _
            CType(targetControl, Microsoft.Office.Tools.Word.Bookmark)

        ' Do some work with the book mark here.
    End If
Next

foreach (object targetControl in this.Controls)
{
    Microsoft.Office.Tools.Word.Bookmark bookMark = 
        targetControl as Microsoft.Office.Tools.Word.Bookmark;

    if (bookMark != null)
    {
        // Do some work with the book mark here.
    }
}

Vea también

Conceptos

Información general sobre elementos y controles Host

Elemento host Worksheet

Elemento host Workbook

Elemento host Document

Referencia

Worksheet.Controls

Document.Controls

Otros recursos

Controles Host de Word

Controles Host de Excel

Historial de cambios