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

Artigo
08/08/2011

Você pode usar um suplemento em nível de aplicativo para personalizar documentos do Word e pastas de trabalho do Excel das seguintes maneiras:

Adicione controles gerenciados para qualquer documento aberto ou uma planilha.
Crie marcas inteligentes que são reconhecidas em um documento específico ou uma pasta de trabalho.

Observação

As marcas inteligentes estão obsoletas no Excel 2010 e Word 2010. For more information, see Visão geral sobre marcas inteligentes.
Converter um objeto de lista existente em uma planilha do Excel prorrogada ListObject que expõe eventos e podem ser vinculado a dados usando o modelo de ligação do Windows Forms a dados.
Eventos de nível de aplicativo de acesso que são expostos pelo Word e Excel para documentos específicos, pastas de trabalho e planilhas.

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

Para usar esta funcionalidade, você pode gerar um objeto em tempo de execução que estende o documento ou pasta de trabalho.

Aplicável a: As informações neste tópico se aplicam a 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.

Gerando objetos estendidos nos suplementos

Extended objetos são instâncias de tipos fornecidos pelo Visual Studio Tools for Office em tempo de execução adicionar funcionalidade a objetos que existem nativamente nos modelos de objeto do Word ou Excel (chamado objetos nativos do Office). Para gerar um objeto estendido para um objeto do Word ou Excel, use o GetVstoObject método. Na primeira vez que você chamar o o métodoGetVstoObject para uma palavra especificada ou o Excel o objeto, ele retorna um novo objeto que estende o objeto especificado. Objeto cada vez que você chame o método e especifica a mesma do Word ou Excel, ele retorna o mesmo objeto estendida.

O tipo de objeto estendido tem o mesmo nome como o tipo do objeto nativo do Office, mas o tipo está definido na Microsoft.Office.Tools.Excel ou Microsoft.Office.Tools.Word namespace. Por exemplo, se você chamar o GetVstoObject método para estender uma Microsoft.Office.Interop.Word.Document o objeto, o método retorna um Microsoft.Office.Tools.Word.Document objeto.

A maneira que você acessar o GetVstoObject método depende de qual versão do.NET Framework seus destinos do projeto:

Em projetos destinados a.NET Framework 3.5, use o GetVstoObject o método de uma instância de um dos seguintes tipos dos assemblies de interoperabilidade primários Excel e Word:
Em projetos destinados a .NET Framework 4, use o Globals.Factory.GetVstoObject método e passar o objeto nativo do Word ou Excel (como um Microsoft.Office.Interop.Word.Document ou Microsoft.Office.Interop.Excel.Worksheet) que você deseja estender.

O GetVstoObject métodos destinam-se a ser usado 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 forma diferente e têm menos de usos. For more information, see Obtendo Extended objetos a partir de objetos nativos do Office no nível do documento personalizações.

Para determinar se um objeto estendido já foi gerado para um determinado objeto nativo do Office, use o HasVstoObject método. Para obter mais informações, consulte Determinar se um Office objeto tiver sido estendido.

Observação
Para usar o GetVstoObject e métodos deHasVstoObject em um código de arquivo diferente de ThisAddIn.cs ou ThisAddIn. vb em um projeto voltado para o.NET Framework 3.5, você deve modificar seu projeto. Para obter mais informações, consulte Configurar seu projeto para usar os métodos de HasVstoObject de GetVstoObject e.

Gerar itens de Host

Quando você usa o GetVstoObject para estender um objeto de nível de documento (ou seja, um Microsoft.Office.Interop.Excel.Workbook, Microsoft.Office.Interop.Excel.Worksheet, ou Microsoft.Office.Interop.Word.Document), o objeto retornado é chamado um item de host. Um item de host é um tipo que pode conter outros objetos, incluindo outros objetos estendidos e controles. Se parece com o tipo correspondente no Word ou Excel primary interop assembly, mas ele possui recursos adicionais. Para obter mais informações sobre itens de host, consulte Itens de host e a 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 controles gerenciados para planilhas e documentos.

Para gerar um item de host para um documento do Word

O exemplo de código a seguir demonstra como gerar um item de host para o documento ativo em um projeto que se destina a .NET Framework 4.

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 = _
        Globals.Factory.GetVstoObject(NativeDocument)
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 =
        Globals.Factory.GetVstoObject(nativeDocument);
}

O exemplo de código a seguir demonstra a mesma tarefa em um projeto que tem como alvo o.NET Framework 3.5.

If Globals.ThisAddIn.Application.Documents.Count > 0 Then
    Dim NativeDocument As Microsoft.Office.Interop.Word.Document =
        Globals.ThisAddIn.Application.ActiveDocument
    If NativeDocument IsNot Nothing Then
        Dim vstoDocument As Microsoft.Office.Tools.Word.Document =
            NativeDocument.GetVstoObject()
    End If
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

