Limitaciones mediante programación de elementos host y controles host
Los elementos y controles host están diseñados para comportarse como los objetos de Microsoft Office Word o Microsoft Office Excel nativos correspondientes, pero con funcionalidad adicional. Sin embargo, hay algunas diferencias fundamentales entre el comportamiento de los elementos y los controles host y los objetos nativos de Office en tiempo de ejecución.
Para obtener información general sobre los elementos host y los controles host, consulte Información general sobre los elementos host y los controles host.
Se aplica a: La información de este tema se aplica a proyectos de nivel de documento y proyectos de complementos de VSTO para Excel y Word. Para obtener más información, consulte Características disponibles por aplicación de Office lication y tipo de proyecto.
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 usa el método Add para crear un nuevo documento de Word en tiempo de ejecución, será un objeto Document nativo en lugar de un elemento host Document . De forma similar, cuando crea una nueva hoja de cálculo en tiempo de ejecución mediante el método Add , obtiene un objeto Worksheet nativo en lugar de un elemento host Worksheet .
En los proyectos de nivel de documento, no es posible crear elementos host en tiempo de ejecución. Los elementos host pueden crearse solo en tiempo de diseño en proyectos de nivel de documento. Para obtener más información, vea Elemento host de documento, Elemento host del libro y Elemento host de hoja de cálculo.
En los proyectos de complemento de VSTO, se puede crear los elementos host Document, Workbooko Worksheet en tiempo de ejecución. Para obtener más información, vea Extender documentos de Word y libros de Excel en complementos de VSTO en tiempo de ejecución.
Crear controles host mediante programación
Puede agregar mediante programación controles host a un elemento host Document o 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 se pueden agregar controles host a Document o Worksheetnativo.
Nota:
Los controles host siguientes no se pueden agregar mediante programación a hojas de cálculo ni documentos: XmlMappedRange, XMLNodey XMLNodes.
Descripción de las diferencias de tipos entre los elementos host, los controles host y los objetos nativos de Office
Existe un objeto nativo subyacente de Microsoft Office Word o Microsoft Office Excel por cada elemento y control host. Puede acceder al objeto subyacente mediante la propiedad InnerObject del elemento host o el control host. Sin embargo, no hay forma de convertir un objeto nativo de Office en el elemento o control host correspondiente. Si se intenta convertir un objeto nativo de Office en el tipo de un elemento o control host, se produce una InvalidCastException .
Hay varios escenarios donde las diferencias entre los tipos de elementos y controles host y los objetos nativos de Office 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. Debe usar la propiedad InnerObject del control host para devolver el objeto nativo subyacente de Word. Por ejemplo, puede pasar un objeto Bookmark a un método pasando la propiedad InnerObject del control host Bookmark al método.
En Excel, debe usar la propiedad InnerObject del control host para pasar el control host a un método o propiedad cuando el método o la propiedad espera el objeto de Excel subyacente.
En el ejemplo siguiente se crea un control NamedRange para pasarlo al método AutoFill . El código usa la propiedad InnerObject del rango con nombre para devolver el Range subyacente de Office necesario para el método AutoFill .
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);
Tipos devueltos de propiedades y métodos nativos de Office
La mayoría de los métodos y propiedades de lo elementos host devuelven el objeto de Office nativo subyacente en el que se basa el elemento host. Por ejemplo, la propiedad Parent de un control host NamedRange en Excel devuelve un objeto Worksheet en lugar de un elemento host Worksheet . De igual forma, la propiedad Parent de un control host RichTextContentControl en Word devuelve un objeto Document en lugar de un elemento host Document .
Acceso a colecciones de controles host
El entorno de ejecución de Visual Studio Tools para Office no proporciona colecciones individuales para cada tipo de control host. En su lugar, use la propiedad Controls de un elemento host para recorrer en iteración todos los controles administrados (controles host y controles de Windows Forms) en el documento o hoja de cálculo y busque elementos que coincidan con el tipo del control host que le interese. En el siguiente ejemplo de código se examina cada control en un documento de Word y se determina si el control es un control Bookmark.
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 Word y Excel incluyen propiedades que exponen colecciones de controles nativos en los documentos y las hojas de cálculo. No se puede acceder a los controles administrados mediante estas propiedades. Por ejemplo, no es posible enumerar cada control host Bookmark en un documento mediante la propiedad Bookmarks de un objeto Document o la propiedad Bookmarks de un objeto Document. Estas propiedades incluyen solo los controles Bookmark del documento; no contienen los controles host Bookmark del documento.