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

Artigo
08/08/2011

Itens de host e controles de host são tipos que ajudam a fornecer o modelo de programação para soluções do Office são criadas usando as ferramentas de desenvolvimento do Office em Visual Studio. Itens de host e controles de host tornam-se de interagir com os modelos de objeto de Microsoft Office o Word e Excel de Microsoft Office, 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 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.

Itens de host

Itens de host são tipos que estão na parte superior das hierarquias de modelo de objeto em projetos do Office. O Visual Studio Tools for Office runtime define os seguintes itens de host para soluções do Word e Excel:

Cada um desses tipos estende um objeto que existe nativamente no modelo de objeto do Word ou Excel (chamado um objeto nativo do Office). Por exemplo, o Microsoft.Office.Tools.Word.Document item host estende o Microsoft.Office.Interop.Word.Document objeto, que é definido no assembly de interoperabilidade primária para o Word.

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

A capacidade de hospedar controles gerenciados, incluindo controles de host e controles Windows Forms.
Modelos mais sofisticados do evento. Alguns eventos de documento, pasta de trabalho e planilha em que os modelos de objeto nativos do Word e Excel são gerados somente no nível do aplicativo. Os itens de host fornecem esses eventos no nível do documento, para que seja mais fácil manipular os eventos de um documento específico.

Noções básicas sobre o Host de itens em projetos de nível de documento

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

O Microsoft.Office.Tools.Word.Document e Microsoft.Office.Tools.Excel.Worksheet itens do host associou designers que são a representação visual do documento ou planilha, como um designer de formulários do Windows. Você pode usar esse designer para modificar o conteúdo do documento ou planilha diretamente no Word ou Excel e arraste os controles na superfície de design. For more information, see Item de Host do documento and Item de Host de planilha.

O Microsoft.Office.Tools.Excel.Workbook o item de host não atua como um recipiente para controles que têm uma interface de usuário. Em vez disso, o designer para este item de host funciona como uma bandeja de componentes, o que permite que você arraste um componente, como um DataSet, em sua superfície de design. For more information, see Item de Host da pasta de trabalho.

Não não possível criar itens de host programaticamente em projetos de nível de documento. Em vez disso, use o ThisDocument, ThisWorkbook, ou Sheetn classes Visual Studio gera automaticamente em seu projeto em tempo de design. Essas classes geradas derivam de itens de host e eles fornecem um ponto de entrada para o seu código. For more information, see Limitações de programação de itens de Host e controles de Host.

Noções básicas sobre o Host de itens em projetos de nível de aplicativo

Quando você cria um suplemento em nível de aplicativo, você não tem acesso a itens de qualquer host por padrão. No entanto, você pode gerar Microsoft.Office.Tools.Word.Document, Microsoft.Office.Tools.Excel.Workbook, e Microsoft.Office.Tools.Excel.Worksheet itens do host no Word e Excel add-ins em tempo de execução.

Depois de gerar um item de host, você pode executar tarefas como adicionar controles a documentos e Criando marcas inteligentes que são reconhecidos em um documento específico. 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.

Observação
As marcas inteligentes estão obsoletas no Excel 2010 e Word 2010. For more information, see Visão geral sobre marcas inteligentes.

Controles de host

Controles de host estendem vários objetos de interface (UI) do usuário nos modelos de objeto do Word e Excel, como Microsoft.Office.Interop.Word.ContentControl e Microsoft.Office.Interop.Excel.Range objetos.

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

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

Os controles de host são adicionados aos documentos do Office se comportam como objetos nativos do Office; Entretanto, os controles de host têm funcionalidades adicionais, incluindo eventos e recursos de ligação de dados. Por exemplo, quando você deseja capturar os eventos de um nativo Microsoft.Office.Interop.Excel.Range de objeto no Excel, você primeiro deve manipular o evento change da planilha. Em seguida, você deve determinar se a alteração ocorreu dentro do Microsoft.Office.Interop.Excel.Range. Em contraste, o Microsoft.Office.Tools.Excel.NamedRange o controle de host tem um Change o evento que você pode manipular diretamente.

A relação entre um item de host e controles de host é muito semelhante ao relacionamento entre controles de formulário do Windows e Windows Forms. Assim como você poderia colocar um controle de caixa de texto em um formulário do Windows, se você colocar um Microsoft.Office.Tools.Excel.NamedRange controle em um Microsoft.Office.Tools.Excel.Worksheet item de host. A ilustração a seguir mostra a relação entre itens de host e os controles de host.

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

