Obtendo estendido objetos de objetos do Office nativo em personalizações de nível de documento

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 documento 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 documento

Versão do Microsoft Office

O Excel 2007
Word 2007

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

Vários manipuladores de eventos para eventos de Office recebem um objeto de Office nativo 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 em sua personalização de nível de documento disparou o evento.Por exemplo, uma personalização de nível de documento para o Excel, convém executar código quando o usuário ativar um dos itens host Microsoft.Office.Tools.Excel.Worksheet na personalização, mas não quando o usuário ativar uma planilha no algumas Outro pasta de trabalho que ocorre a ser Abrir ao mesmo tempo.

Iniciando no Visual Studio 2008 Serviço Pack 1 (SP1), quando chegar em um objeto do Office nativo, você pode testar se esse objeto foi estendido para uma de item de host ou Microsoft.Office.Tools.Excel.ListObject host Controlarar uma personalização de nível de documento.

Itens de host e controles de host 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).Coletivamente, itens de host e o host controles também são chamados estendido objetos. Para obter mais informações sobre itens de host e controles de host, consulte Itens de host e Visão geral sobre controles de host.

Usando o GetVstoObject e HasVstoObject métodos

Para testar um objeto do Office nativo, use as HasVstoObject e os métodos de GetVstoObject de uma instância de um dos seguintes objetos Office nativos:

Se você apenas quiser determinar se o objeto do Office nativo tem um objeto estendido em sua personalização, use o método HasVstoObject.Esse método retorna true se o objeto do Office nativo tiver um objeto estendido e false caso contrário.

Se você quiser obter o objeto estendido, use o método GetVstoObject.Esse método retorna um Microsoft.Office.Tools.Excel.ListObject, Microsoft.Office.Tools.Excel.Workbook, Microsoft.Office.Tools.Excel.Worksheetou Microsoft.Office.Tools.Word.Document objeto se o objeto do Office nativo tiver uma.Caso contrário, GetVstoObject retornará null.Por exemplo, o método GetVstoObject de um objeto Microsoft.Office.Interop.Word.Document retorna um Microsoft.Office.Tools.Word.Document se o Microsoft.Office.Interop.Word.Document o objeto subjacente para o documento no seu projeto de documento do Word.

Você não é possível usar GetVstoObject em uma solução de nível de documento para criar um novo item de host em tempo de execução.Você pode usá-lo somente para acessar itens de host existentes que são gerados em seu projeto em tempo de design.For more information, see Limitações através de programação de itens de host e controles de host.

Em projetos de nível de aplicativo, você pode usar o método GetVstoObject para gerar novos itens de host em tempo de execução.For more information, see Estendendo os documentos do Word e Excel pastas de trabalho no nível de aplicativo Adicionar-ins em tempo de execução.

Observação:
Para usar o GetVstoObject e HasVstoObject métodos, você deve adicionar using (para C#) ou declarações de Imports (para o Visual Basic) para o Microsoft.Office.Tools.Excel.Extensions ou Microsoft.Office.Tools.Word.Extensions namespaces à parte superior da seu arquivo de código.Os métodos de GetVstoObject e HasVstoObject são implementados como de métodos de extensão no Tempo de execução Ferramentas do Visual Studio para o Office, e essas instruções permitem que você chamar esses métodos.

Para usar o GetVstoObject e HasVstoObject métodos, você deve adicionar using (para C#) ou declarações de Imports (para o Visual Basic) para o Microsoft.Office.Tools.Excel.Extensions ou Microsoft.Office.Tools.Word.Extensions namespaces à parte superior da seu arquivo de código.Os métodos de GetVstoObject e HasVstoObject são implementados como de métodos de extensão no Tempo de execução Ferramentas do Visual Studio para o Office, e essas instruções permitem que você chamar esses métodos.

Determinar se um item de host alto relevo a um evento

Os exemplos de código a seguir demonstram os métodos de HasVstoObject e GetVstoObject.Ambos os exemplos manipular o evento SheetActivate da classe ThisWorkbook em um projeto de pasta de trabalho do Excel.

O primeiro exemplo determina se um dos itens Microsoft.Office.Tools.Excel.Worksheet host foi ativado, comparando o parâmetro Sh com a propriedade InnerObject 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
    ElseIf Type.ReferenceEquals(Globals.Sheet2.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet2
    ElseIf Type.ReferenceEquals(Globals.Sheet3.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet3
    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;
    else if (Type.ReferenceEquals(Globals.Sheet2.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet2;
    else if (Type.ReferenceEquals(Globals.Sheet3.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet3;

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

O Avançar exemplo simplifica esse processo, usando os métodos de HasVstoObject do parâmetro GetVstoObject e Sh.

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.
    }
}