Estendendo os documentos do Word e Excel pastas de trabalho no nível de aplicativo Adicionar-ins em tempo de execução

Artigo
08/25/2010

Se aplica a
As informações contidas neste tópico se aplicam apenas às especificado Ferramentas do Visual Studio para o Office projetos e as versões do Microsoft Office. Tipo de Projeto Projetos de nível de aplicativo Versão do Microsoft Office O Excel 2007 Word 2007 For more information, see Recursos disponíveis pelo aplicativo e o tipo de projeto.

As informações contidas neste tópico se aplicam apenas às especificado Ferramentas do Visual Studio para o Office projetos e as versões do Microsoft Office.

Tipo de Projeto

Projetos de nível de aplicativo

Versão do Microsoft Office

O Excel 2007
Word 2007

For more information, see Recursos disponíveis pelo aplicativo e o tipo de projeto.

Iniciando no Visual Studio 2008 Serviço Pack 1 (SP1), você pode usar um aplicativo-nível Adicionar - para personalizar documentos e pastas de trabalho das seguintes maneiras:

Adicionar controles gerenciados para qualquer Abrir documento ou planilha.
Criar inteligentes marcas que são reconhecidas em um documento específico ou a pasta de trabalho.
Convertera um objeto de lista existente em uma planilha do Excel em um objeto de lista Ferramentas do Visual Studio para o Office que expõe eventos e pode ser Ligado a dados usando o modelo de ligação de dados do Windows Forms.
Acessar eventos no nível do aplicativo que são expostos pelo Word e Excel para documentos específicos, pastas de trabalho e planilhas.

Para usar esta funcionalidade, você gerar um objeto Ferramentas do Visual Studio para o Office em tempo de execução que estende o documento ou pasta de trabalho.

Gerar objetos estendidos no Adicionar-ins

Estendido objetos são Ferramentas do Visual Studio para o Office objetos que Adicionar funcionalidade para objetos existentes de forma nativa nos modelos de objeto de Word ou Excel (chamados nativo Office objetos).Para gerar um objeto estendido em sua Adicionar - in, use o método GetVstoObject de uma instância de um dos seguintes tipos nos assemblies de interoperabilidade primários Excel e Word:

Na Primeiro vez que você chamar o método GetVstoObject de um objeto nativo do Office, ele retorna um novo objeto de Ferramentas do Visual Studio para o Office que estende o objeto. Sempre que você chame o método no mesmo objeto do Office nativo, ele retorna o mesmo objeto estendido.

O tipo de objeto estendido tem o mesmo nome que o tipo do objeto Office nativo, mas o tipo é definido no namespace Microsoft.Office.Tools.Excel ou Microsoft.Office.Tools.Word.Por exemplo, o método GetVstoObject de um objeto Microsoft.Office.Interop.Word.Document retorna um Microsoft.Office.Tools.Word.Document.

Para determinar se um objeto Ferramentas do Visual Studio para o Office já foi gerado para um determinado objeto de Office nativo, use o método HasVstoObject do objeto do Office.Para obter mais informações, consulte determinar se um Office objeto com foi estendido.

Os métodos de GetVstoObject devem ser usados principalmente em projetos de nível de aplicativo.Você também pode usar esses métodos em projetos de nível de documento, mas eles se comportam de maneira diferente e têm menos usa.For more information, see Obtendo estendido objetos de objetos do Office nativo em personalizações de nível de documento.

Observação:
Para usar o GetVstoObject e métodos de HasVstoObject em um arquivo de código Outro que ThisAddIn.cs ou ThisAddIn.vb, ou em um projeto que você criou antes de instalar o SP1, você deve modificar seu projeto.Para obter mais informações, consulte Configurando seu projeto para usar o GetVstoObject e métodos de HasVstoObject .

Gerar itens do host

Quando você usa o método GetVstoObject de um objeto de nível de documento, ou seja, um Microsoft.Office.Interop.Excel.Workbook, Microsoft.Office.Interop.Excel.Worksheetou Microsoft.Office.Interop.Word.Document, o objeto retornado é chamado de item de host um .Um item de host é um tipo que pode conter outros objetos, incluindo outros objetos estendidos e controles.Ele lembra o tipo correspondente no assembly de interoperabilidade primária Word ou Excel, mas ele tem recursos adicionais.Para obter mais informações sobre os itens de host, consulte Itens de host e Visão geral sobre controles de host.

Depois de gerar um item de host, você pode usá-lo para adicionar marcas inteligentes ou controles gerenciados para o documento, pasta de trabalho ou planilha.Para obter mais informações, consulte adicionando marcas inteligentes para documentos e pastas de trabalho e adicionando gerenciado controles a documentos e planilhas.

Para gerar um item de host para um documento do Word

