Limitaciones de programación de elementos y controles Host

Artículo
08/10/2011

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 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.

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, hay dos casos en los que se 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.
Cuando el valor de Microsoft.Office.Tools.Excel.ExcelLocale1033Attribute está establecido en false en un proyecto destinado a .NET Framework 3.5, y el método o la propiedad espera un Object en lugar del objeto de Excel subyacente. Para obtener más información acerca de Microsoft.Office.Tools.Excel.ExcelLocale1033Attribute, vea Aplicar formato a datos de Excel con varias configuraciones regionales.

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

El Motor en tiempo de ejecución 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.

Obtener acceso a los nuevos miembros de Excel 2010 y Word 2010 en proyectos destinados a .NET Framework 3.5

En los proyectos de Excel 2010 y Word 2010 destinados a .NET Framework 3.5, los miembros que se introdujeron en Office 2010 no están disponibles en los elementos host ni los controles host. En estos proyectos, los elementos host y los controles host solo tienen los miembros que estaban disponibles en 2007 Microsoft Office system. Para obtener acceso a un miembro que se agregó en Excel 2010 o Word 2010, utilice la propiedad InnerObject del control host para devolver el objeto nativo subyacente y, a continuación, obtenga acceso al miembro en ese objeto.

Por ejemplo, en Word 2010, los objetos Microsoft.Office.Interop.Word.ContentControl tienen la propiedad Checked que se puede utilizar para determinar si está seleccionado un control de contenido de casilla (esta propiedad no está disponible en Word 2007 porque esta aplicación no tiene controles de contenido de casilla). En proyectos de Word 2010 destinados a .NET Framework 3.5, el control host Microsoft.Office.Tools.Word.ContentControl no tiene la propiedad Checked. En el ejemplo de código siguiente, se muestra cómo usar la propiedad InnerObject para obtener acceso a la propiedad Checked del objeto Microsoft.Office.Interop.Word.ContentControl subyacente.

Me.Paragraphs(1).Range.InsertParagraphBefore()
Me.Paragraphs(1).Range.Select()
Dim checkBoxControl1 As Microsoft.Office.Tools.Word.ContentControl =
    Me.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox)

' The following line of code compiles in projects that target the .NET Framework 4, but it does not compile 
' in projects that target the .NET Framework 3.5.
checkBoxControl1.Checked = True

' In projects that target the .NET Framework 3.5, use the following code.
checkBoxControl1.InnerObject.Checked = True

this.Paragraphs[1].Range.InsertParagraphBefore();
this.Paragraphs[1].Range.Select();
Microsoft.Office.Tools.Word.ContentControl checkBoxControl1 = 
    this.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox);

// The following line of code compiles in projects that target the .NET Framework 4, but it does not compile 
// in projects that target the .NET Framework 3.5.
checkBoxControl1.Checked = true;

// In projects that target the .NET Framework 3.5, use the following code.
checkBoxControl1.InnerObject.Checked = true;