Condividi tramite


Estensione in fase di esecuzione di documenti di Word e di cartelle di lavoro di Excel in componenti aggiuntivi a livello di applicazione

È possibile utilizzare un componente aggiuntivo a livello di applicazione per personalizzare documenti di Word e cartelle di lavoro di Excel nei modi seguenti:

  • Aggiungere controlli gestiti a qualsiasi documento o foglio di lavoro aperto.

  • Creare smart tag riconosciuti in una cartella di lavoro o documento specifico.

    Nota

    Gli smart tag sono deprecati in Excel 2010 e Word 2010. Per ulteriori informazioni, vedere Cenni preliminari sugli smart tag.

  • Convertire un oggetto elenco esistente in un foglio di lavoro di Excel in un oggetto ListObject esteso che esponga eventi e possa essere associato ai dati tramite il modello di associazione dati di Windows Form.

  • Accedere agli eventi a livello di applicazione esposti da Word ed Excel per documenti, cartelle di lavoro e fogli di lavoro specifici.

Per utilizzare questa funzionalità, viene generato un oggetto in fase di esecuzione che estende il documento o la cartella di lavoro.

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

Generazione di oggetti estesi nei componenti aggiuntivi

Gli oggetti estesi sono istanze di tipi forniti dal runtime Visual Studio Tools per Office che aggiungono funzionalità a oggetti che esistono a livello nativo nei modelli a oggetti di Word o di Excel (chiamati oggetti nativi di Office). Per generare un oggetto esteso per un oggetto di Word o di Excel, utilizzare il metodo GetVstoObject. Quando si chiama il metodo GetVstoObject per la prima volta per un oggetto di Word o di Excel specificato, viene restituito un nuovo oggetto che estende l'oggetto specificato. Ogni volta che si chiamerà il metodo e si specificherà lo stesso oggetto di Word o di Excel, verrà restituito lo stesso oggetto esteso.

Il tipo dell'oggetto esteso ha lo stesso nome del tipo dell'oggetto nativo di Office, ma il tipo viene definito nello spazio dei nomi Microsoft.Office.Tools.Excel o Microsoft.Office.Tools.Word. Se ad esempio si chiama il metodo GetVstoObject per estendere un oggetto Microsoft.Office.Interop.Word.Document, il metodo restituisce un oggetto Microsoft.Office.Tools.Word.Document.

La modalità con cui si accede al metodo GetVstoObject dipende dalla versione di .NET Framework a cui è destinato il progetto:

I metodi GetVstoObject devono essere utilizzati principalmente nei progetti a livello di applicazione. Possono essere utilizzati anche nei progetti a livello di documento, ma si comportano in modo diverso e vengono utilizzati con minore frequenza. Per ulteriori informazioni, vedere Recupero di oggetti estesi da oggetti nativi di Office nelle personalizzazioni a livello di documento.

Per determinare se un oggetto esteso è già stato generato per un oggetto nativo di Office specifico, utilizzare il metodo HasVstoObject. Per ulteriori informazioni, vedere Determinazione dell'eventuale estensione di un oggetto di Office.

Nota

Per utilizzare i metodi GetVstoObject e HasVstoObject in un file di codice diverso da ThisAddIn.cs o ThisAddIn.vb in un progetto destinato a .NET Framework 3.5, è necessario modificare il progetto. Per ulteriori informazioni, vedere Configurazione del progetto per l'utilizzo dei metodi GetVstoObject e HasVstoObject.

Generazione di elementi host

Quando si utilizza il metodo GetVstoObject per estendere un oggetto a livello di documento (ovvero un oggetto Microsoft.Office.Interop.Excel.Workbook, Microsoft.Office.Interop.Excel.Worksheet o Microsoft.Office.Interop.Word.Document), l'oggetto restituito viene denominato elemento host. Un elemento host è un tipo che può contenere altri oggetti, inclusi altri oggetti estesi e controlli. È simile al tipo corrispondente nell'assembly di interoperabilità primario di Word o di Excel, ma dispone di funzionalità aggiuntive. Per ulteriori informazioni sugli elementi host, vedere Cenni preliminari sugli elementi e sui controlli host.

