Itens de host e visão geral sobre controles de Host

Artigo
02/25/2013

Os itens host e controles host são os tipos que ajudam a fornecer o modelo de programação para soluções do Office que são criados usando as ferramentas de desenvolvimento do Office no Visual Studio.Os itens host e controles host tornam interagir com os modelos de objeto do Microsoft Office Word e Microsoft Office Excel, que são baseados em COM, mais como interagir com objetos gerenciados como controles de formulários do windows.

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.

Itens host

Os itens host são os tipos que estão na parte superior de hierarquias de modelo de objeto em projetos do Office.Visual Studio Tools for Office Runtime define os seguintes itens host para soluções da palavra e Excel:

Cada um de esses tipos estendem um objeto nativo que existe no modelo de objeto do word ou o excel, chamado um objeto nativo do Office.Por exemplo, o item host de Microsoft.Office.Tools.Word.Document estende o objeto de Microsoft.Office.Interop.Word.Document , que é definido no assembly de interoperabilidade primária para palavra.

Os itens host geralmente têm a mesma funcionalidade básica que objetos correspondentes do Office, mas são aprimorados com os seguintes recursos:

A capacidade para hospedar controles gerenciados, incluindo controles host e controles dos formulários do windows.
Modelos de eventos mais ricos.Alguns documento, pasta de trabalho, e eventos da planilha nos modelos de objeto nativos de palavras Excel e são gerados apenas a nível do aplicativo.Os itens host fornecem esses eventos no nível do documento, de modo que é mais fácil manipular os eventos para um documento específico.

Entendendo host de itens em projetos de um documento Nível

Em projetos de um documento nível, os itens host fornecem um ponto de entrada para seu código, e possuem os designers que ajudam a desenvolver sua solução.

Os itens host de Microsoft.Office.Tools.Word.Document e de Microsoft.Office.Tools.Excel.Worksheet possui os designers que são a representação visual de documento ou planilha, como um windows form designer.Você pode usar este designer para modificar o conteúdo do documento ou a planilha diretamente nas palavras ou o excel, e para arrastar controles a superfície de design.Para obter mais informações, consulte Item de Host do documento e Item de Host de planilha.

O item host de Microsoft.Office.Tools.Excel.Workbook não atua como um recipiente para os controles que têm uma interface do usuário.Em vez de isso, o designer para este item host funciona como uma bandeja de componentes, que permite que você arraste um componente, como DataSet, na superfície de design.Para obter mais informações, consulte Item de Host da pasta de trabalho.

Os itens host não podem ser criados por programação em projetos de um documento nível.Em vez de isso, use ThisDocument, ThisWorkbook, ou classes de Sheetem que o Visual Studio gera automaticamente em seu projeto em tempo de design.Essas classes geradas derivam de itens host, e fornecem um ponto de entrada para seu código.Para obter mais informações, consulte Limitações de programação de itens de Host e controles de Host.

Entendendo host de itens em projetos de Nível de aplicativo

Quando você cria um suplemento ao aplicativo, você não tem acesso aos itens host por padrão.Em o entanto, você pode gerar Microsoft.Office.Tools.Word.Document, Microsoft.Office.Tools.Excel.Workbook, e itens Microsoft.Office.Tools.Excel.Worksheet no host de suplementos da palavra e o excel em tempo de execução.

Depois que você gerar um item host, você pode executar tarefas como adicionar controles aos documentos.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.

Controles de host

Os controles de host estendem mais objetos de interface do usuário (UI) nos modelos de objeto da palavra e Excel, como Microsoft.Office.Interop.Word.ContentControl e objetos de Microsoft.Office.Interop.Excel.Range .

Os seguintes controles host estão disponíveis para projetos do excel:

Os seguintes controles host estão disponíveis para projetos do word:

Hospedar controles que são adicionados aos documentos do Office se comportam como objetos nativos do Office; entretanto, os controles de host têm funcionalidade adicional, incluindo eventos e recursos de associação de dados.Por exemplo, quando você deseja capturar eventos de um objeto nativo de Microsoft.Office.Interop.Excel.Range o excel, primeiro você deve manipular o evento de alteração da planilha.Então você deve determinar se a mudança ocorreu dentro de Microsoft.Office.Interop.Excel.Range.Em contraste, o controle hospedeiro de Microsoft.Office.Tools.Excel.NamedRange tem um evento de Change que você pode manipular diretamente.

A relação entre um item de host e controles host é muito semelhante à relação entre formulários e controles dos formulários do windows.Assim como você deve um controle de caixa de texto em um formulário do windows, você coloca um controle de Microsoft.Office.Tools.Excel.NamedRange em um item de host de Microsoft.Office.Tools.Excel.Worksheet .A ilustração a seguir mostra a relação entre itens host e controles host.

