Persistenza dei controlli dinamici nei documenti di Office

I controlli che vengono aggiunti in fase di esecuzione non vengono mantenuti al salvataggio e alla chiusura di un documento o di una cartella di lavoro.Il comportamento effettivo varia a seconda che il controllo sia host o Windows Form.In entrambi casi è possibile aggiungere codice alla soluzione per ricreare i controlli quando l'utente riapre il documento.

I controlli aggiunti ai documenti in fase di esecuzione sono noti come controlli dinamici.Per ulteriori informazioni sui controlli dinamici, vedere Aggiunta di controlli ai documenti di Office in fase di esecuzione.

Si applica a: le informazioni fornite in questo argomento sono valide per i progetti a livello di documento e di applicazione per Excel 2013, Excel 2010, Word 2013 e Word 2010. Per ulteriori informazioni, vedere Funzionalità disponibili in base ai tipi di progetto e applicazioni di Office.

Persistenza dei controlli host nel documento

Quando si salva e si chiude un documento, tutti i controlli host dinamici vengono rimossi dal documento.Soltanto gli oggetti nativi di Office sottostanti restano nel documento.Ad esempio, un controllo host Microsoft.Office.Tools.Excel.ListObject diviene Microsoft.Office.Interop.Excel.ListObject.Gli oggetti nativi di Office non sono connessi agli eventi del controllo host e non dispongono della funzionalità di associazione dati del controllo host.

Nella tabella seguente viene indicato l'oggetto nativo di Office che resta in un documento per ogni tipo di controllo host.

Ricreazione di controlli host dinamici all'apertura dei documenti

È possibile ricreare controlli host dinamici al posto dei controlli nativi esistenti ogni volta che un utente apre un documento.Questa modalità di creazione dei controlli host all'apertura di un documento simula l'esperienza d'uso prevista dagli utenti.

Per ricreare un controllo host per Word o un controllo host Microsoft.Office.Tools.Excel.NamedRange o Microsoft.Office.Tools.Excel.ListObject per Excel, utilizzare un metodo Add<classe di controllo> di un oggetto Microsoft.Office.Tools.Excel.ControlCollection o Microsoft.Office.Tools.Word.ControlCollection.Utilizzare un metodo che dispone di un parametro per l'oggetto nativo di Office.

Ad esempio, se si desidera creare un controllo host Microsoft.Office.Tools.Excel.ListObject da un controllo nativo Microsoft.Office.Interop.Excel.ListObject esistente quando il documento viene aperto, utilizzare il metodo AddListObject(ListObject) e passare il controllo Microsoft.Office.Interop.Excel.ListObject esistente.Nell'esempio di codice seguente viene illustrata la stessa procedura in un progetto a livello di documento per Excel.Il codice ricrea un oggetto Microsoft.Office.Tools.Excel.ListObject dinamico basato su un oggetto Microsoft.Office.Interop.Excel.ListObject esistente denominato MyListObject nella classe 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);
    }
}

Ricreazione di grafici

Per ricreare un controllo host Microsoft.Office.Tools.Excel.Chart, è innanzitutto necessario eliminare l'oggetto nativo Microsoft.Office.Interop.Excel.Chart, e quindi ricreare Microsoft.Office.Tools.Excel.Chart utilizzando il metodo AddChart(Range, String) oppure il metodo AddChart(Double, Double, Double, Double, String).Non è disponibile alcun metodo di Add<classe di controllo> che consenta di creare un nuovo Microsoft.Office.Tools.Excel.Chart basato su un Microsoft.Office.Interop.Excel.Chart esistente.

Se non si elimina innanzitutto l'oggetto Microsoft.Office.Interop.Excel.Chart nativo, verrà creato un secondo grafico duplicato quando si ricrea Microsoft.Office.Tools.Excel.Chart.

Persistenza dei controlli Windows Form nei documenti

Quando si salva e si chiude un documento, Runtime di Visual Studio Tools per Office rimuove automaticamente dal documento tutti i controlli Windows Form creati dinamicamente.Tuttavia, il comportamento varia a seconda che il progetto sia a livello di documento o a livello di applicazione.

Nelle personalizzazioni a livello di documento, i controlli e i relativi wrapper ActiveX sottostanti (utilizzati per ospitare i controlli nel documento) vengono rimossi alla successiva apertura del documento.Una volta eseguita questa rimozione, dei controlli non resta alcuna traccia.