Dopo aver generato un elemento host, è possibile utilizzarlo per aggiungere smart tag o controlli gestiti al documento, alla cartella di lavoro o al foglio di lavoro. Per ulteriori informazioni, vedere Aggiunta di smart tag a documenti e cartelle di lavoro e Aggiunta di controlli gestiti a documenti e fogli di lavoro.

Per generare un elemento host per un documento di Word

  • Nell'esempio di codice seguente viene dimostrato come generare un elemento host per il documento attivo in un progetto destinato 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);
    }
    
  • Nell'esempio di codice riportato di seguito viene dimostrata la stessa attività in un progetto destinato a .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();
    }
    

Per generare un elemento host per una cartella di lavoro di Excel

  • Nell'esempio di codice seguente viene dimostrato come generare un elemento host per la cartella di lavoro attiva in un progetto destinato 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);
    }
    
  • Nell'esempio di codice riportato di seguito viene dimostrata la stessa attività in un progetto destinato a .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();
    }
    

Per generare un elemento host per un foglio di lavoro di Excel

  • Nell'esempio di codice seguente viene dimostrato come generare un elemento host per il foglio di lavoro attivo in un progetto destinato 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);
    }
    
  • Nell'esempio di codice riportato di seguito viene dimostrata la stessa attività in un progetto destinato a .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();
    }
    

Generazione di controlli host ListObject

Quando si utilizza il metodo GetVstoObject per estendere un oggetto Microsoft.Office.Interop.Excel.ListObject, il metodo restituisce un oggetto Microsoft.Office.Tools.Excel.ListObject. L'oggetto Microsoft.Office.Tools.Excel.ListObject dispone di tutte le funzionalità dell'oggetto Microsoft.Office.Interop.Excel.ListObject originale, ma dispone anche di funzionalità aggiuntiva, ad esempio la possibilità di essere associato ai dati tramite il modello di associazione dati di Windows Form. Per ulteriori informazioni, vedere Controllo ListObject.

Per generare un controllo host per un oggetto ListObject

  • Nell'esempio di codice seguente viene dimostrato come generare un Microsoft.Office.Tools.Excel.ListObject per il primo oggetto Microsoft.Office.Interop.Excel.ListObject nel foglio di lavoro attivo in un progetto destinato 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);
    }
    
  • Nell'esempio di codice riportato di seguito viene dimostrata la stessa attività in un progetto destinato a .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();
    }
    

Aggiunta di smart tag a documenti e cartelle di lavoro

Dopo aver generato un oggetto Microsoft.Office.Tools.Word.Document o Microsoft.Office.Tools.Excel.Workbook, è possibile creare uno smart tag riconosciuto nel contesto del documento o della cartella di lavoro che tali oggetti rappresentano. A tale scopo, utilizzare la proprietà VstoSmartTags dell'oggetto Microsoft.Office.Tools.Word.Document o Microsoft.Office.Tools.Excel.Workbook. Per ulteriori informazioni, vedere i seguenti argomenti:

Aggiunta di controlli gestiti a documenti e fogli di lavoro

Dopo aver generato un oggetto Microsoft.Office.Tools.Word.Document o Microsoft.Office.Tools.Excel.Worksheet, è possibile aggiungere i controlli al documento o al foglio di lavoro che questi oggetti estesi rappresentano. A tale scopo, utilizzare la proprietà Controls dell'oggetto Microsoft.Office.Tools.Word.Document o Microsoft.Office.Tools.Excel.Worksheet. Per ulteriori informazioni, vedere Aggiunta di controlli ai documenti di Office in fase di esecuzione.

