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

Aggiornamento: Luglio 2008

Si applica a
Le informazioni contenute in questo argomento riguardano solo i progetti Visual Studio Tools per Office e le versioni di Microsoft Office specificati. Tipo di progetto Progetti a livello di applicazione Versione Microsoft Office Excel 2007 Word 2007 Per ulteriori informazioni, vedere la classe Funzionalità disponibili in base ai tipi di progetto e applicazione.

A partire da Visual Studio 2008 Service Pack 1 (SP1) è possibile utilizzare un componente aggiuntivo a livello di applicazione per personalizzare documenti e cartelle di lavoro 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.

• Convertire un oggetto elenco esistente su un foglio di lavoro di Excel in un oggetto elenco Visual Studio Tools per Office 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 di Visual Studio Tools per Office in fase di esecuzione che estende il documento o la cartella di lavoro.

Generazione di oggetti estesi nei componenti aggiuntivi

Gli oggetti estesi sono oggetti di 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 nel componente aggiuntivo, utilizzare il metodo GetVstoObject di un'istanza di uno dei tipi seguenti negli assembly di interoperabilità primari di Excel e di Word:

• Oggetto Microsoft.Office.Interop.Excel.ListObject.

• Oggetto Microsoft.Office.Interop.Excel.Workbook.

• Oggetto Microsoft.Office.Interop.Excel.Worksheet.

• Oggetto Microsoft.Office.Interop.Word.Document.

Alla prima chiamata al metodo GetVstoObject di uno oggetto nativo di Office, viene restituito un oggetto di Visual Studio Tools per Office nuovo che estende l'oggetto. Ogni volta che si chiama il metodo sullo stesso oggetto nativo di Office, viene 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. Ad esempio, il metodo GetVstoObject di un oggetto Microsoft.Office.Interop.Word.Document restituisce un oggetto Microsoft.Office.Tools.Word.Document.

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

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 la classe Recupero di oggetti estesi da oggetti nativi di Office nelle personalizzazioni a livello di documento.

Nota:
Per utilizzare i metodi GetVstoObject e HasVstoObject in un file di codice diverso da ThisAddIn.cs o ThisAddIn.vb o in un progetto creato prima di installare SP1, è 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 di 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à primaria 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

• Utilizzare il metodo GetVstoObject di un oggetto Microsoft.Office.Interop.Word.Document. Nell'esempio di codice seguente viene generato un elemento host per il documento attivo.

  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 = _
          NativeDocument.GetVstoObject()
  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

• Utilizzare il metodo GetVstoObject di un oggetto Microsoft.Office.Interop.Excel.Workbook. Nell'esempio di codice seguente viene generato un elemento host per la cartella di lavoro attiva.

  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

• Utilizzare il metodo GetVstoObject di un oggetto Microsoft.Office.Interop.Excel.Worksheet. Nell'esempio di codice seguente viene generato un elemento host per il foglio di lavoro attivo.

  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 di un oggetto Microsoft.Office.Interop.Excel.ListObject, il metodo restituisce un oggetto Microsoft.Office.Tools.Excel.ListObject. L'oggetto Microsoft.Office.Tools.Excel.ListObject generato 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 la classe Controllo ListObject.

Per generare un controllo host per un oggetto ListObject

• Utilizzare il metodo GetVstoObject di un oggetto Microsoft.Office.Interop.Excel.ListObject. Nell'esempio di codice seguente viene generato un oggetto Microsoft.Office.Tools.Excel.ListObject per il primo oggetto Microsoft.Office.Interop.Excel.ListObject nel foglio di lavoro attivo.

  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 questi 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:

• Procedura: aggiungere smart tag ai documenti di Word

• Procedura: aggiungere smart tag a cartelle di lavoro di Excel

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 la classe Aggiunta di controlli ai documenti di Office in fase di esecuzione.

È possibile aggiungere controlli Windows Form o controlli host. Un controllo host è un controllo 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 la classe 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 la classe 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 la classe 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. Tramite il metodo CreateDocument1 utilizzato in questo esempio viene creato un nuovo documento e quindi viene definito un gestore eventi DocumentBeforeSave che impedisce il salvataggio di questo 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;
    }
}

Esempio in cui viene utilizzatoun elemento host

Nell'esempio di codice seguente questo processo viene semplificato gestendo l'evento BeforeSave di un elemento host Microsoft.Office.Tools.Word.Document. Tramite il metodo CreateDocument2 utilizzato in questo esempio 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.

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 = 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 di Visual Studio Tools per Office è già stato generato per un particolare oggetto nativo di Office, utilizzare il metodo HasVstoObject dell'oggetto di Office. Questo metodo restituisce true se un oggetto esteso è già stato generato. In caso contrario viene restituito false.

Ciò 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 del progetto per l'utilizzo dei metodi GetVstoObject e HasVstoObject

Quando si crea un progetto a livello di applicazione dopo avere installato Visual Studio 2008 SP1, 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.Excel.Extensions
  

  using Microsoft.Office.Tools.Excel.Extensions;
  

Per utilizzare questi metodi in un progetto a livello di applicazione creato prima di installare SP1, è necessario apportare le modifiche seguenti al progetto.

Per modificare un componente aggiuntivo di Excel esistente per creare oggetti estesi

1. Aggiungere un riferimento all'assembly Microsoft.Office.Tools.Excel.v9.0.dll.

2. 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 componente aggiuntivo di Word esistente per creare oggetti estesi

1. Aggiungere un riferimento all'assembly Microsoft.Office.Tools.Word.v9.0.dll.

2. 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 del 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

Attività

Esempio di controlli dinamici del componente aggiuntivo di Excel

Esempio di controlli dinamici del componente aggiuntivo di Word

Concetti

Programmazione di componenti aggiuntivi a livello di applicazione

Aggiunta di controlli ai documenti di Office in fase di esecuzione

Cenni preliminari sugli elementi e sui controlli host

Cenni preliminari sugli smart tag

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

Cronologia delle modifiche

Date	History	Motivo
Luglio 2008	Argomento aggiunto.	Modifica di funzionalità in SP1.