O exemplo de código a seguir demonstra como gerar um item de host para a pasta de trabalho ativa em um projeto que se destina a .NET Framework 4.

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 =
        Globals.Factory.GetVstoObject(NativeWorkbook)
End If

Microsoft.Office.Interop.Excel.Workbook nativeWorkbook = 
    Globals.ThisAddIn.Application.ActiveWorkbook;
if (nativeWorkbook != null)
{
    Microsoft.Office.Tools.Excel.Workbook vstoWorkbook = 
        Globals.Factory.GetVstoObject(nativeWorkbook);
}

O exemplo de código a seguir demonstra a mesma tarefa em um projeto que tem como alvo o.NET Framework 3.5.

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

O exemplo de código a seguir demonstra como gerar um item de host para a planilha ativa em um projeto que se destina a .NET Framework 4.

Dim NativeWorksheet As Microsoft.Office.Interop.Excel.Worksheet =
    Globals.ThisAddIn.Application.ActiveSheet
If NativeWorksheet IsNot Nothing Then
    Dim vstoSheet As Microsoft.Office.Tools.Excel.Worksheet =
        Globals.Factory.GetVstoObject(NativeWorksheet)
End If

Microsoft.Office.Interop.Excel.Worksheet nativeWorksheet =
    Globals.ThisAddIn.Application.ActiveSheet;
if (nativeWorksheet != null)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoSheet = 
        Globals.Factory.GetVstoObject(nativeWorksheet);
}

O exemplo de código a seguir demonstra a mesma tarefa em um projeto que tem como alvo o.NET Framework 3.5.

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 controles de Host de ListObject

Quando você usa o GetVstoObject método para estender uma Microsoft.Office.Interop.Excel.ListObject, o método retorna um Microsoft.Office.Tools.Excel.ListObject. O Microsoft.Office.Tools.Excel.ListObject tem todos os recursos do original Microsoft.Office.Interop.Excel.ListObject, mas também possui funcionalidades adicionais, como, por exemplo, a capacidade de ser acoplado a dados usando os dados do Windows Forms vinculação modelo. For more information, see Controle de ListObject.

Para gerar um controle de host para um ListObject

O exemplo de código a seguir demonstra como gerar um Microsoft.Office.Tools.Excel.ListObject para o primeiro Microsoft.Office.Interop.Excel.ListObject na planilha ativa em um projeto que se destina a .NET Framework 4.

Dim sheet As Microsoft.Office.Interop.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 =
        Globals.Factory.GetVstoObject(listObject)
End If

Microsoft.Office.Interop.Excel.Worksheet sheet =
    Globals.ThisAddIn.Application.ActiveSheet;
if (sheet.ListObjects.Count > 0)
{
    Excel.ListObject listObject = 
        sheet.ListObjects[1];
    Microsoft.Office.Tools.Excel.ListObject vstoListObject =
        Globals.Factory.GetVstoObject(listObject);
}

O exemplo de código a seguir demonstra a mesma tarefa em um projeto que tem como alvo o.NET Framework 3.5.

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

Adicionando marcas inteligentes para 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 esses objetos representam. Para fazer isso, use o VstoSmartTags propriedade da Microsoft.Office.Tools.Word.Document ou Microsoft.Office.Tools.Excel.Workbook. For more information, see the following topics:

Adicionando controles gerenciados aos 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 o Controls propriedade da 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 Windows Forms ou controles de host. Um host é um controle fornecido pelo Visual Studio Tools for Office runtime que encapsula um controle correspondente no Word ou Excel primary interop assembly. Um controle de host expõe todas o comportamento do objeto nativo de Office subjacente, mas também gera eventos e podem ser vinculado a dados usando o modelo de ligação de dados do Windows Forms. For more information, see Itens de host e a visão geral sobre controles de Host.

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

Persistente e removendo os controles

Quando você adiciona controles gerenciados para um documento ou planilha, os controles não são mantidos quando o documento é salvo e, em seguida, fechado. Todos os controles de host são removidos para que somente nativos Office objetos subjacentes são deixados para trás (por exemplo, um Microsoft.Office.Tools.Excel.ListObject se torna um Microsoft.Office.Interop.Excel.ListObject). Todos os controles do Windows Forms também são removidos, mas os invólucros de ActiveX para os controles são deixados para trás no documento. Você deve incluir o código no seu suplemento para limpar os controles ou recriar os controles na próxima vez em que o documento for aberto. For more information, see Persistência de controles dinâmicos em documentos do Office.

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

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. Por exemplo, o DocumentBeforeSave evento é gerado quando um documento é aberto no Word, mas este evento é definido na Microsoft.Office.Interop.Word.Application classe, em vez de Microsoft.Office.Interop.Word.Document classe.