È possibile aggiungere controlli Windows Form o controlli host. Un controllo host è un controllo fornito da Runtime di Visual Studio Tools per Office che esegue il wrapping di un controllo corrispondente nell'assembly di interoperabilità primario di Word o di Excel. Tale tipo di controllo espone tutto il comportamento dell'oggetto nativo di Office sottostante, ma genera anche eventi e può essere associato ai dati tramite il modello di associazione dati di Windows Form. Per ulteriori informazioni, vedere Cenni preliminari sugli elementi e sui controlli host.

Nota

Non è possibile aggiungere un controllo XmlMappedRange a un foglio di lavoro o un controllo XMLNode o XMLNodes a un documento tramite un componente aggiuntivo. Questi controlli host non possono essere aggiunti a livello di codice. Per ulteriori informazioni, vedere Limitazioni a livello di codice degli elementi e dei controlli host.

Persistenza e rimozione di controlli

Quando si aggiungono controlli gestiti a un documento o a un foglio di lavoro, i controlli non vengono salvati in modo permanente una volta salvato e quindi chiuso il documento. Tutti i controlli host vengono rimossi in modo che vengono lasciati solo gli oggetti nativi di Office sottostanti (ad esempio, un oggetto Microsoft.Office.Tools.Excel.ListObject diventa un oggetto Microsoft.Office.Interop.Excel.ListObject). Anche tutti i controlli Windows Form vengono rimossi, ma i wrapper ActiveX per i controlli restano nel documento. È necessario includere il codice nel componente aggiuntivo per pulire i controlli o per ricreare i controlli alla successiva apertura del documento. Per ulteriori informazioni, vedere Persistenza dei controlli dinamici nei documenti di Office.

Accesso agli eventi a livello di applicazione in documenti e cartelle di lavoro

Alcuni eventi relativi a documenti, cartelle di lavoro e fogli di lavoro nei modelli a oggetti di Word e di Excel nativi vengono generati solo a livello di applicazione. Ad esempio, l'evento DocumentBeforeSave viene generato quando un documento viene aperto in Word, ma tale evento viene definito nella classe Microsoft.Office.Interop.Word.Application, anziché nella classe Microsoft.Office.Interop.Word.Document.

Quando si utilizzano solo oggetti nativi di Office nel componente aggiuntivo, è necessario gestire questi eventi a livello di applicazione e scrivere quindi altro codice per stabilire se il documento che ha generato l'evento è quello personalizzato. Gli elementi host forniscono questi eventi a livello di documento, in modo da rendere più facile la gestione di eventi per un documento specifico. È possibile generare un elemento host e gestire quindi l'evento per quell'elemento host.

Esempio in cui vengono utilizzati oggetti nativi di Word

Nell'esempio di codice seguente viene illustrato come gestire un evento a livello di applicazione per documenti di Word. Il metodo CreateDocument consente di creare un nuovo documento, quindi di definire un gestore eventi DocumentBeforeSave che impedisce il salvataggio del documento. Poiché questo è un evento a livello di applicazione generato per l'oggetto Microsoft.Office.Interop.Word.Application, il gestore eventi deve confrontare il parametro Doc con l'oggetto document1 per determinare se document1 rappresenta il documento salvato.

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

Esempi in cui viene utilizzato un elemento host

Negli esempi di codice seguenti viene illustrato come semplificare il processo mediante la gestione dell'evento BeforeSave di un elemento host Microsoft.Office.Tools.Word.Document. Tramite il metodo CreateDocument2 utilizzato in questi esempi, viene generato un oggetto Microsoft.Office.Tools.Word.Document che estende l'oggetto document2 e quindi viene definito un gestore eventi BeforeSave che impedisce il salvataggio del documento. Poiché questo gestore eventi viene chiamato solo quando viene salvato document2, il gestore eventi può annullare l'azione di salvataggio senza la necessità di operazioni aggiuntive per verificare quale documento è stato salvato.

Nell'esempio di codice riportato di seguito viene dimostrata questa attività in un progetto destinato 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;
}

Nell'esempio di codice riportato di seguito viene dimostrata questa attività in un progetto destinato a .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;
}

