Chiamata di codice nei componenti aggiuntivi a livello di applicazione da altre soluzioni Office

Articolo
08/11/2011

Un oggetto può essere esposto nel componente aggiuntivo ad altre soluzioni, comprese altre soluzioni Microsoft Office. Questa possibilità risulta utile se il componente aggiuntivo fornisce un servizio che si desidera possa essere utilizzato da altre soluzioni. Se ad esempio si dispone di un componente aggiuntivo per Microsoft Office Excel che effettua i calcoli dei dati finanziari di un servizio Web, le altre soluzioni possono effettuare tali calcoli eseguendo la chiamata nel componente aggiuntivo per Excel in fase di esecuzione.

Si applica a: le informazioni fornite in questo argomento sono valide per i progetti a livello di applicazione per Microsoft Office 2010 e Microsoft Office System 2007. Per ulteriori informazioni, vedere Funzionalità disponibili in base ai tipi di progetto e applicazioni di Office.

Questo processo è costituito da due passaggi principali:

Esposizione di un oggetto del componente aggiuntivo ad altre soluzioni.
Accesso all'oggetto esposto dal componente aggiuntivo e chiamata dei membri dell'oggetto in un'altra soluzione.

Tipi di soluzioni in grado di chiamare il codice di un componente aggiuntivo

È possibile esporre un oggetto di un componente aggiuntivo ai seguenti tipi di soluzioni:

Codice Visual Basic, Applications Edition (VBA) di un documento caricato nello stesso processo dell'applicazione del componente aggiuntivo.
Personalizzazioni a livello di documento caricate nello stesso processo dell'applicazione del componente aggiuntivo.
Altri componenti aggiuntivi creati tramite i modelli di progetto di Office in Visual Studio.
Componenti aggiuntivi COM, ovvero componenti aggiuntivi che implementano direttamente l'interfaccia IDTExtensibility2.
Qualsiasi soluzione in esecuzione in un processo diverso dal componente aggiuntivo (questi tipi di soluzioni sono anche denominati client out-of-process). Sono incluse applicazioni che automatizzano un'applicazione di Office, quale Windows Form o un'applicazione console, e componenti aggiuntivi caricati in un processo diverso.

Esposizione di oggetti ad altre soluzioni

Per esporre un oggetto del componente aggiuntivo ad altre soluzioni, effettuare le seguenti operazioni:

Definire una classe che si desidera esporre ad altre soluzioni.
Eseguire l'override del metodo RequestComAddInAutomationService nella classe ThisAddIn Restituire un'istanza della classe che si desidera esporre ad altre soluzioni.

Definizione della classe che si desidera esporre ad altre soluzioni

Questa classe deve essere almeno pubblica, deve disporre dell'attributo ComVisibleAttribute impostato su true e deve esporre l'interfaccia IDispatch.

Il modo consigliato per esporre l'interfaccia IDispatch consiste nell'eseguire i passaggi seguenti:

Definire un'interfaccia che dichiari i membri che si desidera esporre ad altre soluzioni. È possibile definire questa interfaccia nel progetto di componente aggiuntivo. È tuttavia preferibile definire questa interfaccia in un progetto di libreria di classi separato se si desidera esporre la classe a soluzioni non VBA, in modo che le soluzioni che chiamano il componente aggiuntivo possano fare riferimento all'interfaccia senza fare riferimento al progetto di componente aggiuntivo.
Applicare l'attributo ComVisibleAttribute a questa interfaccia e impostare tale attributo su true.
Modificare la classe per implementare questa interfaccia.
Applicare l'attributo ClassInterfaceAttribute alla classe e impostare tale attributo sul valore None dell'enumerazione ClassInterfaceType.
Se si desidera esporre la classe a client out-of-process, potrebbe essere necessario effettuare i passaggi seguenti:
- Derivare la classe da StandardOleMarshalObject: Per ulteriori informazioni, vedere Esposizione di classi a client out-of-process.
- Impostare la proprietà Registra per interoperabilità COM nel progetto in cui si definisce l'interfaccia. Questo passaggio è necessario solo se si desidera consentire ai client di utilizzare l'associazione anticipata per effettuare chiamate nel componente aggiuntivo. Per ulteriori informazioni, vedere Procedura: registrare un componente per l'interoperabilità COM.

