Limitaciones de programación de elementos y controles Host

Artículo
02/19/2013

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.

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

Crear elementos host mediante programación

Cuando se crea o se abre mediante programación un documento, un libro o una hoja de cálculo en tiempo de ejecución usando el modelo de objetos de Word o Excel, 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 Documents.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 Worksheets.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 y Elemento host Worksheet.

En proyectos de nivel de aplicación, se pueden crear elementos host Microsoft.Office.Tools.Word.Document, Microsoft.Office.Tools.Excel.Workbook o Microsoft.Office.Tools.Excel.Worksheet 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.

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, debe utilizar la propiedad InnerObject del control host para pasar el control host a un método o una propiedad cuando el método o la propiedad espera el 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"].Value2 = "Monday";
this.Range["A2"].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

El Runtime de Microsoft Visual Studio Tools para Office no proporciona colecciones individuales para cada tipo de control host.En su lugar, utilice la propiedadControls de un elemento host para iterar por todos los controles administrados (controles host y controles de Windows Forms) en el documento o la hoja de cálculo y, a continuación, busque elementos que coincidan con el tipo del control host de su interés.En el siguiente ejemplo de código, se examina cada control de un documento de Word y se determina si el control es un objeto 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 bookmark here.
    }
}

Para obtener más información sobre la propiedad Controls de los elementos host, vea Agregar controles a documentos de Office en tiempo de ejecución.

Los modelos de objetos de Excel y Word incluyen propiedades que exponen colecciones de controles nativos en los documentos y hojas de cálculo.No se puede obtener acceso a los controles administrados mediante estas propiedades.Por ejemplo, no es posible enumerar cada control host Microsoft.Office.Tools.Word.Bookmark en un documento mediante la propiedad Bookmarks de un objeto Microsoft.Office.Interop.Word.Document o la propiedad Bookmarks de un objeto Microsoft.Office.Tools.Word.Document.Estas propiedades incluyen solo los controles Microsoft.Office.Interop.Word.Bookmark del documento; no contienen los controles host Microsoft.Office.Tools.Word.Bookmark del documento.