Use o método GetVstoObject de um Microsoft.Office.Interop.Word.Document.O exemplo de código a seguir gera um item de host para o documento ativo.

If Globals.ThisAddIn.Application.Documents.Count > 0 Then
    Dim NativeDocument As Microsoft.Office.Interop.Word.Document = _
        Globals.ThisAddIn.Application.ActiveDocument
    Dim VstoDocument As Microsoft.Office.Tools.Word.Document = _
        NativeDocument.GetVstoObject()
End If

if (Globals.ThisAddIn.Application.Documents.Count > 0)
{
    Microsoft.Office.Interop.Word.Document nativeDocument =
        Globals.ThisAddIn.Application.ActiveDocument;
    Microsoft.Office.Tools.Word.Document vstoDocument =
        nativeDocument.GetVstoObject();
}

Para gerar um item de host para uma pasta de trabalho do Excel

Use o método GetVstoObject de um Microsoft.Office.Interop.Excel.Workbook.O exemplo de código a seguir gera um item de host para a pasta de trabalho Ativo.

Dim NativeWorkbook As Microsoft.Office.Interop.Excel.Workbook = _
    Globals.ThisAddIn.Application.ActiveWorkbook

If NativeWorkbook IsNot Nothing Then
    Dim VstoWorkbook As Microsoft.Office.Tools.Excel.Workbook = _
        NativeWorkbook.GetVstoObject()
End If

Microsoft.Office.Interop.Excel.Workbook nativeWorkbook =
    Globals.ThisAddIn.Application.ActiveWorkbook;

if (nativeWorkbook != null)
{
    Microsoft.Office.Tools.Excel.Workbook vstoWorkbook =
        nativeWorkbook.GetVstoObject();
}

Para gerar um item de host para uma planilha do Excel

Use o método GetVstoObject de um Microsoft.Office.Interop.Excel.Worksheet.O exemplo de código a seguir gera um item de host para a planilha Ativo.

Dim NativeSheet As Microsoft.Office.Interop.Excel.Worksheet = _
    TryCast(Globals.ThisAddIn.Application.ActiveSheet,  _
    Microsoft.Office.Interop.Excel.Worksheet)

If NativeSheet IsNot Nothing Then
    Dim VstoSheet As Microsoft.Office.Tools.Excel.Worksheet = _
        NativeSheet.GetVstoObject()
End If

Microsoft.Office.Interop.Excel.Worksheet nativeSheet =
    Globals.ThisAddIn.Application.ActiveSheet as
    Microsoft.Office.Interop.Excel.Worksheet;

if (nativeSheet != null)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoSheet =
        nativeSheet.GetVstoObject();
}

Gerar ListObject host controles

Quando você usa o método GetVstoObject um Microsoft.Office.Interop.Excel.ListObject, o método retorna um Microsoft.Office.Tools.Excel.ListObject.O gerado Microsoft.Office.Tools.Excel.ListObject tem Tudo recursos do original Microsoft.Office.Interop.Excel.ListObject, mas ele também possui obter funcionalidades adicionais, como a capacidade de ser Ligados a dados usando o modelo de ligação de dados do Windows Forms.For more information, see Controlarar de ListObject.

Para gerar um Controlarar de host para um ListObject

Use o método GetVstoObject de um Microsoft.Office.Interop.Excel.ListObject.O exemplo de código a seguir gera um Microsoft.Office.Tools.Excel.ListObject para o primeiro Microsoft.Office.Interop.Excel.ListObject na planilha Ativo.

Dim sheet As Excel.Worksheet = Globals.ThisAddIn.Application.ActiveSheet

If sheet.ListObjects.Count > 0 Then
    Dim listObject As Excel.ListObject = sheet.ListObjects(1)
    Dim vstoListObject As Microsoft.Office.Tools.Excel.ListObject = _
        listObject.GetVstoObject()
End If

Microsoft.Office.Interop.Excel.Worksheet sheet =
    Globals.ThisAddIn.Application.ActiveSheet as
    Microsoft.Office.Interop.Excel.Worksheet;

if (sheet.ListObjects.Count > 0)
{
    Excel.ListObject listObject = sheet.ListObjects[1];
    Microsoft.Office.Tools.Excel.ListObject vstoListObject =
        listObject.GetVstoObject();
}

Adicionar marcas inteligentes a documentos e pastas de trabalho

Depois de gerar um Microsoft.Office.Tools.Word.Document ou Microsoft.Office.Tools.Excel.Workbook, você pode criar uma marca inteligente que é reconhecida no contexto do documento ou pasta de trabalho que representam esses objetos.Para fazer isso, use a propriedade VstoSmartTags do Microsoft.Office.Tools.Word.Document ou Microsoft.Office.Tools.Excel.Workbook.Para obter mais informações, consulte os seguintes tópicos:

