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

Artigo
08/08/2011

Cada item de host e o controle de host foi projetado para se comportar como uma palavra de Microsoft Office nativa correspondente ou o objeto do Excel de Microsoft Office, com funcionalidades adicionais. No entanto, existem algumas diferenças fundamentais entre o comportamento dos itens de host e controles de host e os objetos nativos do Office em tempo de execução.

Para obter informações gerais sobre itens de host e controles de host, consulte Itens de host e a 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 2007 e Excel 2010; Word 2007 e Word 2010. Para obter mais informações, consulte Recursos disponíveis pelo aplicativo do Office e o tipo de projeto.

Criar programaticamente os itens de Host

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

Em projetos de nível de documento, é possível criar itens de host em tempo de execução. Itens de host podem ser criados somente em tempo de design em projetos de nível de documento. For more information, see Item de Host do documento, Item de Host da pasta de trabalho, and Item de Host de planilha.

Em projetos de nível de aplicativo, você pode criar Microsoft.Office.Tools.Word.Document, Microsoft.Office.Tools.Excel.Workbook, ou Microsoft.Office.Tools.Excel.Worksheet itens do host em tempo de execução. For more information, see Estendendo os documentos do Word e pastas de trabalho do Excel em suplementos de nível de aplicativo em tempo de execução.

Criar programaticamente os controles de Host

Você pode programaticamente adicionar controles de host para um Microsoft.Office.Tools.Word.Document ou Microsoft.Office.Tools.Excel.Worksheet o item de host em tempo de execução. For more information, see Adicionar controles a documentos do Office em tempo de execução.

Não é possível adicionar controles de host para um nativo Microsoft.Office.Interop.Word.Document ou Microsoft.Office.Interop.Excel.Worksheet.

Observação
Os seguintes controles de host não podem ser adicionados programaticamente a planilhas ou documentos: XmlMappedRange, XMLNode, and XMLNodes.

Noções básicas sobre o diferenças de tipo entre os itens de Host, Host controles e objetos nativos do Office

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

Há vários cenários onde as diferenças entre os tipos de itens de host e controles de host e os objetos subjacentes nativos do Office podem afetar o seu código.

Controles de Host de passagem para métodos e propriedades

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

No Excel, há dois casos em que você deve usar o InnerObject a propriedade do controle de host para passar o controle de host para um método ou propriedade:

Quando o método ou propriedade espera que o objeto subjacente do Excel.
Quando o Microsoft.Office.Tools.Excel.ExcelLocale1033Attribute é definida como false em um projeto que tem como alvo o.NET Framework 3.5 e o método ou propriedade espera uma Object em vez do objeto subjacente do Excel. Para obter mais informações sobre o Microsoft.Office.Tools.Excel.ExcelLocale1033Attribute, consulte Formatação de dados no Excel com várias configurações regionais.

O exemplo a seguir cria um Microsoft.Office.Tools.Excel.NamedRange de controle e passá-lo para o AutoFill método. O código usa a InnerObject propriedade do intervalo nomeado para retornar o Office subjacente Microsoft.Office.Interop.Excel.Range que é necessária para o AutoFill método.

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);

Retornar tipos de propriedades e métodos nativos do Office

A maioria dos métodos e propriedades de itens de host retornam o objeto Office nativo subjacente na qual o item de host se baseia. Por exemplo, o Parent propriedade de um NamedRange hospedar o controle no Excel retorna um Microsoft.Office.Interop.Excel.Worksheet objeto em vez de um Microsoft.Office.Tools.Excel.Worksheet item de host. Da mesma forma, o Parent propriedade de um RichTextContentControl hospedar o controle retorna do Word uma Microsoft.Office.Interop.Word.Document objeto em vez de um Microsoft.Office.Tools.Word.Document item de host.

Acessando as coleções de controles de Host

O Visual Studio Tools for Office runtime não fornece coleções individuais para cada tipo de controle de host. Em vez disso, use o Controls são de propriedade de um item de host para iterar em todos os controles gerenciados (os controles de host e controles Windows Forms) no documento ou planilha e, em seguida, procurar itens que coincidam com o tipo de controle de host você interessado cm O exemplo de código a seguir examina cada controle em um documento do Word e determina se o controle é um 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 o Controls propriedade dos itens de host, consulte Adicionar controles a documentos do Office em tempo de execução.

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

Acessando novo 2010 do Excel e Word membros de 2010 em projetos que visam o.NET Framework 3.5

Em 2010 do Excel e Word 2010 projetos destinados a.NET Framework 3.5, a membros que foram introduzidos em 2010 do Office não estão disponíveis em itens de host e controles de host. Nesses projetos, itens de host e controles de host apenas tem membros que estavam disponíveis no sistema de Microsoft Office de 2007. Para acessar um membro que tenha sido adicionado em 2010 do Excel ou Word 2010, use o InnerObject a propriedade do controle de host para retornar o objeto subjacente nativo e então acessar o membro no objeto.

Por exemplo, em 2010 do Word, Microsoft.Office.Interop.Word.ContentControl objetos têm uma Checked propriedade pode ser usada para determinar se um controle de conteúdo da caixa de seleção está selecionado (essa propriedade não está disponível no Word 2007, pois o Word 2007 não tem controles de conteúdo da caixa de seleção). No Word 2010 projetos destinados a.NET Framework 3.5, o Microsoft.Office.Tools.Word.ContentControl o controle de host não tem um Checked propriedade. O exemplo de código a seguir demonstra como usar o InnerObject propriedade para acessar o Checked a propriedade da Microsoft.Office.Interop.Word.ContentControl objeto.

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;