Condividi tramite

Chiamata di codice nelle personalizzazioni a livello di documento da VBA

  • Articolo

È possibile configurare un progetto a livello di documento per Word o Excel in modo che il codice Visual Basic, Applications Edition (VBA) del documento possa chiamare il codice dell'assembly di personalizzazione. Questa operazione è utile negli scenari seguenti:

  • Si desidera estendere il codice VBA esistente di un documento utilizzando le funzionalità di una personalizzazione a livello di documento associata allo stesso documento.

  • Si desidera creare servizi sviluppati in una personalizzazione a livello di documento disponibile agli utenti finali in grado di accedervi scrivendo codice VBA nel documento.

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

Gli strumenti di sviluppo di Office in Visual Studio forniscono una funzionalità simile per i componenti aggiuntivi a livello di applicazione. Se si sviluppa un componente aggiuntivo, è possibile chiamare il codice nel componente aggiuntivo dalle altre soluzioni Microsoft Office. Per ulteriori informazioni, vedere Chiamata di codice nei componenti aggiuntivi a livello di applicazione da altre soluzioni Office.

Nota

Questa funzionalità non può essere utilizzata nei progetti Modello di Word, bensì esclusivamente nei progetti Documento di Word, Cartella di lavoro di Excel o Modello di Excel.

Requisiti

Per consentire al codice VBA di eseguire chiamate nell'assembly di personalizzazione, il progetto deve soddisfare i requisiti seguenti:

  • Il documento deve avere una delle estensioni di file seguenti:

    • Per Word: DOCM o DOC

    • Per Excel: xlsm, xltm, xls o xlt

  • Il documento deve già contenere un progetto VBA che include il codice VBA.

  • Il codice VBA del documento deve poter essere eseguito senza che venga richiesto all'utente di attivare le macro. È possibile considerare attendibile l'esecuzione del codice VBA aggiungendo il percorso del progetto di Office all'elenco di percorsi attendibili nelle impostazioni del Centro protezione per Word o Excel.

  • Il progetto di Office deve contenere almeno una classe pubblica che contenga uno o più membri pubblici da esporre a VBA.

    È possibile esporre metodi, proprietà ed eventi a VBA. La classe da esporre può essere una classe dell'elemento host (ad esempio ThisDocument per Word o ThisWorkbook e Sheet1 per Excel) o un'altra classe definita nel progetto. Per ulteriori informazioni sugli elementi host, vedere Cenni preliminari sugli elementi e sui controlli host.

Come consentire al codice VBA di essere chiamato nell'assembly di personalizzazione

Esistono due modalità diverse per esporre i membri di un assembly di personalizzazione al codice VBA del documento:

  • È possibile esporre a VBA i membri di una classe dell'elemento host di un progetto Visual Basic. A tale scopo, impostare la proprietà EnableVbaCallers dell'elemento host a True nella finestra Proprietà mentre l'elemento host, ovvero il documento, il foglio di lavoro o la cartella di lavoro, è aperto nella finestra di progettazione. Visual Studio esegue automaticamente le operazioni necessarie per consentire al codice VBA di chiamare i membri della classe.

  • È possibile esporre a VBA i membri di qualsiasi classe pubblica di un progetto Visual C# o i membri di una classe dell'elemento non host di un progetto Visual Basic. Questa opzione offre una maggiore libertà di scelta delle classi da esporre a VBA ma richiede più passaggi manuali.

    A questo scopo, è necessario eseguire la seguente procedura principale:

    1. Esporre la classe a COM.

    2. Eseguire l'override del metodo GetAutomationObject di una classe dell'elemento host del progetto per restituire un'istanza della classe che si sta esponendo a VBA.

    3. Impostare la proprietà ReferenceAssemblyFromVbaProject di una qualsiasi classe dell'elemento host del progetto su True. La libreria dei tipi dell'assembly di personalizzazione viene incorporata nell'assembly e viene aggiunto un riferimento alla libreria dei tipi al progetto VBA nel documento.

Per istruzioni dettagliate, vedere Procedura: esporre il codice a VBA in un progetto Visual Basic e Procedura: esporre il codice a VBA in un progetto Visual C#.

