Estendere i documenti di Word e le cartelle di lavoro di Excel nei componenti aggiuntivi VSTO in fase di esecuzione

  • Articolo

È possibile usare un componente aggiuntivo VSTO per personalizzare i documenti di Word e le cartelle di lavoro di Excel nei modi seguenti:

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

  • Convertire un oggetto elenco di un foglio di lavoro di Excel in un oggetto ListObject esteso che espone gli eventi e che può essere associato a dati mediante il modello di associazione dati di Windows Form.

  • Eventi di accesso a livello di applicazione esposti da Word ed Excel per documenti, cartelle di lavoro e fogli di lavoro specifici.

    Per usare questa funzionalità, è necessario creare un oggetto in fase di esecuzione che estenda il documento o la cartella di lavoro.

    Si applica a: le informazioni contenute in questo articolo si applicano ai progetti di componente aggiuntivo VSTO per le applicazioni seguenti: Excel e Word. Per altre informazioni, vedere Funzionalità disponibili per app Office lication e tipo di progetto.

Generare oggetti estesi nei componenti aggiuntivi VSTO

Glioggetti estesi rappresentano istanze di tipi forniti da Visual Studio Tools per Office Runtime e aggiungono funzionalità a oggetti che esistono in modo nativo nei modelli a oggetti di Word o Excel (chiamati oggetti nativi di Office). Per creare un oggetto esteso per un oggetto di Word o Excel, utilizzare il metodo GetVstoObject. La prima volta che si chiama il GetVstoObject metodo per un oggetto Word o Excel specificato, viene restituito un nuovo oggetto che estende l'oggetto specificato. Tutte le altre volte in cui si chiama un metodo e si specifica lo stesso oggetto di Word o Excel, viene restituito lo stesso oggetto esteso.

Il tipo dell'oggetto esteso dispone dello stesso nome di quello dell'oggetto nativo di Office; tuttavia, il tipo è definito nello spazio dei nomi Microsoft.Office.Tools.Excel o Microsoft.Office.Tools.Word . Ad esempio, se si chiama il metodo GetVstoObject per estendere un oggetto Document, il metodo restituisce un oggetto Document.

l metodi GetVstoObject devono essere usati principalmente nei progetti di componente aggiuntivo VSTO. È inoltre possibile usare questi metodi nei progetti a livello di documento, ma si comportano in modo diverso e sono caratterizzati da minori possibilità di utilizzo.

Per determinare se un oggetto esteso sia stato già creato per un particolare oggetto nativo di Office, usare il metodo HasVstoObject. Per altre informazioni, vedere Determinare se un oggetto di Office è stato esteso.

Generare elementi host

Quando si usa GetVstoObject per estendere un oggetto a livello di documento, ovvero , WorksheetWorkbooko 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 presente nell'assembly di interoperabilità primaria di Word o Excel, ma dispone di funzionalità aggiuntive. Per altre informazioni sugli elementi host, vedere Panoramica degli elementi host e dei controlli host.

Dopo aver generato un elemento host, è possibile usarlo per aggiungere controlli gestiti al documento, alla cartella di lavoro o al foglio di lavoro. Per altre informazioni, vedere Aggiungere controlli gestiti a documenti e fogli di lavoro.

Creare un elemento host per un documento di Word

  • Nel seguente esempio di codice viene spiegato come creare un elemento host per il documento attivo.

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

Creare un elemento host per una cartella di lavoro di Excel

  • Nel seguente esempio di codice viene spiegato come creare un elemento host per la cartella di lavoro attiva.

    Microsoft.Office.Interop.Excel.Workbook nativeWorkbook = 
    Globals.ThisAddIn.Application.ActiveWorkbook;
if (nativeWorkbook != null)
{
    Microsoft.Office.Tools.Excel.Workbook vstoWorkbook = 
        Globals.Factory.GetVstoObject(nativeWorkbook);
}

Creare un elemento host per un foglio di lavoro di Excel

  • Nel seguente esempio di codice viene spiegato come creare un elemento host per il foglio di lavoro attivo.

    Microsoft.Office.Interop.Excel.Worksheet nativeWorksheet =
    Globals.ThisAddIn.Application.ActiveSheet;
if (nativeWorksheet != null)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoSheet = 
        Globals.Factory.GetVstoObject(nativeWorksheet);
}

Generare controlli host ListObject

Quando si usa il metodo GetVstoObject per estendere un ListObject, il metodo restituisce un ListObject. include ListObject tutte le funzionalità dell'oggetto originale ListObject. Include anche funzionalità aggiuntive e può essere associata ai dati usando il modello di data binding Windows Form. Per altre informazioni, vedere Controllo ListObject.

