Obtendo Extended objetos a partir de objetos nativos do Office no nível do documento personalizações

Vários manipuladores de eventos para eventos de Office recebem um objeto nativo do Office que representa a pasta de trabalho, planilha ou documento que disparou o evento. Em alguns casos, convém executar algum código somente se a pasta de trabalho ou o documento na sua personalização no nível do documento disparou o evento. Por exemplo, uma personalização de nível de documento do Excel, convém executar algum código quando o usuário ativar uma das planilhas na pasta de trabalho personalizada, mas não quando o usuário ativar uma planilha em outra pasta que seja aberto ao mesmo tempo.

Quando você tem um objeto nativo do Office, você pode testar se o objeto foi estendido em um o item de host ou o controle de host uma personalização de nível de documento. Itens de host e controles de host são tipos fornecidos pelo Visual Studio Tools for Office runtime que adiciona funcionalidade a objetos que existem nativamente nos modelos de objeto do Word ou Excel (chamado objetos nativos do Office). Coletivamente, itens de host e controles de host também são chamados de estendidos objetos. Para obter mais informações 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 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.

Noções básicas sobre os métodos de HasVstoObject e GetVstoObject

Para testar um objeto nativo do Office, use o HasVstoObject e GetVstoObject métodos em seu projeto:

• Use o HasVstoObject método se você quiser determinar se o objeto nativo do Office tem um objeto estendido na personalização. Esse método retorna true se o objeto nativo do Office tem um objeto estendido, e false contrário.

• Use o GetVstoObject método se você deseja obter o objeto estendido para um objeto Office nativo. Esse método retorna um Microsoft.Office.Tools.Excel.ListObject, Microsoft.Office.Tools.Excel.Workbook, Microsoft.Office.Tools.Excel.Worksheet, ou Microsoft.Office.Tools.Word.Document objeto se o objeto especificado nativo do Office tem um. Otherwise, GetVstoObject returns null. Por exemplo, o GetVstoObject método retorna um Microsoft.Office.Tools.Word.Document se especificado Microsoft.Office.Interop.Word.Document é o objeto subjacente para o documento no seu projeto de documento do Word.

Em projetos de nível de documento, você não pode usar o GetVstoObject método para criar uma nova Microsoft.Office.Tools.Excel.Workbook, Microsoft.Office.Tools.Excel.Worksheet, ou Microsoft.Office.Tools.Word.Document o item de host em tempo de execução. Você pode usar esse método apenas para acessar itens host existentes que são gerados em seu projeto em tempo de design. Se você desejar criar novos itens de host em tempo de execução, você deve desenvolver um projeto de nível de aplicativo. For more information, see Limitações de programação de itens de Host e controles de Host and Estendendo os documentos do Word e pastas de trabalho do Excel em suplementos de nível de aplicativo em tempo de execução.

Usando os métodos de HasVstoObject e o GetVstoObject

A maneira que você chamar o HasVstoObject e GetVstoObject métodos depende de qual versão do.NET Framework seus destinos do projeto:

• Em projetos destinados a .NET Framework 4, use o Globals.Factory.GetVstoObject ou Globals.Factory.HasVstoObject 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 Test.

• Em projetos destinados a.NET Framework 3.5, acessar os métodos em uma instância de um dos seguintes tipos dos assemblies de interoperabilidade primários Excel e Word:

  • A Microsoft.Office.Interop.Excel.ListObject.

  • A Microsoft.Office.Interop.Excel.Workbook.

  • A Microsoft.Office.Interop.Excel.Worksheet.

  • A Microsoft.Office.Interop.Word.Document.

Observação