Relação entre itens de host e controles de host

Você também pode usar controles de formulários do windows em suas soluções do Office adicionando a superfície diretamente para o documento do word e Excel.Para obter mais informações, consulte Controles do Windows Forms em Visão geral de documentos do Office.

Observação
Adicionar controles host ou controles de formulários do windows a um subdocument da palavra não é suportado.

Adicionando controles host aos documentos

Em projetos de um documento nível, você pode adicionar controles host para suas documentos do word ou planilhas do excel em tempo de design das seguintes maneiras:

Adicionar controles host no seu documento em tempo de design da mesma maneira que você adicionaria um objeto nativo.
Arraste os controles do host de Caixa de Ferramentas nos documentos e planilhas.Os controles de host do excel estão disponíveis na guia de Controles do excel em projetos do excel, os controles e host do word estão disponíveis na guia de Controles do word em projetos de palavras.
Arraste os controles do host da janela de Fontes de Dados nos documentos e planilhas.Isso permite que você adicione os controles que já estão associados a dados.Para obter mais informações, consulte A ligação de dados a controles em soluções do Office.

Em projetos da nível de aplicativo, você também pode adicionar alguns controles host para documentos em tempo de execução.Para obter mais informações, consulte Adicionar controles a documentos do Office em tempo de execução.

Para obter mais informações sobre como adicionar controles host para documentos, consulte os seguintes tópicos:

Nomeando controles host

Quando você arrasta um controle do host de Caixa de Ferramentas no seu documento, o controle é chamado automaticamente usando o tipo de controle com um número incremental no final.Por exemplo, marcadores são nomeados bookmark1, bookmark2, e assim por diante.Se você usar a funcionalidade nativo do word ou do excel para adicionar o controle, você pode dar um nome específico no momento que você o cria.Você também pode renomear seus controles alterando o valor da propriedade de Nome na janela de Propriedades .

Observação
Você não pode usar palavra reservada para nomear controles host.Por exemplo, se você adicionar um controle de NamedRange a uma planilha e altera o nome a Sistema, os erros ocorrem quando você criar o projeto.

Excluindo controles host

Em projetos de um documento nível, você pode excluir controles de hosts em tempo de design selecionando o controle na planilha do excel ou no documento do word e pressionando a tecla de exclusão.Em o entanto, você deve usar a caixa de diálogo de Definir Nome Excel para excluir controles de NamedRange .

Se você adicionar um controle do host a um documento em tempo de design, você não deve remova-o de programação em tempo de execução porque a próxima vez que você tenta usar o controle no código, uma exceção é lançada.O método de Delete de um controle do host apenas remove os controles host que são adicionados ao documento em tempo de execução.Se você chamar o método de Delete de um controle host que é criado em tempo de design, uma exceção é lançada.

Por exemplo, o método de Delete de NamedRange só exclui com êxito NamedRange foi somado programaticamente à planilha, que é conhecido como criação de controles host dinamicamente.Os controles criados dinamicamente host também podem ser removidos passando o nome do controle para o método de Remove da propriedade de Worksheet.Controls ou de Document.Controls .Para obter mais informações, consulte Adicionar controles a documentos do Office em tempo de execução.

Se os usuários finais exclui um controle do host do documento em tempo de execução, a solução pode falhar em maneiras inesperadas.Você pode usar os recursos de segurança do documento nas palavras e Excel para proteger os controles de host de ser excluído.Para obter mais informações, consulte Passo a passo e amostras de desenvolvimento do office.

Observação
Não remover programaticamente os controles no manipulador de eventos de Shutdown de documento ou a planilha.Os elementos de interface do usuário não estão mais disponíveis quando o evento de Shutdown ocorre.Se você deseja remover os controles antes que o aplicativo seja fechada, adicione o código para outro manipulador de eventos como BeforeClose ou BeforeSave.

Programação com eventos de controle do host

Uma maneira que hospeda controles estende objetos do Office é adicionando eventos.Por exemplo, o objeto de Microsoft.Office.Interop.Excel.Range Excel e o objeto de Microsoft.Office.Interop.Word.Bookmark na palavra não tem eventos, mas Visual Studio Tools for Office Runtime estende esses objetos adicionando eventos programáveis.Você pode acessar código e contra esses eventos da mesma maneira que você acessa eventos os controles dos formulários do windows: através da lista suspensa de evento no Visual Basic e da página de propriedades de evento em C#.Para obter mais informações, consulte Passo a passo: Programação contra eventos de um controle NamedRange.

Observação
Você não deve definir a propriedade de EnableEvents do objeto de Application Excel a false.Defina essa propriedade como false impede que o excel para aumentar todos os eventos, incluindo os eventos de controles host.