Le proprietà EnableVbaCallers e ReferenceAssemblyFromVbaProject sono disponibili nella finestra Proprietà solo in fase di progettazione; non possono essere utilizzate in fase di esecuzione. Per visualizzare le proprietà, aprire la finestra di progettazione per un elemento host in Visual Studio. Per ulteriori informazioni sulle attività specifiche che Visual Studio esegue quando si impostano queste proprietà, vedere Attività eseguite dalle proprietà degli elementi host.

Nota

Se la cartella di lavoro o il documento non contiene già il codice VBA o se il codice VBA del documento non è considerato attendibile per l'esecuzione, si riceve un messaggio di errore quando si imposta la proprietà EnableVbaCallers o la proprietà ReferenceAssemblyFromVbaProject su True. Ciò avviene perché Visual Studio non può modificare il progetto VBA nel documento in questa situazione.

Utilizzo di membri nel codice VBA per eseguire chiamate nell'assembly di personalizzazione

Dopo avere configurato il progetto per consentire al codice VBA di eseguire chiamate nell'assembly di personalizzazione, in Visual Studio vengono aggiunti i membri seguenti al progetto VBA del documento:

  • Per tutti i progetti, in Visual Studio viene aggiunto un metodo globale denominato GetManagedClass.

  • Per i progetti Visual Basic in cui vengono esposti membri di una classe di elementi host tramite la proprietà EnableVbaCallers, Visual Studio aggiunge una proprietà denominata CallVSTOAssembly al modulo ThisDocument, ThisWorkbook, Sheet1, Sheet2 o Sheet3 nel progetto VBA.

È possibile utilizzare la proprietà CallVSTOAssembly o il metodo GetManagedClass per accedere ai membri pubblici della classe esposta al codice VBA nel progetto.

Nota

Durante lo sviluppo e la distribuzione della soluzione esistono alcune copie diverse del documento in cui è possibile aggiungere il codice VBA. Per ulteriori informazioni, vedere Linee guida per l'aggiunta di codice VBA al documento.

Utilizzo della proprietà CallVSTOAssembly in un progetto Visual Basic

Utilizzare la proprietà CallVSTOAssembly per accedere ai membri pubblici aggiunti alla classe dell'elemento host. Ad esempio, la macro VBA seguente chiama un metodo denominato MyVSTOMethod definito nella classe Sheet1 in un progetto di cartella di lavoro di Excel.

Sub MyMacro()
    Sheet1.CallVSTOAssembly.MyVSTOMethod()
End Sub

Questa proprietà rappresenta un modo più pratico per effettuare chiamate nell'assembly di personalizzazione rispetto all'utilizzo diretto del metodo GetManagedClass. CallVSTOAssembly restituisce un oggetto che rappresenta la classe di elementi host esposta a VBA. I membri e parametri del metodo dell'oggetto restituito sono visualizzati in IntelliSense.

La proprietà CallVSTOAssembly ha una dichiarazione che è simile al codice seguente. Tale codice presuppone che sia stata esposta a VBA la classe dell'elemento host Sheet1 in un progetto di cartella di lavoro di Excel denominato ExcelWorkbook1.

Property Get CallVSTOAssembly() As ExcelWorkbook1.Sheet1
    Set CallVSTOAssembly = GetManagedClass(Me)
End Property

Utilizzo del metodo GetManagedClass

Per utilizzare il metodo globale GetManagedClass, passare l'oggetto VBA corrispondente alla classe dell'elemento host contenente l'override del metodo GetAutomationObject. Quindi, utilizzare l'oggetto restituito per accedere alla classe esposta a VBA.

Ad esempio, la macro VBA seguente chiama un metodo denominato MyVSTOMethod definito nella classe dell'elemento host Sheet1 in un progetto di cartella di lavoro di Excel denominato ExcelWorkbook1.

Sub CallVSTOMethod
    Dim VSTOSheet1 As ExcelWorkbook1.Sheet1
    Set VSTOSheet1 = GetManagedClass(Sheet1)
    VSTOSheet1.MyVSTOMethod
End Sub

Il metodo GetManagedClass è caratterizzato dalla dichiarazione seguente.

GetManagedClass(pdispInteropObject Object) As Object

