Persisting controles dinâmicos em documentos do Office

Os controles que são adicionados em tempo de execução não são persistidos quando o documento ou pasta de trabalho são salvos e fechados.O comportamento exato é diferente para controles host e controles dos formulários do windows.Em ambos os casos, você pode adicionar código à sua solução para recriar controles quando o usuário reabra o documento.

Os controles que você adicionar aos documentos em tempo de execução são chamados controles dinâmicos.Para obter mais informações sobre controles dinâmicos, consulte Adicionar controles a documentos do Office em tempo de execução.

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 2013 e Excel 2010; Word 2013 e Word 2010. Para obter mais informações, consulte Recursos disponíveis pelo aplicativo do Office e o tipo de projeto.

Gravando controles host no documento

Quando um documento é salvo e fechado em seguida, todos os controles dinâmicos host são removidos do documento.Somente objetos subjacentes do Office de ambos permanecem code-behind.Por exemplo, um controle do host de Microsoft.Office.Tools.Excel.ListObject transformações Microsoft.Office.Interop.Excel.ListObject.Os objetos do Office de ambos não estão conectados a eventos de controle do host, e não possuem funcionalidades de associação de dados do controle do host.

A tabela a seguir lista o objeto nativo do Office que é deixado code-behind em um documento para cada tipo de controle do host.

Recreando controles dinâmicos host quando são os documentos abertos

Você pode recriar controles dinâmicos host no lugar dos controles existentes nativos cada vez que um usuário abre o documento.Criando controles host assim quando um documento está aberto simula a experiência que os usuários podem aguardar.

Para recriar um host controle para palavras, ou um controle do host de Microsoft.Office.Tools.Excel.NamedRange ou de Microsoft.Office.Tools.Excel.ListObject para o excel, usa um método de Add<classe de controle> de um objeto de Microsoft.Office.Tools.Excel.ControlCollection ou de Microsoft.Office.Tools.Word.ControlCollection .Use um método que tem um parâmetro para o objeto nativo do Office.

Por exemplo, se você quiser criar um controle do host de Microsoft.Office.Tools.Excel.ListObject de um existente Microsoft.Office.Interop.Excel.ListObject nativo quando o documento está aberto, use o método de AddListObject(ListObject) e passar em Microsoft.Office.Interop.Excel.ListObjectexistente.O exemplo de código a seguir demonstra isso em um projeto da nível do excel.O código recria Microsoft.Office.Tools.Excel.ListObject dinâmico que é baseado em Microsoft.Office.Interop.Excel.ListObject chamado MyListObject existente na classe de Sheet1 .

Private vstoListObject As Microsoft.Office.Tools.Excel.ListObject
Private Const DISP_E_BADINDEX As Integer = CInt(&H8002000B)

Private Sub Sheet1_Startup(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup
    Dim nativeListObject As Excel.ListObject = Nothing

    Try
        nativeListObject = Me.ListObjects("MyListObject")
    Catch ex As System.Runtime.InteropServices.COMException
        ' "MyListObject" does not exist.
        If ex.ErrorCode <> DISP_E_BADINDEX Then
            Throw
        End If
    End Try

    If nativeListObject IsNot Nothing Then
        vstoListObject = Me.Controls.AddListObject(nativeListObject)
    End If
End Sub

private Microsoft.Office.Tools.Excel.ListObject vstoListObject;
private const int DISP_E_BADINDEX = unchecked((int)0x8002000B);

private void Sheet1_Startup(object sender, System.EventArgs e)
{
    Excel.ListObject nativeListObject = null;

    try
    {
        nativeListObject = this.ListObjects.get_Item("MyListObject");
    }
    catch (System.Runtime.InteropServices.COMException ex)
    {
        // "MyListObject" does not exist.
        if (ex.ErrorCode != DISP_E_BADINDEX)
            throw;
    }

    if (nativeListObject != null)
    {
        vstoListObject = this.Controls.AddListObject(nativeListObject);
    }
}

recreando gráficos

Para recriar um controle do host de Microsoft.Office.Tools.Excel.Chart , você deve primeiro excluir Microsoft.Office.Interop.Excel.Chartnativo, recria e em seguida Microsoft.Office.Tools.Excel.Chart usando o método de AddChart(Range, String) ou de AddChart(Double, Double, Double, Double, String) .Não há nenhum método de Add<classe de controle> que permite que você crie novo Microsoft.Office.Tools.Excel.Chart baseado em Microsoft.Office.Interop.Excel.Chartexistente.

Se você não excluir primeiro Microsoft.Office.Interop.Excel.Chartnativo, então você criará um segundo, gráfico duplicado quando você recria Microsoft.Office.Tools.Excel.Chart.

Gravando controles de formulários do windows em documentos

Quando um documento é salvo e fechado em seguida, Visual Studio Tools for Office Runtime automaticamente remove todos os controles de formulários do windows criados dinamicamente do documento.Em o entanto, o comportamento é diferente para projetos da nível do aplicativo.

Em a personalizações de nível, os controles e seus conteúdos subjacentes ActiveX (que são usados para hospedar os controles no documento) são removidos na próxima vez no documento são abertos.Não há nenhuma indicando que os controles foram nunca lá.

Em o suplementos do aplicativo, os controles são removidos, mas os wrappers ActiveX permanecem no documento.Em a próxima vez que o usuário abre o documento, os wrappers ActiveX são visíveis.O excel, as imagens de exibição de wrappers ActiveX de controles como apareceram a última vez que o documento foram salvas.Em as palavras, os wrappers ActiveX são invisíveis a menos que o usuário clique em no, em esse caso exibem uma linha pontilhada que representa a borda dos controles.Há várias maneiras que você pode remover os wrappers ActiveX.Para obter mais informações, consulte Removendo os wrappers ActiveX em um suplemento.

Recreando controles de formulários do windows quando são os documentos abertos

Você pode recriar controles de formulários do windows excluídos quando o usuário reabra o documento.Para fazer isso, sua solução deve executar as seguintes tarefas:

1. Armazenar informações sobre o tamanho, o local, e o estado dos controles quando o documento é salvo ou fechada.Personalização de um documento em um nível, você pode salvar esses dados para o cache de dados no documento.Em um suplemento ao aplicativo, você pode salvar esses dados a uma parte personalizado XML no documento.

2. Recrie controles em um evento que é gerado quando o documento está aberto.Em projetos de um documento nível, você pode fazer isso em Sheetem_Startup ou nos manipuladores de eventos de ThisDocument_Startup .Em projetos de aplicativo, você pode fazer isso nos manipuladores de eventos para os eventos de WorkbookOpen ou de DocumentOpen .

Removendo os wrappers ActiveX em um suplemento

Quando você adiciona controles dinâmicos de formulários do windows para documentos usando um suplemento, você pode impedir que os wrappers ActiveX para os controles apareçam no documento a próxima vez que é aberto das seguintes maneiras.

Removendo os wrappers ActiveX quando o documento está aberto

Para remover todos os wrappers ActiveX, chame o método de GetVstoObject para gerar um item host para Microsoft.Office.Interop.Word.Document ou Microsoft.Office.Interop.Excel.Workbook que representa o documento aberto recentemente.Por exemplo, para remover todos os wrappers ActiveX de um documento do word, você pode chamar o método de GetVstoObject para gerar um item host para o objeto de Document que é passado para o manipulador de eventos para o evento de DocumentOpen .

Este procedimento é útil quando você souber que o documento será aberto somente em computadores que têm o suplemento instalado.Se o documento pode ser passado para outros usuários que não tenham o suplemento instalado, considere remover os controles antes de fechar o documento em vez de isso.

O exemplo de código a seguir demonstra como chamar o método de GetVstoObject quando o documento está aberto.

Private Sub Application_DocumentOpen_ClearActiveXWrappers( _
    ByVal Doc As Word.Document) Handles Application.DocumentOpen

    Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Doc)