Adicionando controles gerenciados para documentos e planilhas

Depois de gerar um Microsoft.Office.Tools.Word.Document ou Microsoft.Office.Tools.Excel.Worksheet, você pode adicionar controles ao documento ou planilha que esses estendido objetos representam.Para fazer isso, use a propriedade Controls do Microsoft.Office.Tools.Word.Document ou Microsoft.Office.Tools.Excel.Worksheet.For more information, see Adicionar controles a documentos do Office em tempo de execução.

Você pode adicionar controles de Windows Forms ou host controles.Um Controlarar de host é um Controlarar de Ferramentas do Visual Studio para o Office que envolve um Controlarar correspondente no assembly de interoperabilidade primário Word ou Excel.Um Controlarar de host expõe Tudos o comportamento do objeto Office nativo subjacente, mas ele também gera eventos e podem ser Ligados a dados usando o modelo de ligação de dados do Windows Forms.For more information, see Itens de host e Visão geral sobre controles de host.

Observação:
Não é possível adicionar um Controlarar de XmlMappedRange um Controlarar de planilha, ou um XMLNode ou XMLNodes para um documento, usando um Adicionar-in.Esses controles de host não podem ser adicionados programaticamente.For more information, see Limitações através de programação de itens de host e controles de host.

Persistência e remover controles

Quando você Adicionar controles gerenciados para um documento ou planilha, os controles não são mantidas quando o documento é salvo e, em seguida, Fechada.Tudo controles de host são removidos para que somente os subjacentes objetos Office nativos são Esquerda por trás (por exemplo, se um Microsoft.Office.Tools.Excel.ListObject torna um Microsoft.Office.Interop.Excel.ListObject).Tudo controles Windows Forms também serão removidos, mas wrappers do ActiveX para os controles são Esquerda behind no documento.Você deve incluir o código em seu Adicionar - para Apagar os controles ou recrie os controles a Avançar vez que o documento for aberto.For more information, see Persistência controles dinâmicos em documentos do Office.

Acessar eventos de nível de aplicativo de documentos e pastas de trabalho

Alguns eventos de documento, pasta de trabalho e planilha em nativos Word e Excel modelos de objeto são disparados somente no nível do aplicativo.Por exemplo, o evento DocumentBeforeSave é gerado quando um documento é aberto no Word, mas este evento é definido na classe Microsoft.Office.Interop.Word.Application , em vez da classe Microsoft.Office.Interop.Word.Document.

Quando você usa somente nativos objetos do Office no seu suplemento, você deve manipular esses eventos a nível de aplicativo e, em seguida, Gravar código adicional para determinar se o documento que disparou o evento é que você personalizou.Itens de host fornecem esses eventos no nível do documento, para que é mais fácil manipular os eventos de um documento específico.Você pode gerar um item de host e, em seguida, manipular o evento para aquele item de host.

Exemplo que utiliza objetos de Word nativo

O exemplo de código a seguir demonstra como manipular um evento de nível de aplicativo para documentos do Word.O método CreateDocument1 neste exemplo cria um novo documento e, em seguida, define um manipulador de eventos DocumentBeforeSave que impede que este documento seja salvo.Como esse é um evento de nível de aplicativo que é aumentado para o objeto de Microsoft.Office.Interop.Word.Application , o manipulador de eventos deve comparar o parâmetro Doc com o objeto document1 para determinar se document1 representa o documento salvo.

Private document1 As Word.Document = Nothing

Private Sub CreateDocument1()
    document1 = Me.Application.Documents.Add()
End Sub

Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
    ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) _
    Handles Application.DocumentBeforeSave
    If Type.ReferenceEquals(Doc, document1) Then
        Cancel = True
    End If
End Sub

private Word.Document document1 = null;

private void CreateDocument1()
{
    document1 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    this.Application.DocumentBeforeSave += 
        new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
        Application_DocumentBeforeSave);
}

private void Application_DocumentBeforeSave(Word.Document Doc, 
    ref bool SaveAsUI, ref bool Cancel)
{
    if (Type.ReferenceEquals(Doc, document1)) 
    {
        Cancel = true;
    }
}

Exemplo que usa um item de host

O exemplo de código a seguir simplifica esse processo ao manipular o evento BeforeSave de um item de host Microsoft.Office.Tools.Word.Document.O método CreateDocument2 neste exemplo gera um Microsoft.Office.Tools.Word.Document que estende o objeto document2 e, em seguida, define um manipulador de eventos BeforeSave que impede que o documento seja salvo.Porque esse manipulador de evento é chamado somente quando document2 é salvo, o manipulador de eventos pode cancelar o salvamento ação sem fazer qualquer trabalho extra para verificar qual documento foi salvo.

Private document2 As Word.Document = Nothing
Private WithEvents vstoDocument As Microsoft.Office.Tools.Word.Document = Nothing