Creare un controllo host per ListObject

  • Nel seguente esempio di codice viene spiegato come creare un ListObject per il primo ListObject nel foglio di lavoro attivo di un progetto.

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

Aggiungere controlli gestiti a documenti e fogli di lavoro

Dopo aver generato un Document o un Worksheet, è possibile aggiungere controlli al documento o al foglio di lavoro rappresentato da tali oggetti estesi. Per aggiungere controlli, utilizzare la Controls proprietà dell'oggetto Document o Worksheet. Per altre informazioni, vedere Aggiungere controlli ai documenti di Office in fase di esecuzione.

È possibile aggiungere controlli Windows Form o controlli host. Un controllo host è un controllo fornito dal runtime di Strumenti di Visual Studio per Office che esegue il wrapping di un controllo corrispondente nell'assembly di interoperabilità primario di Word o Excel. Un controllo host espone tutto il comportamento dell'oggetto office nativo sottostante. Genera anche eventi e può essere associato ai dati usando il modello di data binding Windows Form. Per altre informazioni, vedere Panoramica degli elementi host e dei controlli host.

Nota

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

Rendere persistenti e rimuovere i controlli

Quando si aggiungono controlli gestiti a un documento oppure a un foglio di lavoro, tali controlli non vengono conservati al momento di salvataggio e chiusura del documento. Tutti i controlli host vengono rimossi; in questo modo, vengono conservati soltanto gli oggetti Office nativi. Ad esempio, un ListObject diventa un ListObject. Inoltre, vengono rimossi tutti i controlli Windows Form. Tuttavia, i wrapper ActiveX dei controlli vengono mantenuti nel documento. È necessario includere un codice nel componente aggiuntivo VSTO per pulire i controlli oppure per creare di nuovo i controlli alla successiva apertura del documento. Per altre informazioni, vedere Rendere persistenti i controlli dinamici nei documenti di Office.

Accedere agli eventi a livello di applicazione su documenti e cartelle di lavoro

Alcuni eventi relativi a documenti, cartelle di lavoro e fogli di lavoro nei modelli a oggetti nativi di Word ed Excel vengono generati soltanto a livello di applicazione. Ad esempio, l'evento DocumentBeforeSave viene generato quando si apre un documento di Word; tuttavia, tale evento viene definito nella classe Application invece che nella classe Document .

Quando si usano soltanto oggetti nativi di Office nel componente aggiuntivo VSTO, è necessario gestire tali eventi a livello di applicazione e scrivere codice aggiuntivo per determinare se il documento che ha creato l'evento è uno di quelli personalizzati. Gli elementi host forniscono questi eventi a livello di documento, in modo che sia più semplice gestire gli eventi per un documento specifico. È possibile creare un elemento host e gestire l'evento per quell'elemento host.

Esempio che usa oggetti word nativi

Nel seguente esempio di codice viene descritto come gestire un evento a livello di applicazione per i documenti di Word. Il metodo CreateDocument consente di creare un nuovo documento e di definire il gestore eventi DocumentBeforeSave che impedisce di salvare il documento. L'evento è un evento a livello di applicazione generato per l'oggetto Application e il gestore eventi deve confrontare il Doc parametro con l'oggetto document1 per determinare se document1 rappresenta il documento salvato.

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 che usano un elemento host

Negli esempi di codice seguenti, il processo viene semplificato gestendo l'evento BeforeSave di un elemento host Document . Il CreateDocument2 metodo in questi esempi genera un oggetto Document che estende l'oggetto document2 e quindi definisce un BeforeSave gestore eventi che impedisce il salvataggio del documento. Il gestore eventi viene chiamato solo quando document2 viene salvato e può annullare l'azione di salvataggio senza eseguire ulteriori operazioni per verificare quale documento è stato salvato.

Nell'esempio di codice seguente viene illustrata questa attività.

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

Determinare se un oggetto office è stato esteso

Per determinare se un oggetto esteso sia stato già creato per un particolare oggetto nativo di Office, usare il metodo HasVstoObject. Questo metodo restituisce true se è già stato generato un oggetto esteso.

Usare il metodo Globals.Factory.HasVstoObject. Passare all'oggetto Word o Excel nativo (ad esempio, un Document o Worksheet) che si desidera sottoporre a test per un oggetto esteso.

Il metodo HasVstoObject è utile se si desidera eseguire il codice nel caso in cui un oggetto di Office disponga di un oggetto esteso. Ad esempio, se si dispone di un componente aggiuntivo VSTO di Word che gestisce l'evento DocumentBeforeSave per rimuovere i controlli gestiti da un documento prima del salvataggio, utilizzare il HasVstoObject metodo per determinare se il documento è stato esteso. Se il documento non è stato esteso, non può avere controlli gestiti e il gestore eventi può restituire senza tentare di pulire i controlli nel documento.

Contenuto correlato