Para usar o GetVstoObject e projetos de métodos deHasVstoObject no nível do documento de destino do.NET Framework 3.5, você deve adicionar using (para C#) ou Imports (para Visual Basic) instruções para a Microsoft.Office.Tools.Excel.Extensions ou Microsoft.Office.Tools.Word.Extensions namespaces na parte superior do seu arquivo de código. O GetVstoObject e HasVstoObject métodos são implementados como métodos de extensão, e essas instruções permitem que você chamar esses métodos.

Exemplo: Determinar se um Item de Host disparou um evento

Os exemplos de código a seguir demonstram o HasVstoObject e GetVstoObject métodos. Ambos os exemplos de manipular a SheetActivate evento da ThisWorkbook classe em um projeto de pasta de trabalho do Excel. O primeiro exemplo determina se um do Microsoft.Office.Tools.Excel.Worksheet itens do host foi ativado, comparando o Sh parâmetro com o InnerObject propriedade de cada item de host padrão.

Sub ThisWorkbook_SheetActivate1(ByVal Sh As Object) Handles Me.SheetActivate
    Dim vstoWorksheet As Microsoft.Office.Tools.Excel.Worksheet = Nothing

    If Type.ReferenceEquals(Globals.Sheet1.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet1.Base
    ElseIf Type.ReferenceEquals(Globals.Sheet2.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet2.Base
    ElseIf Type.ReferenceEquals(Globals.Sheet3.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet3.Base
    End If

    If vstoWorksheet IsNot Nothing Then
        ' Do something with the VSTO worksheet here.
    End If
End Sub

void ThisWorkbook_SheetActivate1(object Sh)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoWorksheet = null;

    if (Type.ReferenceEquals(Globals.Sheet1.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet1.Base;
    else if (Type.ReferenceEquals(Globals.Sheet2.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet2.Base;
    else if (Type.ReferenceEquals(Globals.Sheet3.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet3.Base;

    if (vstoWorksheet != null)
    {
        // Do something with the VSTO worksheet here.
    }
}

O próximo exemplo simplifica esse processo usando o HasVstoObject e GetVstoObject métodos para a Sh parâmetro. Este exemplo demonstra como chamar esses métodos em um projeto voltado para o .NET Framework 4.

Private Sub ThisWorkbook_SheetActivate2(ByVal Sh As Object)
    Dim vstoWorksheet As Microsoft.Office.Tools.Excel.Worksheet = Nothing
    Dim interopWorksheet As Microsoft.Office.Interop.Excel.Worksheet =
        CType(Sh, Microsoft.Office.Interop.Excel.Worksheet)

    If interopWorksheet IsNot Nothing AndAlso
        Globals.Factory.HasVstoObject(interopWorksheet) Then
        vstoWorksheet = Globals.Factory.GetVstoObject(interopWorksheet)
    End If

    If vstoWorksheet IsNot Nothing Then
        ' Do something with the VSTO worksheet here. 
    End If

End Sub

void ThisWorkbook_SheetActivate2(object Sh)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoWorksheet = null;
    Microsoft.Office.Interop.Excel.Worksheet interopWorksheet =
        Sh as Microsoft.Office.Interop.Excel.Worksheet;

    if (interopWorksheet != null && Globals.Factory.HasVstoObject(interopWorksheet))
    {
        vstoWorksheet = Globals.Factory.GetVstoObject(interopWorksheet);
    }

    if (vstoWorksheet != null)
    {
        // Do something with the VSTO worksheet here.
    }
}

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

Sub ThisWorkbook_SheetActivate2(ByVal Sh As Object) Handles Me.SheetActivate
    Dim vstoWorksheet As Microsoft.Office.Tools.Excel.Worksheet = Nothing
    Dim interopWorksheet As Microsoft.Office.Interop.Excel.Worksheet = _
        CType(Sh, Microsoft.Office.Interop.Excel.Worksheet)

    If interopWorksheet IsNot Nothing AndAlso _
        interopWorksheet.HasVstoObject() Then
        vstoWorksheet = interopWorksheet.GetVstoObject()
    End If

    If vstoWorksheet IsNot Nothing Then
        ' Do something with the VSTO worksheet here.
    End If
End Sub

void ThisWorkbook_SheetActivate2(object Sh)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoWorksheet = null;
    Microsoft.Office.Interop.Excel.Worksheet interopWorksheet = 
        Sh as Microsoft.Office.Interop.Excel.Worksheet;

    if (interopWorksheet != null && interopWorksheet.HasVstoObject())
    {
        vstoWorksheet = interopWorksheet.GetVstoObject();
    }

    if (vstoWorksheet != null)
    {
        // Do something with the VSTO worksheet here.
    }
}

Consulte também

Referência

Métodos de extensão (guia de programação de C#)

Conceitos

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

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

Métodos de extensão (Visual Basic)

Outros recursos

Programação personalizações em nível de documento