Private Sub CreateDocument2()
    document2 = Me.Application.Documents.Add()
    vstoDocument = document2.GetVstoObject()
End Sub

Private Sub vstoDocument_BeforeSave(ByVal sender As Object, _
    ByVal e As SaveEventArgs) Handles vstoDocument.BeforeSave
    e.Cancel = True
End Sub

private Word.Document document2 = null;
private Microsoft.Office.Tools.Word.Document vstoDocument = null;

private void CreateDocument2()
{
    document2 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    vstoDocument = document2.GetVstoObject();
    vstoDocument.BeforeSave += new SaveEventHandler(vstoDocument_BeforeSave);
}

private void vstoDocument_BeforeSave(object sender, SaveEventArgs e)
{
    e.Cancel = true;
}

Determinar se um objeto do Office tem sido estendido

Para determinar se um objeto Ferramentas do Visual Studio para o Office já foi gerado para um determinado objeto de Office nativo, use o método HasVstoObject do objeto do Office.Esse método retorna true se já tiver sido gerado um objeto estendido; Caso contrário, ela retornará false.

Isso é útil quando você deseja executar o código somente quando um objeto do Office especificado possui um objeto estendido.Por exemplo, se você tiver uma palavra Adicionar - que alças o evento DocumentBeforeSave para remover gerenciado controles de um documento antes de ele é salvo, você pode usar o método HasVstoObject para determinar se o documento foi estendido.Se o documento não foi estendido, ele não pode conter controles gerenciados e, portanto, o manipulador de eventos pode simplesmente retorne sem tentar Apagar controles no documento.

Configurando o seu projeto para usar GetVstoObject os métodos de HasVstoObject

Quando você Criar um projeto de nível de aplicativo após a Instalar do Visual Studio 2008 SP1, o projeto é configurado automaticamente para você usar os métodos de GetVstoObject e HasVstoObject nos arquivos de código ThisAddIn.cs ou ThisAddIn.vb.

Usar esses métodos em um arquivo de código Outro que ThisAddIn.cs ou ThisAddIn.vb, você necessário fazer as seguintes alterações para o arquivo de código.

Para modificar um arquivo de código em um projeto Excel para criar objetos estendidos

Adicionar o seguinte using (para C#) ou instruções de Imports (para o Visual Basic) para o início do arquivo código no qual você deseja usar os métodos de GetVstoObject e HasVstoObject.
```
Imports Microsoft.Office.Tools.Excel.Extensions
```
```
using Microsoft.Office.Tools.Excel.Extensions;
```

Para modificar um Arquivo de Código em um projeto Word para criar objetos estendidos

Adicionar o seguinte using (para C#) ou instruções de Imports (para o Visual Basic) para o início do arquivo código no qual você deseja usar os métodos de GetVstoObject e HasVstoObject.
```
Imports Microsoft.Office.Tools.Excel.Extensions
```
```
using Microsoft.Office.Tools.Excel.Extensions;
```

Para usar esses métodos em um projeto de nível de aplicativo que você criou antes de instalar o SP1, você necessário fazer as seguintes alterações ao seu projeto.

Para modificar um existente Excel Adicionar - para criar objetos estendidos

Adicionar uma referência ao assembly Microsoft.Office.Tools.Excel.v9.0.dll.
Adicionar o seguinte using (para C#) ou instruções de Imports (para o Visual Basic) para o início do arquivo código no qual você deseja usar os métodos de GetVstoObject e HasVstoObject.
```
Imports Microsoft.Office.Tools.Excel.Extensions
```
```
using Microsoft.Office.Tools.Excel.Extensions;
```

Para modificar um existente Word Adicionar - para criar objetos estendidos

Adicionar uma referência ao assembly Microsoft.Office.Tools.Word.v9.0.dll.
Adicionar o seguinte using (para C#) ou instruções de Imports (para o Visual Basic) para o início do arquivo código no qual você deseja usar os métodos de GetVstoObject e HasVstoObject.
```
Imports Microsoft.Office.Tools.Word.Extensions
```
```
using Microsoft.Office.Tools.Word.Extensions;
```

Essas alterações são necessárias porque os métodos de GetVstoObject e HasVstoObject são implementados como de métodos de extensão .Embora você usar os métodos de GetVstoObject e HasVstoObject como se eles foram definidos em tipos nos assemblies de interoperabilidade primários Excel ou Word, na verdade, elas são definidas em tipos no Microsoft.Office.Tools.Excel.Extensions e Microsoft.Office.Tools.Word.Extensions namespaces do Tempo de execução Ferramentas do Visual Studio para o Office.Para obter mais informações sobre os métodos de extensão, consulte Métodos de extensão (Guia de programação C#) e Métodos de extensão (Visual Basic).