Nell'esempio di codice riportato di seguito viene illustrata una classe AddInUtilities con un metodo ImportData che è possibile chiamare da altre soluzioni. Per visualizzare il codice nel contesto di una procedura dettagliata di maggiore portata, vedere Procedura dettagliata: chiamata di codice in un componente aggiuntivo a livello di applicazione da VBA.

<ComVisible(True)> _
Public Interface IAddInUtilities
    Sub ImportData()
End Interface

<ComVisible(True)> _
<ClassInterface(ClassInterfaceType.None)> _
Public Class AddInUtilities
    Implements IAddInUtilities

    ' This method tries to write a string to cell A1 in the active worksheet.
    Public Sub ImportData() Implements IAddInUtilities.ImportData

        Dim activeWorksheet As Excel.Worksheet = Globals.ThisAddIn.Application.ActiveSheet

        If activeWorksheet IsNot Nothing Then
            Dim range1 As Excel.Range = activeWorksheet.Range("A1")
            range1.Value2 = "This is my data"
        End If
    End Sub
End Class

[ComVisible(true)]
public interface IAddInUtilities
{
    void ImportData();
}

[ComVisible(true)]
[ClassInterface(ClassInterfaceType.None)]
public class AddInUtilities : IAddInUtilities
{
    // This method tries to write a string to cell A1 in the active worksheet.
    public void ImportData()
    {
        Excel.Worksheet activeWorksheet = Globals.ThisAddIn.Application.ActiveSheet as Excel.Worksheet;

        if (activeWorksheet != null)
        {
            Excel.Range range1 = activeWorksheet.get_Range("A1", System.Type.Missing);
            range1.Value2 = "This is my data";
        }
    }
}

Esposizione di classi a VBA

Quando si effettuano i passaggi descritti sopra, il codice VBA può chiamare solo i metodi dichiarati nell'interfaccia. Il codice VBA non può chiamare alcun altro metodo della classe, compresi i metodi che la classe ottiene dalle classi di base, ad esempio Object.

In alternativa, è possibile esporre l'interfaccia IDispatch impostando l'attributo ClassInterfaceAttribute sul valore AutoDispatch o AutoDual dell'enumerazione ClassInterfaceType. Se si esegue questa operazione, non è necessario dichiarare i metodi in un'interfaccia separata. Tuttavia, il codice VBA può chiamare qualsiasi metodo pubblico e non statico della classe, compresi i metodi ottenuti dalle classi di base, ad esempio Object. Inoltre, i client out-of-process che utilizzano l'associazione anticipata non possono chiamare la classe.

Esposizione di classi ai client out-of-process

Se si desidera esporre una classe nel componente aggiuntivo a client out-of-process, è necessario derivare la classe da StandardOleMarshalObject per assicurarsi che i client out-of-process possano chiamare l'oggetto componente aggiuntivo esposto. In caso contrario, i tentativi di ottenere un'istanza dell'oggetto esposto in un client out-of-process potrebbero avere un esito negativo imprevisto.

Questa situazione si verifica perché tutte le chiamate nel modello a oggetti di un'applicazione di Office devono essere effettuate nel thread principale dell'interfaccia utente, mentre le chiamate da un client out-of-process all'oggetto arriveranno su un thread RPC (Remote Procedure Call) arbitrario. Il meccanismo di marshalling COM in .NET Framework non passerà i thread e tenterà invece di effettuare il marshalling della chiamata all'oggetto sul thread RPC in ingresso anziché sul thread principale dell'interfaccia utente. Se l'oggetto è un'istanza di una classe che deriva da StandardOleMarshalObject, viene automaticamente effettuato il marshalling delle chiamate in ingresso all'oggetto in relazione al thread in cui è stato creato l'oggetto esposto, che sarà il thread principale dell'interfaccia utente dell'applicazione host.

Per ulteriori informazioni sull'utilizzo dei thread nelle soluzioni Office, vedere Supporto del threading in Office.

Override del metodo RequestComAddInAutomationService

Nell'esempio di codice riportato di seguito viene illustrato come eseguire l'override del metodo RequestComAddInAutomationService nella classe ThisAddIn nel componente aggiuntivo. In questo esempio si presuppone che sia stata definita una classe denominata AddInUtilities che si desidera esporre ad altre soluzioni. Per visualizzare il codice nel contesto di una procedura dettagliata di maggiore portata, vedere Procedura dettagliata: chiamata di codice in un componente aggiuntivo a livello di applicazione da VBA.

