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

Articolo
02/19/2013

È 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.
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: che le informazioni contenute in questo argomento si applicano ai progetti a livello di applicazione per le applicazioni seguenti: Excel 2010; 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 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 per un oggetto di Word o di Excel, utilizzare il metodo GetVstoObject.La prima volta chiama il metodo GetVstoObject per un oggetto di Word o di Excel specificato, restituisce un nuovo oggetto che estende l'oggetto specificato. Ogni volta che viene chiamato il metodo e specificare stesso oggetto Word o di Excel, restituisce 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.

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

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 controlli gestiti al documento, la cartella di lavoro, o al foglio di lavoro.Per ulteriori informazioni, vedere 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.

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

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.

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

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.

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

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 Microsoft.Office.Tools.Excel.ListObject per primo Microsoft.Office.Interop.Excel.ListObject nel foglio di lavoro attivo in un progetto.

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

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 XMLNodes o XMLNode a un documento, utilizzando 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 da consentire solo gli oggetti nativi di Office sottostanti.Ad esempio, Microsoft.Office.Tools.Excel.ListObject diventa 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 seguente viene illustrata questa attività.

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

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.

Utilizzare il metodo Globals.Factory.HasVstoMethod.Passare l'oggetto nativo di Word o di Excel, ad esempio Microsoft.Office.Interop.Word.Document o Microsoft.Office.Interop.Excel.Worksheet, che si desidera verificare 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.

Vedere anche

Concetti

Aggiunta di controlli ai documenti di Office in fase di esecuzione

Cenni preliminari sugli elementi e sui controlli host

Altre risorse

Programmazione di componenti aggiuntivi a livello di applicazione

Procedure dettagliate ed esempi di sviluppo di applicazioni per Microsoft Office

Condividi tramite