Programmazione delle personalizzazioni a livello di documento

Articolo
02/19/2013

Quando si estende Microsoft Office Word o Microsoft Office Excel utilizzando una personalizzazione a livello di documento è possibile eseguire le attività seguenti:

Automazione dell'applicazione mediante il relativo modello a oggetti.
Aggiunta di controlli all'area di un documento.
Chiamata a codice Visual Basic, Applications Edition (VBA) contenuto nel documento dall'assembly di personalizzazione.
Chiamata a codice contenuto nell'assembly di personalizzazione da VBA.
Gestione di determinati aspetti di un documento anche se si trova in un server in cui non è stato installato Microsoft Office.
Personalizzazione dell'interfaccia utente di un'applicazione.

Si applica a: le informazioni fornite in questo argomento sono valide per i progetti a livello di documento 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.

Alcuni aspetti della scrittura del codice nei progetti a livello di documento presentano delle differenze rispetto ad altri tipi di progetti in Visual Studio.Molte di queste differenze dipendono dal modo in cui i modelli a oggetti di Office sono esposti al codice gestito.Per ulteriori informazioni, vedere Scrittura di codice nelle soluzioni Office.

Per informazioni generali sulle personalizzazioni a livello di documento e su altri tipi di soluzioni che è possibile creare tramite gli strumenti di sviluppo di Office in Visual Studio, vedere Cenni preliminari sullo sviluppo di soluzioni Office.

Utilizzo delle classi generate nei progetti a livello di documento

Quando si crea un progetto a livello di documento, in Visual Studio viene generata automaticamente nel progetto una classe utilizzabile come base iniziale di scrittura del codice.In Visual Studio vengono generate classi specifiche per Word ed Excel:

Per impostazione predefinita, nei progetti a livello di documento di Word la classe viene denominata ThisDocument.
Per i progetti a livello di documento di Excel vengono generate più classi: una per la cartella di lavoro e una per ogni foglio di lavoro.Per impostazione predefinita, queste classi vengono denominate come segue:
- ThisWorkbook
- Sheet1
- Sheet2
- Sheet3

La classe generata contiene gestori eventi che vengono chiamati quando il documento viene aperto o chiuso.Per eseguire un blocco di codice all'apertura del documento, aggiungere tale blocco nel gestore eventi Startup.Per eseguire un blocco di codice subito prima della chiusura del documento, aggiungere tale blocco al gestore eventi Shutdown.Per ulteriori informazioni, vedere Eventi nei progetti di Office.

Informazioni sulla progettazione delle classi generate

Nei progetti destinati a .NET Framework 4 o .NET Framework 4.5, l'elemento host in Runtime di Visual Studio Tools per Office è interfacce, pertanto le classi generate non possono derivare da esse la loro implementazione.Al contrario, le classi generate derivano la maggior parte dei loro membri dalle classi base seguenti:

ThisDocument: deriva da Microsoft.Office.Tools.Word.DocumentBase.
ThisWorkbook: deriva da Microsoft.Office.Tools.Excel.WorkbookBase.
Sheetn: deriva da Microsoft.Office.Tools.Excel.WorksheetBase.

Queste classi base reindirizzano tutte le chiamate ai loro membri a implementazioni interne delle interfacce di elementi host corrispondenti in Runtime di Visual Studio Tools per Office.Ad esempio, se si chiama il metodo di Protect della classe di ThisDocument, la classe di Microsoft.Office.Tools.Word.DocumentBase reindirizzerà questa chiamata all'implementazione interna dell'interfaccia di Microsoft.Office.Tools.Word.Document in Runtime di Visual Studio Tools per Office.

Accesso al modello a oggetti dell'applicazione host

Per accedere al modello a oggetti dell'applicazione host occorre utilizzare i membri della classe generata nel progetto.Ognuna di queste classi corrisponde a un oggetto nel modello a oggetti di Excel o Word. In particolare, le classi sono quasi identiche in termini di proprietà, metodi ed eventi.Ad esempio, la classe ThisDocument di un progetto a livello di documento di Word fornisce la maggior parte dei membri disponibili nell'oggetto Microsoft.Office.Interop.Word.Document del modello a oggetti di Word.