Você também pode usar controles Windows Forms em suas soluções do Office, adicionando-os diretamente para a superfície de documento do Word e Excel. For more information, see Controles do Windows Forms em Visão geral de documentos do Office.

Observação
Não há suporte para a adição de controles de host ou controles Windows Forms para um subdocumento do Word.

Adicionar controles de Host para seus documentos

Em projetos de nível de documento, você pode adicionar controles de host para seus documentos do Word ou planilhas do Excel em tempo de design das seguintes maneiras:

Adicionar controles de host para o seu documento em tempo de design, da mesma maneira, você adicionaria um objeto nativo.
Arraste os controles de host a partir de Toolbox em seus documentos e planilhas. Controles de host do Excel estão disponíveis na Excel controles guia projetos do Excel e a palavra host controles estão disponíveis no Controles do Word guia em projetos do Word.
Arraste os controles de host a partir de Fontes de dados janela para seus documentos e planilhas. Isso permite que você adicione controles que já estejam vinculados a dados. For more information, see A ligação de dados a controles em soluções do Office.

Em projetos de nível de aplicativo e de documento, você também pode adicionar alguns controles de host para documentos em tempo de execução. For more information, see Adicionar controles a documentos do Office em tempo de execução.

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

Controles de Host de nomeação.

Quando você arrasta um controle de host a partir de Toolbox ao seu documento, o controle é automaticamente nomeado usando o tipo de controle com um número incremental ao final. Por exemplo, os indicadores são nomeados bookmark1, bookmark2e assim por diante. Se você usar a funcionalidade nativa do Word ou Excel para adicionar o controle, você pode atribuir um nome específico no momento em que criá-la. Você também pode renomear, alterando o valor de seus controles de nome propriedade no Propriedades janela.

Observação
É possível usar palavras reservadas para controles de host do nome. Por exemplo, se você adicionar um NamedRange para uma planilha de controle e altere o nome para sistema, os erros ocorrem quando você constrói o projeto.

A exclusão de controles de Host

Em projetos de nível de documento, você pode excluir os controles de host, em tempo de design, selecionando o controle no documento do Word ou planilha do Excel e pressionando a tecla DELETE. No entanto, você deve usar o Definir nome caixa de diálogo no Excel para excluir NamedRange controles. For more information, see How to: Delete NamedRange Controls at Design Time.

Se você adicionar um controle de host a um documento em tempo de design, você não deve removê-lo programaticamente em tempo de execução porque na próxima vez que você tentar usar o controle de código, uma exceção é lançada. O Delete método de um controle de host somente remove controles de host, que são adicionados ao documento em tempo de execução. Se você chamar o Delete o método de um controle de host que foi criado em tempo de design, uma exceção é lançada.

Por exemplo, o Delete o método de um NamedRange exclui somente com êxito o NamedRange se ele foi adicionado programaticamente a planilha, o que é conhecido como criar controles de host dinamicamente. Host criado dinamicamente controles também podem ser removidos, passando o nome do controle para o Remove método o Worksheet.Controls ou Document.Controls propriedade. For more information, see Adicionar controles a documentos do Office em tempo de execução.

Se os usuários finais excluir um controle de host do documento em tempo de execução, a solução pode falhar de maneiras inesperadas. Você pode usar os recursos de proteção do documento no Word e Excel para proteger os controles de host que está sendo excluído. For more information, see Exemplos de desenvolvimento do Office e Walkthroughs.

Observação
Não remover programaticamente controles durante o Shutdown o manipulador de eventos do documento ou planilha. Os elementos de interface do usuário não estão mais disponíveis quando o Shutdown evento ocorre. Se você quiser remover os controles antes do aplicativo é fechado, adicione seu código ao manipulador de eventos de outro, como BeforeClose ou BeforeSave.

Programar eventos de controle de Host

Uma maneira de controles de host para estender a objetos do Office é adicionando eventos. Por exemplo, o Microsoft.Office.Interop.Excel.Range o objeto no Excel e Microsoft.Office.Interop.Word.Bookmark objeto no Word não possuem eventos, mas o Visual Studio Tools for Office runtime estende a esses objetos, adicionando eventos programável. Você pode acessar e codificar esses eventos da mesma maneira que você acessar eventos de controles de formulários do Windows: por meio da evento na lista suspensa no Visual Basic e a página de propriedades de evento em C#. For more information, see Demonstra Passo a passo: Programação de eventos de um controle NamedRange.

Observação
Você não deve definir o EnableEvents propriedade da Application objeto no Excel para false. A definição dessa propriedade false impede que o Excel a partir de geração de quaisquer eventos, incluindo os eventos de controles de host.