End Sub

private void Application_DocumentOpen_ClearActiveXWrappers(Word.Document Doc)
{
    Microsoft.Office.Tools.Word.Document vstoDocument = Globals.Factory.GetVstoObject(Doc);

}

Embora o método de GetVstoObject é basicamente usado para gerar em tempo de execução um novo item host, esse método também limpa todos os wrappers ActiveX do documento a primeira vez que é chamado para um documento específico.Para obter mais informações sobre como usar o método de GetVstoObject , consulte Estendendo os documentos do Word e pastas de trabalho do Excel em suplementos de nível de aplicativo em tempo de execução.

Observe que se o suplemento cria controles dinâmicos quando o documento está aberto, o suplemento já chamar o método de GetVstoObject como parte do processo para criar controles.Você não precisa adicionar uma chamada para o método separado de GetVstoObject para remover os wrappers ActiveX em esse cenário.

Remova os controles dinâmicos antes de documento é fechado

O suplemento pode remover explicitamente cada controle dinâmico de documento antes do documento seja fechado.Este procedimento é útil para documentos que podem ser passados para outros usuários que não tenham o suplemento instalado.

O exemplo de código a seguir demonstra como remover todos os controles de formulários do windows de um documento do word quando o documento é fechado.

Private Sub Application_DocumentBeforeClose(ByVal Doc As Word.Document, _
    ByRef Cancel As Boolean) Handles Application.DocumentBeforeClose

    Dim isExtended As Boolean = Globals.Factory.HasVstoObject(Doc)

    If isExtended Then

        Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Doc)

        Dim controlsToRemove As System.Collections.ArrayList = _
            New System.Collections.ArrayList()

        ' Get all of the Windows Forms controls.
        For Each control As Object In vstoDocument.Controls
            If TypeOf control Is System.Windows.Forms.Control Then
                controlsToRemove.Add(control)
            End If
        Next

        ' Remove all of the Windows Forms controls from the document.
        For Each control As Object In controlsToRemove
            vstoDocument.Controls.Remove(control)
        Next
    End If
End Sub

void Application_DocumentBeforeClose(Word.Document Doc, ref bool Cancel)
{

    bool isExtended = Globals.Factory.HasVstoObject(Doc);

    if (isExtended)
    {
        Microsoft.Office.Tools.Word.Document vstoDocument = Globals.Factory.GetVstoObject(Doc);


        System.Collections.ArrayList controlsToRemove = 
            new System.Collections.ArrayList();

        // Get all of the Windows Forms controls.
        foreach (object control in vstoDocument.Controls)
        {
            if (control is System.Windows.Forms.Control)
            {
                controlsToRemove.Add(control);
            }
        }

        // Remove all of the Windows Forms controls from the document.
        foreach (object control in controlsToRemove)
        {
            vstoDocument.Controls.Remove(control);
        }
    }
}

Consulte também

Conceitos

Adicionar controles a documentos do Office em tempo de execução