Limitações de programação de itens de Host e controles de Host

Artigo
02/25/2013

Cada item de host e controle do host são criados para se comportar como um nativo correspondente Microsoft Office Word ou objeto do Microsoft Office Excel, com funcionalidade adicional.Em o entanto, há algumas diferenças entre fundamentais o comportamento de itens host e hospeda controles e Office nativo objetos em tempo de execução.

Para obter informações gerais sobre os itens host e controles host, consulte Itens de host e visão geral sobre controles de Host.

Aplicável a: As informações neste tópico se aplicam a projetos de nível de documento e projetos de nível de aplicativo para os seguintes aplicativos: Excel 2013 e Excel 2010; Word 2013 e Word 2010. Para obter mais informações, consulte Recursos disponíveis pelo aplicativo do Office e o tipo de projeto.

Criando itens programaticamente host

Quando você cria programaticamente ou abrir um documento, uma pasta de trabalho, ou uma planilha em tempo de execução usando o modelo de objeto do word ou o excel, o item não for um item host.Em vez de isso, o novo objeto é um objeto nativo do Office.Por exemplo, se você usar o método de Documents.Add para criar em tempo de execução um novo documento do word, será um objeto nativo de Microsoft.Office.Interop.Word.Document em vez de um item host de Microsoft.Office.Tools.Word.Document .De a mesma forma, quando você cria uma nova planilha em tempo de execução usando o método de Worksheets.Add , você obtém um objeto nativo de Microsoft.Office.Interop.Excel.Worksheet em vez de um item host de Microsoft.Office.Tools.Excel.Worksheet .

Em projetos de um documento nível, você não pode criar itens de hosts em tempo de execução.Os itens host podem ser criados somente em tempo de design em projetos de um documento nível.Para obter mais informações, consulte Item de Host do documento, Item de Host da pasta de trabalho, e Item de Host de planilha.

Em projetos de aplicativo, você pode criar Microsoft.Office.Tools.Word.Document, Microsoft.Office.Tools.Excel.Workbook, ou itens host de Microsoft.Office.Tools.Excel.Worksheet em tempo de execução.Para obter mais informações, consulte Estendendo os documentos do Word e pastas de trabalho do Excel em suplementos de nível de aplicativo em tempo de execução.

Criando controles programaticamente host

Você pode adicionar programaticamente controles host a um item de host de Microsoft.Office.Tools.Word.Document ou de Microsoft.Office.Tools.Excel.Worksheet em tempo de execução.Para obter mais informações, consulte Adicionar controles a documentos do Office em tempo de execução.

Você não pode adicionar controles host a Microsoft.Office.Interop.Word.Document nativo ou a Microsoft.Office.Interop.Excel.Worksheet.

Observação
Os seguintes controles host não podem ser adicionados por meio para planilhas ou para documentos: XmlMappedRange, XMLNode, e XMLNodes.

Entendendo as diferenças de tipo entre itens host, controles host, e objetos de nativo do Office

Para cada item do host e controle do host, há um nativo subjacente Microsoft Office Word ou um objeto do Microsoft Office Excel.Você pode acessar o objeto subjacente usando a propriedade de InnerObject de item de host ou hospedar o controle.Em o entanto, não há nenhuma maneira para converter um objeto nativo do Office ao item correspondente de host ou hospedar o controle.Se você tentar converter um objeto nativo do Office no tipo de um item de host ou hospedar o controle, InvalidCastException é lançada.

Há várias situações onde as diferenças entre os tipos de itens de host e controles host e objetos subjacentes do Office de ambos podem afetar seu código.

Passando controles host para os métodos e propriedade

Em as palavras, você não pode passar um controle do host a um método ou propriedade que requer um objeto nativo da palavra como um parâmetro.Você deve usar a propriedade de InnerObject de controle do host para retornar o objeto nativo subjacente da palavra.Por exemplo, você pode passar um objeto de Microsoft.Office.Interop.Word.Bookmark a um método passando a propriedade de InnerObject de controle do host de Microsoft.Office.Tools.Word.Bookmark para o método.

O excel, você deve usar a propriedade de InnerObject de controle do host para passar o controle hospedeiro a um método ou propriedade quando o método ou propriedade esperam o objeto subjacente do excel.

O exemplo a seguir cria um controle de Microsoft.Office.Tools.Excel.NamedRange e passá-lo para o método de AutoFill .O código a seguir usa a propriedade de InnerObject de intervalo nomeado para retornar o Office subjacente Microsoft.Office.Interop.Excel.Range que é exigido pelo método de 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);

Tipos de retorno de métodos e propriedades de nativo do Office

A maioria métodos e propriedades de itens host retorne o objeto subjacente do Office de nativo em que o item host é baseado.Por exemplo, a propriedade de Parent de um controle hospedeiro de NamedRange Excel retorna um objeto de Microsoft.Office.Interop.Excel.Worksheet em vez de um item host de Microsoft.Office.Tools.Excel.Worksheet .De a mesma forma, a propriedade de Parent de um controle hospedeiro de RichTextContentControl em palavras retorna um objeto de Microsoft.Office.Interop.Word.Document em vez de um item host de Microsoft.Office.Tools.Word.Document .

Acessando coleções de controles host

Visual Studio Tools for Office Runtime não fornece coleções individuais para cada tipo de controle do host.Em vez de isso, use a propriedade de Controls de um item host para iterar por todos os controles (controles gerenciados host e controles dos formulários do windows) em um documento ou planilha, e procure nos itens que correspondem ao tipo de controle host que você está interessado.O exemplo de código examina cada controle em um documento do word e determina se o controle é 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 obter mais informações sobre a propriedade de Controls de itens host, consulte Adicionar controles a documentos do Office em tempo de execução.

Os modelos de objeto da palavra e Excel incluem propriedades que expõem coleções de controles nativos em documentos e em planilhas.Você não pode acessar controles gerenciados usando essas propriedades.Por exemplo, não é possível especificar cada controle hospedeiro de Microsoft.Office.Tools.Word.Bookmark em um documento usando a propriedade de Bookmarks de Microsoft.Office.Interop.Word.Document ou a propriedade de Bookmarks de Microsoft.Office.Tools.Word.Document.Essas propriedades incluem apenas os controles de Microsoft.Office.Interop.Word.Bookmark no documento; não contêm os controles de host de Microsoft.Office.Tools.Word.Bookmark no documento.