Nell'esempio di codice seguente viene illustrato come utilizzare il modello a oggetti di Word per salvare il documento appartenente a una personalizzazione a livello di documento di Word.Questo esempio deve essere eseguito dall'interno della classe ThisDocument.

Me.Save()

this.Save();

Per eseguire lo stesso esempio dall'esterno della classe ThisDocument, utilizzare l'oggetto Globals per accedere alla classe ThisDocument.Ad esempio, per includere un pulsante Salva nell'interfaccia utente del riquadro delle azioni è possibile aggiungere questo codice a un file di codice del riquadro delle azioni.

Globals.ThisDocument.Save()

Globals.ThisDocument.Save();

Poiché la classe ThisDocument ottiene la maggior parte dei suoi membri dall'elemento host Microsoft.Office.Tools.Word.Document, il metodo Save chiamato in questo codice è di fatto il metodo Save dell'elemento host Microsoft.Office.Tools.Word.Document.Questo metodo corrisponde al metodo Save dell'oggetto Microsoft.Office.Interop.Word.Document del modello a oggetti di Word.

Per ulteriori informazioni sull'utilizzo dei modelli a oggetti di Word ed Excel, vedere Cenni preliminari sul modello a oggetti di Word e Cenni preliminari sul modello a oggetti di Excel.

Per ulteriori informazioni sull'oggetto Globals, vedere Accesso globale a oggetti nei progetti di Office.

Aggiunta di controlli ai documenti

Per personalizzare l'interfaccia utente di un documento è possibile aggiungere controlli Windows Form o controlli host all'area del documento.Combinando opportunamente codice e diversi gruppi di controlli è possibile associare i controlli a dati, ottenere informazioni dall'utente e rispondere alle azioni dell'utente.

I controlli host sono classi che estendono alcuni degli oggetti del modello a oggetti di Word ed Excel.Ad esempio, il controllo host Microsoft.Office.Tools.Excel.ListObject fornisce tutte le funzionalità dell'oggetto Microsoft.Office.Interop.Excel.ListObject di Excel.Tuttavia, il controllo host Microsoft.Office.Tools.Excel.ListObject presenta inoltre eventi e funzionalità di associazione dati aggiuntivi.

Per ulteriori informazioni, vedere Cenni preliminari sugli elementi e sui controlli host e Cenni preliminari sui controlli Windows Form nei documenti di Office.

Combinazione di VBA con le personalizzazioni a livello di documento

È possibile utilizzare codice VBA in un documento appartenente a una personalizzazione a livello di documento.È possibile chiamare codice VBA nel documento dall'assembly di personalizzazione ed è anche possibile configurare il progetto in modo da consentire al codice VBA nel documento di chiamare il codice nell'assembly di personalizzazione.

Per ulteriori informazioni, vedere Combinazione di VBA con le personalizzazioni a livello di documento.

Gestione di documenti in un server

Diversi aspetti della personalizzazione a livello di documento possono essere gestiti anche nei server in cui non è stato installato Microsoft Office Word oppure Microsoft Office Excel.È ad esempio possibile accedere e apportare modifiche ai dati memorizzati nella cache dei dati di un documento.È inoltre possibile gestire l'assembly di personalizzazione associato al documento.Ad esempio, è possibile rimuovere a livello di codice l'assembly da un documento affinché quest'ultimo non esegua più il codice. È inoltre possibile collegare un assembly a un documento a livello di codice.

Per ulteriori informazioni, vedere Gestione dei documenti di un server utilizzando la classe ServerDocument.

Personalizzazione dell'interfaccia utente delle applicazioni di Microsoft Office

È possibile personalizzare l'interfaccia utente di Word ed Excel nei modi seguenti utilizzando una personalizzazione a livello di documento:

Aggiungere controlli host o controlli Windows Form alla superficie del documento.

Per ulteriori informazioni, vedere Automazione di Word utilizzando oggetti estesi, Automazione di Excel utilizzando oggetti estesi e Cenni preliminari sui controlli Windows Form nei documenti di Office.
Aggiungere un riquadro azioni al documento.