Private utilities As AddInUtilities

Protected Overrides Function RequestComAddInAutomationService() As Object
    If utilities Is Nothing Then
        utilities = New AddInUtilities()
    End If
    Return utilities
End Function

private AddInUtilities utilities;

protected override object RequestComAddInAutomationService()
{
    if (utilities == null)
        utilities = new AddInUtilities();

    return utilities;
}

Quando il componente aggiuntivo viene caricato, Runtime di Visual Studio Tools per Office chiama il metodo RequestComAddInAutomationService. Il runtime assegna l'oggetto restituito alla proprietà Object di un oggetto COMAddIn che rappresenta il componente aggiuntivo. Questo oggetto COMAddIn è disponibile per altre soluzioni Office e per soluzioni che automatizzano Office.

Accesso agli oggetti da altre soluzioni

Per chiamare l'oggetto esposto del componente aggiuntivo, effettuare le seguenti operazioni nella soluzione client:

Ottenere l'oggetto COMAddIn che rappresenta il componente aggiuntivo esposto. I client possono accedere a tutti i componenti aggiuntivi disponibili utilizzando la proprietà Application.COMAddIns nel modello a oggetti dell'applicazione Office host.
Accedere alla proprietà Object dell'oggetto COMAddIn. Questa proprietà restituisce l'oggetto esposto dal componente aggiuntivo.
Chiamare i membri dell'oggetto esposto.

La modalità con cui si utilizza il valore restituito della proprietà COMAddIn.Object è diversa per i client VBA e i client non VBA. Per i client out-of-process, il codice aggiuntivo è necessario per evitare una possibile race condition.

Accesso agli oggetti dalle soluzioni VBA

Nell'esempio di codice riportato di seguito viene illustrato come utilizzare VBA per chiamare un metodo esposto da un componente aggiuntivo. Questa macro VBA chiama un metodo denominato ImportData definito in un componente aggiuntivo denominato ExcelImportData. Per visualizzare il codice nel contesto di una procedura dettagliata di maggiore portata, vedere Procedura dettagliata: chiamata di codice in un componente aggiuntivo a livello di applicazione da VBA.

Sub CallVSTOMethod()
    Dim addIn As COMAddIn
    Dim automationObject As Object
    Set addIn = Application.COMAddIns("ExcelImportData")
    Set automationObject = addIn.Object
    automationObject.ImportData
End Sub

Accesso agli oggetti dalle soluzioni non VBA

In una soluzione non VBA è necessario eseguire il cast del valore della proprietà COMAddIn.Object in relazione all'interfaccia che viene implementata, quindi è possibile chiamare i metodi esposti nell'oggetto dell'interfaccia. Nell'esempio di codice riportato di seguito viene illustrato come chiamare il metodo ImportData da un componente aggiuntivo diverso creato tramite gli strumenti di sviluppo di Office in Visual Studio.

Dim addIn As Office.COMAddIn = Globals.ThisAddIn.Application.COMAddIns.Item("ExcelImportData")
Dim utilities As ExcelImportData.IAddInUtilities = TryCast( _
    addIn.Object, ExcelImportData.IAddInUtilities)
utilities.ImportData()

object addInName = "ExcelImportData";
Office.COMAddIn addIn = Globals.ThisAddIn.Application.COMAddIns.Item(ref addInName);
ExcelImportData.IAddInUtilities utilities = (ExcelImportData.IAddInUtilities)addIn.Object;
utilities.ImportData();

In questo esempio, se si tenta di eseguire il cast del valore della proprietà COMAddIn.Object alla classe AddInUtilities e non all'interfaccia IAddInUtilities, verrà generata l'eccezione InvalidCastException.

Vedere anche

Cronologia delle modifiche

Data	Cronologia	Motivo
Settembre 2010	Migliorata l'organizzazione del contenuto e rimosse informazioni ridondanti.	Miglioramento delle informazioni.

Settembre 2010

Migliorata l'organizzazione del contenuto e rimosse informazioni ridondanti.

Miglioramento delle informazioni.

Condividi tramite