Quando você usa objetos apenas nativos do Office no seu suplemento, você deve lidar com esses eventos em nível de aplicativo e então escrever código adicional para determinar se o documento que disparou o evento é aquele que você personalizou. 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. Você pode gerar um item de host e, em seguida, manipule o evento para aquele item de host.

Exemplo que usa objetos nativos do Word

O exemplo de código a seguir demonstra como manipular um evento de nível de aplicativo para documentos do Word. O CreateDocument método cria um novo documento e, em seguida, define uma DocumentBeforeSave o manipulador de eventos que impede que este documento seja salvo. Porque este é um evento de nível de aplicativo que é gerado para o Microsoft.Office.Interop.Word.Application o objeto, o manipulador de eventos deve comparar o Doc parâmetro com o document1 objeto 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;
    }
}

Exemplos que usam um Item de Host

Os exemplos de código a seguir simplificam esse processo pelo tratamento de BeforeSave o evento de um Microsoft.Office.Tools.Word.Document item de host. O CreateDocument2 método nesses exemplos gerar uma Microsoft.Office.Tools.Word.Document que estende o document2 objeto e define um BeforeSave o manipulador de eventos que impede que o documento que está sendo salvo. Porque o manipulador de eventos é chamado somente quando document2 é salvo, o evento manipulador pode cancelar o salvamento ação sem fazer qualquer trabalho extra para verificar qual documento foi salvo.

O exemplo de código a seguir demonstra essa tarefa em um projeto que se destina a .NET Framework 4.

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 = Globals.Factory.GetVstoObject(document2)
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 = Globals.Factory.GetVstoObject(document2);
    vstoDocument.BeforeSave += new SaveEventHandler(vstoDocument_BeforeSave);
}

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

O exemplo de código a seguir demonstra essa tarefa em um projeto que tem como alvo o.NET Framework 3.5.

Private document2 As Microsoft.Office.Interop.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 foi estendido

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

Em projetos destinados a.NET Framework 3.5, o HasVstoObject método está disponível em instâncias dos seguintes tipos dos assemblies de interoperabilidade primários Excel e Word:

Em projetos destinados a .NET Framework 4, use o Globals.Factory.HasVstoMethod método. Passar o objeto do Word ou Excel nativo (como um Microsoft.Office.Interop.Word.Document ou Microsoft.Office.Interop.Excel.Worksheet) que você deseja testar objeto estendida.

O HasVstoObject método é útil quando você deseja executar o código somente quando um objeto especificado do Office tem um objeto estendida. Por exemplo, se você tiver um suplemento do Word que manipula o DocumentBeforeSave evento para remover a controles gerenciados de um documento antes que ele é salvo, você pode usar o HasVstoObject método 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 limpar os controles no documento.

Configurando.NET Framework 3.5 de projetos para usar os métodos de HasVstoObject e GetVstoObject

Quando você cria um projeto de nível de aplicativo voltado para o.NET Framework 3.5, o projeto é automaticamente configurado para usar o GetVstoObject e HasVstoObject métodos no ThisAddIn.cs ou ThisAddIn. vb código arquivos. Para usar esses métodos em um arquivo de código diferente, por exemplo, ThisAddIn.cs ou ThisAddIn. vb, faça as seguintes alterações no arquivo de código.

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

Adicione o seguinte using (para C#) ou Imports (para Visual Basic) instruções para a parte superior do arquivo de código na qual você deseja usar o GetVstoObject e HasVstoObject métodos.
```
Imports Microsoft.Office.Tools.Excel.Extensions
```
```
using Microsoft.Office.Tools.Excel.Extensions;
```

Para modificar um código de arquivo em uma palavra o projeto para criar objetos estendidos

Adicione o seguinte using (para C#) ou Imports (para Visual Basic) instruções para a parte superior do arquivo de código na qual você deseja usar o GetVstoObject e HasVstoObject métodos.
```
Imports Microsoft.Office.Tools.Word.Extensions
```
```
using Microsoft.Office.Tools.Word.Extensions;
```

Essas alterações são necessárias porque o GetVstoObject e HasVstoObject métodos são implementados como métodos de extensão. Apesar de você usar o GetVstoObject e HasVstoObject métodos como se eles foram definidos em tipos dos assemblies de interoperabilidade primários Excel ou Word, na verdade, são definidos em tipos na Microsoft.Office.Tools.Excel.Extensions e Microsoft.Office.Tools.Word.Extensions namespaces da Visual Studio Tools for Office runtime. Para obter mais informações sobre os métodos de extensão, consulte Métodos de extensão (guia de programação de C#) e Métodos de extensão (Visual Basic).