Per ulteriori informazioni, vedere Cenni preliminari sul riquadro delle azioni.
Aggiunta di schede personalizzate alla barra multifunzione.

Per ulteriori informazioni, vedere Cenni preliminari sulla barra multifunzione.
Aggiunta di gruppi personalizzati a una scheda incorporata nella barra multifunzione.

Per ulteriori informazioni, vedere Procedura: personalizzare una scheda incorporata.

Per ulteriori informazioni sulla personalizzazione dell'interfaccia utente delle applicazioni di Microsoft Office, vedere Personalizzazione dell'interfaccia utente di Office.

Recupero degli oggetti estesi dagli oggetti nativi di Office nelle personalizzazioni a livello di documento

Molti gestori degli eventi di Office ricevono un oggetto nativo di Office che rappresenta la cartella di lavoro, il foglio di lavoro o il documento che ha generato l'evento.In alcuni casi, è necessario eseguire il codice solo se l'evento è stato generato dalla cartella di lavoro o dal documento della personalizzazione a livello di documento.Ad esempio, in una personalizzazione a livello di documento per Excel, è necessario eseguire il codice quando l'utente attiva uno dei fogli di lavoro nella cartella di lavoro personalizzata, ma non quando l'utente attiva un foglio di lavoro in altre cartelle di lavoro che possono essere aperte contemporaneamente.

Quando è presente un oggetto nativo di Office, è possibile verificare se tale oggetto è stato esteso in un elemento host o in un controllo host di una personalizzazione a livello di documento.Gli elementi e i controlli host sono tipi forniti da Runtime di Visual Studio Tools per Office che consentono di aggiungere funzionalità a oggetti che esistono a livello nativo nei modelli a oggetti di Word o di Excel (chiamati oggetti nativi di Office).Collettivamente, gli elementi host e controlli host vengono definiti oggetti estesi. Per ulteriori informazioni sugli elementi host e i controlli host, vedere Cenni preliminari sugli elementi e sui controlli host.

Informazioni sui metodi GetVstoObject e HasVstoObject

Per eseguire il test di un oggetto nativo di Office, utilizzare i metodi HasVstoObject e GetVstoObject nel progetto:

Se si desidera determinare se l'oggetto nativo di Office dispone di un oggetto esteso nella personalizzazione, utilizzare il metodo HasVstoObject.Questo metodo restituisce true se l'oggetto nativo di Office dispone di un oggetto esteso, altrimenti false.
Se si desidera ottenere l'oggetto esteso per un oggetto nativo di Office, utilizzare il metodo GetVstoObject.Questo metodo restituisce un oggetto Microsoft.Office.Tools.Excel.ListObject, Microsoft.Office.Tools.Excel.Workbook, Microsoft.Office.Tools.Excel.Worksheet o Microsoft.Office.Tools.Word.Document se l'oggetto nativo di Office specificato ne dispone di uno.In caso contrario, GetVstoObject restituisce null.Ad esempio, il metodo GetVstoObject restituisce un oggetto Microsoft.Office.Tools.Word.Document se l'oggetto Microsoft.Office.Interop.Word.Document specificato è l'oggetto sottostante del documento nel progetto documento di Word.

Nei progetti a livello di documento non è possibile utilizzare il metodo GetVstoObject per creare un nuovo elemento host Microsoft.Office.Tools.Excel.Workbook, Microsoft.Office.Tools.Excel.Worksheet o Microsoft.Office.Tools.Word.Document in fase di esecuzione.Tale metodo può essere utilizzato solo per accedere agli elementi host esistenti generati nel progetto in fase di progettazione.Se si desidera creare nuovi elementi host in fase di esecuzione, è necessario sviluppare un progetto a livello di applicazione.Per ulteriori informazioni, vedere Limitazioni a livello di codice degli elementi e dei controlli host e Estensione in fase di esecuzione di documenti di Word e di cartelle di lavoro di Excel in componenti aggiuntivi a livello di applicazione.

Utilizzo dei metodi GetVstoObject e HasVstoObject

Per chiamare il metodo di GetVstoObject e di HasVstoObject, utilizzare il metodo di Globals.Factory.HasVstoObject o di Globals.Factory.GetVstoObject e 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 testare.