Questo metodo restituisce un oggetto che rappresenta la classe esposta a VBA. I membri e i parametri del metodo dell'oggetto restituito sono visualizzati in IntelliSense.

Linee guida per l'aggiunta di codice VBA al documento

Esistono alcune copie diverse del documento in cui è possibile aggiungere il codice VBA che effettua chiamate nella personalizzazione a livello di documento.

Durante lo sviluppo e la verifica della soluzione è possibile scrivere il codice VBA nel documento che si apre mentre si esegue il debug o il progetto in Visual Studio (ovvero, il documento nella cartella dell'output della compilazione). Tuttavia, il codice VBA aggiunto a questo documento verrà sovrascritto alla successiva compilazione del progetto. Infatti, Visual Studio sostituisce il documento contenuto nella cartella dell'output della compilazione con una copia del documento contenuto nella cartella del progetto principale.

Se si desidera salvare il codice VBA aggiunto al documento durante l'esecuzione del debug o della soluzione, copiare il codice VBA nel documento nella cartella del progetto. Per ulteriori informazioni sul processo di compilazione, vedere Cenni preliminari sul processo di compilazione delle soluzioni Office.

Quando si è pronti per distribuire la soluzione, sono disponibili tre percorsi principali del documento nei quali è possibile aggiungere il codice VBA.

Nella cartella del progetto sul computer di sviluppo

Questo percorso è pratico se si ha un controllo completo sul codice VBA del documento e sul codice di personalizzazione. Perché il documento si trova nel computer di sviluppo, è possibile modificare facilmente il codice VBA qualora si modifichi il codice della personalizzazione. Il codice VBA aggiunto a questa copia del documento rimane nel documento quando si compila, si esegue il debug e si pubblica la soluzione.

Non è possibile aggiungere il codice VBA al documento mentre è aperto nella finestra di progettazione. Prima è necessario chiudere il documento nella finestra di progettazione e quindi aprire direttamente il documento in Word o Excel.

Nota di avvisoAttenzione

Se si aggiunge codice VBA in esecuzione quando il documento è aperto, può accadere in rari casi che tale codice danneggi il documento o ne impedisca l'apertura nella finestra di progettazione.

Nella cartella di pubblicazione o di installazione

In alcuni casi potrebbe essere utile aggiungere il codice VBA al documento nella cartella di pubblicazione o di installazione. Ad esempio, è possibile scegliere questa opzione se il codice VBA è scritto e testato da uno sviluppatore diverso in un computer in cui non è installato Visual Studio.

Se gli utenti installano la soluzione direttamente dalla cartella di pubblicazione, è necessario aggiungere il codice VBA al documento ogni volta che si pubblica la soluzione. Visual Studio sovrascrive il documento nel percorso di pubblicazione quando si pubblica la soluzione.

Se gli utenti installano la soluzione da una cartella di installazione diversa dalla cartella di pubblicazione, è possibile evitare di aggiungere il codice VBA al documento ogni volta che si pubblica la soluzione. Quando un aggiornamento della pubblicazione è pronto per essere spostato dalla cartella di pubblicazione alla cartella di installazione, copiare tutti i file nella cartella di installazione tranne il documento.

Sul computer dell'utente finale

Se gli utenti finali sono sviluppatori VBA che effettuano chiamate nei servizi forniti nella personalizzazione a livello di documento, è possibile specificare come chiamare il codice utilizzando la proprietà CallVSTOAssembly o il metodo GetManagedClass nelle copie del documento. Quando si pubblicano gli aggiornamenti della soluzione, il codice VBA nel documento nel computer dell'utente finale non viene sovrascritto perché il documento non viene modificato dagli aggiornamenti della pubblicazione.

Attività eseguite dalle proprietà degli elementi host

Quando si utilizzano le proprietà EnableVbaCallers e ReferenceAssemblyFromVbaProject, Visual Studio esegue serie diverse di attività.

EnableVbaCallers

Quando si imposta la proprietà EnableVbaCallers di un elemento host su True in un progetto Visual Basic, Visual Studio esegue le attività seguenti:

  1. Aggiunge gli attributi ComClassAttribute e ComVisibleAttribute alla classe dell'elemento host.

  2. Esegue l'override del metodo GetAutomationObject della classe dell'elemento host.

  3. Imposta la proprietà ReferenceAssemblyFromVbaProject dell'elemento host su True.

Quando si imposta la proprietà EnableVbaCallers nuovamente su False, Visual Studio esegue le attività seguenti:

  1. Rimuove gli attributi ComClassAttribute e ComVisibleAttribute dalla classe ThisDocument.

  2. Rimuove il metodo GetAutomationObject dalla classe dell'elemento host.

    Nota

    Visual Studio non imposta automaticamente la proprietà ReferenceAssemblyFromVbaProject su False. È possibile impostare manualmente questa proprietà su False utilizzando la finestra Proprietà.

ReferenceAssemblyFromVbaProject

Quando la proprietà ReferenceAssemblyFromVbaProject di qualsiasi elemento host in un progetto di Visual Basic o Visual C# viene impostata su True, Visual Studio esegue le attività seguenti:

  1. Genera una libreria dei tipi per l'assembly di personalizzazione e la incorpora nell'assembly.

  2. Aggiunge un riferimento alle librerie dei tipi seguenti nel progetto VBA nel documento:

    • La libreria dei tipi per l'assembly di personalizzazione.

    • Microsoft Visual Studio Tools per la libreria dei tipi Office Execution Engine 9.0. Questa libreria di tipi è inclusa nel Runtime di Visual Studio Tools per Office.

Quando si imposta la proprietà ReferenceAssemblyFromVbaProject nuovamente su False, Visual Studio esegue le attività seguenti:

  1. Rimuove i riferimenti alla libreria dei tipi dal progetto VBA nel documento.

  2. Rimuove la libreria dei tipi incorporata dall'assembly.

Risoluzione dei problemi

Nella tabella seguente sono elencati alcuni errori comuni e i suggerimenti per correggerli.

Errore

Suggerimento

Dopo avere impostato la proprietà EnableVbaCallers o ReferenceAssemblyFromVbaProject, un messaggio di errore indica che il documento non contiene un progetto VBA o che non si dispone delle autorizzazioni per accedere al progetto VBA nel documento.

Assicurarsi che il documento nel progetto contenga almeno una macro VBA, che il progetto VBA sia sufficientemente attendibile per essere eseguito e che non sia protetto da una password.

Dopo avere impostato la proprietà EnableVbaCallers o ReferenceAssemblyFromVbaProject, un messaggio di errore indica che la dichiarazione GuidAttribute manca o è danneggiata.

Assicurarsi che la dichiarazione GuidAttribute si trovi nel file AssemblyInfo.cs o AssemblyInfo.vb del progetto e che tale attributo sia impostato su un GUID valido.

Dopo avere impostato la proprietà EnableVbaCallers o ReferenceAssemblyFromVbaProject, un messaggio di errore indica che il numero di versione specificato da AssemblyVersionAttribute non è valido.

Assicurarsi che la dichiarazione AssemblyVersionAttribute si trovi nel file AssemblyInfo.cs o AssemblyInfo.vb del progetto e che sia impostato su un numero di versione di assembly valido. Per informazioni sui numeri di versione di assembly validi, vedere la classe AssemblyVersionAttribute.

Dopo avere rinominato l'assembly di personalizzazione, il codice VBA che viene chiamato nell'assembly di personalizzazione smette di funzionare.

Se si modifica il nome dell'assembly di personalizzazione dopo averlo esposto al codice VBA, il collegamento tra il progetto VBA nel documento e l'assembly di personalizzazione viene infranto. Per correggere questo problema, impostare la proprietà ReferenceFromVbaAssembly nel progetto su False e poi di nuovo su True, quindi sostituire qualsiasi riferimento al nome dell'assembly precedente nel codice VBA con il nome del nuovo assembly.

Vedere anche

Attività

Procedura: esporre il codice a VBA in un progetto Visual Basic

Procedura: esporre il codice a VBA in un progetto Visual C#

Procedura dettagliata: chiamata di codice da VBA in un progetto Visual Basic

Procedura dettagliata: chiamata di codice da VBA in un progetto Visual C#

Concetti

Pubblicazione di soluzioni Office

Altre risorse

Combinazione di VBA con le personalizzazioni a livello di documento

Programmazione delle personalizzazioni a livello di documento