Determinazione dell'eventuale estensione di un oggetto di Office

Per determinare se un oggetto esteso è già stato generato per un oggetto nativo di Office specifico, utilizzare il metodo HasVstoObject. Il metodo restituisce true se un oggetto esteso è già stato generato. In caso contrario, viene restituito false.

In progetti destinati a .NET Framework 3.5, il metodo HasVstoObject è disponibile per istanze di uno dei tipi seguenti negli assembly di interoperabilità primari di Excel e di Word:

In progetti destinati a .NET Framework 4, utilizzare il metodo Globals.Factory.HasVstoMethod. Passare l'oggetto nativo di Word o di Excel (ad esempio, un oggetto Microsoft.Office.Interop.Word.Document o Microsoft.Office.Interop.Excel.Worksheet) che si desidera verificare per un oggetto esteso.

Il metodo HasVstoObject risulta utile se si desidera eseguire codice solo quando un oggetto di Office specificato dispone di un oggetto esteso. Ad esempio, se si dispone di un componente aggiuntivo di Word che gestisce l'evento DocumentBeforeSave per rimuovere i controlli gestiti da un documento prima che venga salvato, è possibile utilizzare il metodo HasVstoObject per determinare se il documento è stato esteso. Se il documento non è stato esteso, non può contenere controlli gestiti, pertanto il gestore eventi può eseguire semplicemente una restituzione senza tentare di pulire i controlli nel documento.

Configurazione dei progetti di .NET Framework 3.5 per l'utilizzo dei metodi GetVstoObject e HasVstoObject

Quando si crea un progetto a livello di applicazione destinato a .NET Framework 3.5, il progetto viene configurato automaticamente per consentire l'utilizzo dei metodi GetVstoObject e HasVstoObject nei file di codice ThisAddIn.cs o ThisAddIn.vb. Per utilizzare questi metodi in un file di codice diverso da ThisAddIn.cs o ThisAddIn.vb, è necessario apportare le modifiche seguenti al file di codice.

Per modificare un file di codice in un progetto Excel per creare oggetti estesi

  • Aggiungere le seguenti istruzioni using (per Visual C#) o Imports (per Visual Basic) all'inizio del file di codice in cui si desidera utilizzare i metodi GetVstoObject e HasVstoObject.

    Imports Microsoft.Office.Tools.Excel.Extensions
    
    using Microsoft.Office.Tools.Excel.Extensions;
    

Per modificare un file di codice in un progetto Word per creare oggetti estesi

  • Aggiungere le seguenti istruzioni using (per Visual C#) o Imports (per Visual Basic) all'inizio del file di codice in cui si desidera utilizzare i metodi GetVstoObject e HasVstoObject.

    Imports Microsoft.Office.Tools.Word.Extensions
    
    using Microsoft.Office.Tools.Word.Extensions;
    

Queste modifiche sono richieste in quanto i metodi GetVstoObject e HasVstoObject vengono implementati come metodi di estensione. Anche se si utilizzano i metodi GetVstoObject e HasVstoObject come se fossero definiti nei tipi degli assembly di interoperabilità primari di Excel o Word, questi vengono in realtà definiti nei tipi degli spazi dei nomi Microsoft.Office.Tools.Excel.Extensions e Microsoft.Office.Tools.Word.Extensions di Runtime di Visual Studio Tools per Office. Per ulteriori informazioni sui metodi di estensione, vedere Metodi di estensione (Guida per programmatori C#) e Metodi di estensione (Visual Basic).

Vedere anche

Concetti

Aggiunta di controlli ai documenti di Office in fase di esecuzione

Cenni preliminari sugli elementi e sui controlli host

Recupero di oggetti estesi da oggetti nativi di Office nelle personalizzazioni a livello di documento

Altre risorse

Programmazione di componenti aggiuntivi a livello di applicazione

Cenni preliminari sugli smart tag

Procedure dettagliate ed esempi di sviluppo di applicazioni per Microsoft Office