Anche nei componenti aggiuntivi a livello di applicazione i controlli vengono rimossi. Tuttavia, i wrapper ActiveX rimangono nel documento.Alla successiva apertura del documento da parte dell'utente, i wrapper ActiveX sono visibili.In Excel, i wrapper ActiveX visualizzano le immagini dei controlli nello stesso modo in cui erano visualizzati l'ultima volta che il documento è stato salvato.In Word, i wrapper ActiveX sono invisibili a meno che l'utente non faccia clic su di essi. In questo caso, viene visualizzata una linea punteggiata che delinea il bordo dei controlli.Esistono diversi modi per rimuovere i wrapper ActiveX.Per ulteriori informazioni, vedere Rimozione dei wrapper ActiveX contenuti in un componente aggiuntivo.

Ricreazione di controlli Windows Form all'apertura dei documenti

È possibile ricreare i controlli Windows Form eliminati quando l'utente riapre il documento.A questo scopo, la soluzione utilizzata deve eseguire le attività seguenti:

1. Memorizzare le informazioni sulla dimensione, il percorso e lo stato dei controlli quando il documento viene salvato o chiuso.In una personalizzazione a livello di documento, questi dati possono essere salvati nella cache di dati del documento.In un componente aggiuntivo a livello di applicazione, invece, questi dati possono essere salvati in una Web part XML personalizzata del documento.

2. Ricreare i controlli in un evento generato all'apertura del documento.Nei progetti a livello di documento, questa attività può essere eseguita nei gestori eventi Sheetn_Startup o ThisDocument_Startup.Nei progetti a livello di applicazione, invece, questa attività può essere eseguita nei gestori degli eventi WorkbookOpen o DocumentOpen.

Rimozione dei wrapper ActiveX contenuti in un componente aggiuntivo

Quando si utilizza un componente aggiuntivo per aggiungere controlli Windows Form dinamici ai documenti, è possibile impedire che i wrapper ActiveX dei controlli vengano visualizzati nel documento alla successiva apertura di quest'ultimo. In particolare, sono disponibili gli approcci elencati di seguito.

Rimozione dei wrapper ActiveX all'apertura del documento

Per rimuovere tutti i wrapper ActiveX, chiamare il metodo GetVstoObject per generare un elemento host per l'oggetto Microsoft.Office.Interop.Word.Document o Microsoft.Office.Interop.Excel.Workbook che rappresenta il documento appena aperto.Ad esempio, per rimuovere tutti i wrapper ActiveX da un documento di Word, è possibile chiamare il metodo GetVstoObject per generare un elemento host per l'oggetto Document passato al gestore dell'evento DocumentOpen.

Questa procedura è utile quando si sa che il documento verrà aperto solo su computer in cui è stato installato il componente aggiuntivo.Se esiste la possibilità che il documento venga passato ad altri computer in cui il componente aggiuntivo non è stato installato, rimuovere i controlli prima di chiudere il documento.

Nell'esempio di codice seguente viene illustrato come chiamare il metodo GetVstoObject all'apertura del documento.

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

}

Oltre a generare in fase di esecuzione un nuovo elemento host (funzionalità per cui in genere viene utilizzato), il metodo GetVstoObject cancella tutti i wrapper ActiveX dal documento la prima volta che viene chiamato per un documento specifico.Per ulteriori informazioni su come utilizzare il metodo GetVstoObject, vedere Estensione in fase di esecuzione di documenti di Word e di cartelle di lavoro di Excel in componenti aggiuntivi a livello di applicazione.

Si noti che, se il componente aggiuntivo crea controlli dinamici all'apertura del documento, chiamerà già il metodo GetVstoObject come parte del processo di creazione dei controlli.Pertanto, in questo caso, non occorre aggiungere alcuna chiamata a parte al metodo GetVstoObject per rimuovere i wrapper ActiveX.

Rimozione dei controlli dinamici prima della chiusura del documento

Il componente aggiuntivo può rimuovere in modo esplicito ogni controllo dinamico dal documento prima che quest'ultimo venga chiuso.Questa procedura è utile per i documenti che possono essere passati a computer in cui non è stato installato il componente aggiuntivo.

Nell'esempio di codice seguente viene illustrato come rimuovere tutti i controlli Windows Form da un documento di Word alla chiusura del documento.

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

Vedere anche

Concetti

Aggiunta di controlli ai documenti di Office in fase di esecuzione