HOW TO: Creare un componente aggiuntivo COM di Office con Visual C# .NET

Traduzione articoli Traduzione articoli
Identificativo articolo: 302901 - Visualizza i prodotti a cui si riferisce l?articolo.
Questo articolo Ŕ stato precedentemente pubblicato con il codice di riferimento I302901
Espandi tutto | Chiudi tutto

In questa pagina

Sommario

Microsoft Office 2002 supporta una nuova architettura uniforme di progettazione per la creazione di componenti aggiuntivi che consentono di migliorare e controllare le applicazioni Office. Tali componenti aggiuntivi sono denominati componenti aggiuntivi COM. In questo articolo viene illustrata la procedura dettagliata per creare un componente aggiuntivo COM di Office con Visual C# .NET.

Interfaccia IDTExensibility2

Un componente aggiuntivo COM Ŕ un server COM in-process oppure una libreria dinamica (DLL) ActiveX che implementa l'interfaccia IDTExensibility2 come descritto nella libreria dei tipi Progettazione componenti aggiuntivi Microsoft (Msaddndr.dll). Tutti i componenti aggiuntivi COM ereditano proprietÓ da tale interfaccia e devono implementarne i relativi cinque metodi.

OnConnection

L'evento OnConnection viene generato ogni volta che il componente aggiuntivo COM Ŕ connesso. Il componente aggiuntivo pu˛ essere connesso all'avvio, dall'utente finale oppure attraverso l'automazione. Se OnConnection ha esito positivo, il componente aggiuntivo viene considerato caricato. Se viene restituito un messaggio di errore, l'applicazione host rilascia immediatamente il proprio riferimento al componente aggiuntivo e l'oggetto viene distrutto.

OnConnection accetta i seguenti quattro parametri:
  • Application - Riferimento all'oggetto applicazione host.
  • ConnectMode - Costante che specifica la modalitÓ di connessione del componente aggiuntivo. ╚ possibile connettere il componente aggiuntivo nei seguenti modi:
    • ext_cm_AfterStartup - Il componente aggiuntivo viene avviato dall'utente finale tramite la finestra di dialogo Componenti aggiuntivi COM.
    • ext_cm_CommandLine - La connessione al componente aggiuntivo viene avviata dalla riga di comando. Questo parametro non riguarda la creazione di componenti aggiuntivi COM per applicazioni di Office.
    • ext_cm_External - La connessione al componente aggiuntivo viene avviata da un'applicazione esterna tramite l'automazione. Questo parametro non riguarda la creazione di componenti aggiuntivi COM per applicazioni di Office.
    • ext_cm_Startup - Il componente aggiuntivo viene avviato dall'host all'avvio dell'applicazione. Questo comportamento Ŕ controllato da un'impostazione del Registro di sistema.
  • AddInInst - Riferimento all'oggetto COMAddIn che fa riferimento al componente aggiuntivo nell'insieme COMAddIns relativo all'applicazione host.
  • Custom - Matrice di valori di tipo Variant che pu˛ contenere dati definiti dall'utente.

OnDisconnection

L'evento OnDisconnection viene generato quando il componente aggiuntivo COM viene disconnesso e appena prima che venga scaricato dalla memoria. Il componente aggiuntivo dovrebbe eseguire un eventuale rilascio delle risorse in questo evento e ripristinare eventuali modifiche apportate all'applicazione host.

OnDisconnection accetta i seguenti due parametri:
  • RemoveMode - Costante che specifica la modalitÓ di disconnessione del componente aggiuntivo. ╚ possibile disconnettere il componente aggiuntivo nei seguenti modi:
    • ext_dm_HostShutdown - Il componente aggiuntivo viene disconnesso quando viene chiusa l'applicazione host.
    • ext_dm_UserClosed - Il componente aggiuntivo viene disconnesso dall'utente finale o da un controller di automazione.
  • Custom - Matrice di valori di tipo Variant che pu˛ contenere dati definiti dall'utente.

OnAddInsUpdate

L'evento OnAddInsUpdate viene generato quando l'insieme di componenti aggiuntivi COM registrati subisce delle modifiche. In altre parole, ogni volta che un componente aggiuntivo COM viene installato o rimosso dall'applicazione host, viene generato un evento OnAddInsUpdate.

OnStartupComplete e OnBeginShutdown

I metodi OnStartupComplete e OnBeginShutdown vengono chiamati quando l'applicazione host ha lasciato oppure sta entrando in uno stato in cui dovrebbe essere evitata l'interazione con l'utente poichÚ l'applicazione Ŕ in fase di caricamento o di rimozione dalla memoria. La chiamata a OnStartupComplete viene effettuata solo se il componente aggiuntivo Ŕ stato connesso all'avvio, mentre quella a OnBeginShutdown solo se l'host disconnette il componente aggiuntivo in fase di arresto.

PoichÚ l'interfaccia utente dell'applicazione host Ŕ pienamente attiva quando vengono generati questi eventi, questi potrebbero rappresentare l'unico modo per eseguire determinate azioni che altrimenti non sarebbero disponibili da OnConnection e OnDisconnection.

Registrazione del componente aggiuntivo COM

Oltre alla normale registrazione COM, Ŕ necessario che un componente aggiuntivo COM si registri con tutte le applicazioni di Office in cui viene eseguito. Per registrarsi con una determinata applicazione, Ŕ necessario che il componente aggiuntivo crei una sottochiave, utilizzando il proprio ProgID come nome per la chiave, nella seguente posizione:
HKEY_CURRENT_USER\Software\Microsoft\Office\ApplicazioneOffice\Addins\ProgID
In questa posizione il componente aggiuntivo pu˛ specificare i valori sia per il nome descrittivo visualizzato che per la descrizione completa. Il componente aggiuntivo dovrebbe inoltre specificare un comportamento di caricamento preferito utilizzando un valore DWORD denominato LoadBehavior. Tale valore determina il modo in cui il componente aggiuntivo viene caricato dall'applicazione host ed Ŕ costituito da una combinazione dei seguenti valori:
  • 0 = Disconnect ? Non viene caricato.
  • 1 = Connected ? Viene caricato.
  • 2 = Bootload ? Viene caricato all'avvio dell'applicazione.
  • 8 = DemandLoad ? Viene caricato solo se richiesto dall'utente.
  • 16 = ConnectFirstTime ? Viene caricato solo una volta (all'avvio successivo).
Il valore che viene generalmente specificato Ŕ 0x03 (Connected | Bootload).

I componenti aggiuntivi che implementano IDTExtensibility2 devono inoltre specificare un valore DWORD denominato CommandLineSafe per indicare se possono eseguire senza problemi operazioni che non supportano un'interfaccia utente. Un valore di 0x00 indica False, mentre un valore di 0x01 indica True.

Creazione di un componente aggiuntivo COM con Visual C#

Come affermato in precedenza, un componente aggiuntivo COM di Office Ŕ un server COM in-process che viene attivato da un'applicazione Office tramite il livello runtime COM. Per lo sviluppo di un componente aggiuntivo COM in .NET Ŕ pertanto necessario che il componente aggiuntivo sia implementato in .NET e quindi esposto ai client COM (ovvero alle applicazioni Office) attraverso il livello Interop di COM.

Per creare un componente aggiuntivo COM in Visual C# .NET, attenersi alla seguente procedura:
  1. In Visual C# .NET creare un progetto Libreria di classi.
  2. Aggiungere un riferimento alla libreria dei tipi che implementa IDTExtensibility2. Il relativo assembly di interoperabilitÓ primario Ŕ giÓ disponibile con il nome di Extensibility.
  3. Aggiungere un riferimento alla Libreria oggetti di Microsoft Office. Il relativo assembly di interoperabilitÓ primario Ŕ giÓ disponibile con il nome di Office.
  4. Creare una classe pubblica nella libreria di classi che implementi IDTExtensibility2.
  5. Dopo aver generato la libreria di classi, registrare la libreria per l'interoperabilitÓ COM. A tal scopo, generare un assembly con un nome sicuro per questa libreria di classi e quindi registrarlo con l'interoperabilitÓ COM. Per registrare un componente .NET per l'interoperabilitÓ COM, Ŕ possibile utilizzare Regasm.exe.
  6. Creare voci di registro appropriate che consentano alle applicazioni di Office di riconoscere e caricare il componente aggiuntivo.
╚ possibile eseguire l'intera procedura oppure creare un progetto .NET di tipo Shared Addin. VerrÓ avviata la procedura di creazione guidata Extensibility, che facilita la creazione di un componente aggiuntivo COM in .NET.

La Creazione guidata Extensibility consente la creazione di un progetto di Libreria di classi Visual C# .NET insieme a una classe Connect che implementa l'interfaccia IDTExtensibility2. Viene inoltre generata la struttura del codice che implementa i membri vuoti di IDTExtensibility. Questo progetto contiene riferimenti agli assembly Extensibility e Office. Nelle impostazioni di generazione del progetto Ŕ selezionata l'opzione Registra per interoperabilitÓ COM. Viene generato il file di chiave assembly (snk), al quale viene fatto riferimento nell'attributo AssemblyKeyfile in Assemblyinfo.vb.

Insieme al progetto libreria di classi, la procedura guidata genera un progetto di installazione che pu˛ essere utilizzato per la distribuzione del componente aggiuntivo COM in altri computer. Se lo si desidera, Ŕ possibile rimuovere questo progetto.

Procedura di esempio

  1. Dal menu File di Visual Studio .NET, scegliere Nuovo, quindi Progetto.
  2. Nella finestra di dialogo Nuovo progetto espandere Altri progetti in Tipi progetto, selezionare Progetti Extensibility, quindi selezionare il modello Componente aggiuntivo condiviso.
  3. Digitare MyCOMAddin come nome del componente aggiuntivo, quindi scegliere OK.
  4. Quando viene visualizzata la finestra della Creazione guidata Extensibility, attenersi alla seguente procedura:
    1. Nella prima pagina selezionare Crea componente aggiuntivo utilizzando Visual C#, quindi scegliere Avanti.
    2. Nella seconda pagina selezionare le seguenti applicazioni host, quindi scegliere Avanti:
      • Microsoft Word
      • Microsoft PowerPoint
      • Microsoft Outlook
      • Microsoft Excel
      • Microsoft Access
    3. Nella terza pagina specificare un nome e una descrizione per il componente aggiuntivo, quindi scegliere Avanti. NOTA: il nome e la descrizione del componente aggiuntivo verranno visualizzati nella finestra di dialogo Componenti aggiuntivi COM nell'applicazione di Office.

    4. Nella quarta pagina selezionare tutte le opzioni disponibili, quindi scegliere Avanti.
    5. Scegliere Fine.
  5. Scegliere Aggiungi riferimento dal menu Progetto. Selezionare System.Windows.Forms.DLL nell'elenco dei componenti, fare clic su Seleziona, quindi scegliere OK.
  6. All'elenco degli spazi dei nomi nella classe Connect aggiungere quanto segue:
    using System.Reflection;
  7. Aggiungere il seguente membro alla classe Connect:
    private CommandBarButton MyButton; 
  8. Implementare il codice per i membri di IDTExtensibility2 nella classe Connect, come segue:
    public void OnConnection(object application, Extensibility.ext_ConnectMode connectMode, object addInInst, ref System.Array custom) {
       applicationObject = application;
       addInInstance = addInInst;
    
       if(connectMode != Extensibility.ext_ConnectMode.ext_cm_Startup)
       {
          OnStartupComplete(ref custom);
       }
    
    }
    
    public void OnDisconnection(Extensibility.ext_DisconnectMode disconnectMode, ref System.Array custom) {
       if(disconnectMode != Extensibility.ext_DisconnectMode.ext_dm_HostShutdown)
       {
          OnBeginShutdown(ref custom);
       }
       applicationObject = null;
    }
    
    
    public void OnAddInsUpdate(ref System.Array custom)
    {
    }
    
    public void OnStartupComplete(ref System.Array custom)
    {
       CommandBars oCommandBars;
       CommandBar oStandardBar;
    
       try
       {
       oCommandBars = (CommandBars)applicationObject.GetType().InvokeMember("CommandBars", BindingFlags.GetProperty , null, applicationObject ,null);
       }
       catch(Exception)
       {
       // Outlook has the CommandBars collection on the Explorer object.
       object oActiveExplorer;
       oActiveExplorer= applicationObject.GetType().InvokeMember("ActiveExplorer",BindingFlags.GetProperty,null,applicationObject,null);
       oCommandBars= (CommandBars)oActiveExplorer.GetType().InvokeMember("CommandBars",BindingFlags.GetProperty,null,oActiveExplorer,null);
       }
    
       // Set up a custom button on the "Standard" commandbar.
       try
       {
       oStandardBar = oCommandBars["Standard"];        
       }
       catch(Exception)
       {
       // Access names its main toolbar Database.
       oStandardBar = oCommandBars["Database"];      
       }
    
       // In case the button was not deleted, use the exiting one.
       try
       {
       MyButton = (CommandBarButton)oStandardBar.Controls["My Custom Button"];
       }
       catch(Exception)
       {
          object omissing = System.Reflection.Missing.Value ;
          MyButton = (CommandBarButton) oStandardBar.Controls.Add(1, omissing , omissing , omissing , omissing);
          MyButton.Caption = "My Custom Button";
          MyButton.Style = MsoButtonStyle.msoButtonCaption;
       }
    
       // The following items are optional, but recommended. 
       //The Tag property lets you quickly find the control 
       //and helps MSO keep track of it when more than
       //one application window is visible. The property is required
       //by some Office applications and should be provided.
       MyButton.Tag = "My Custom Button";
    
       // The OnAction property is optional but recommended. 
       //It should be set to the ProgID of the add-in, so that if
       //the add-in is not loaded when a user presses the button,
       //MSO loads the add-in automatically and then raises
       //the Click event for the add-in to handle. 
       MyButton.OnAction = "!<MyCOMAddin.Connect>";
    
       MyButton.Visible = true;
       MyButton.Click += new Microsoft.Office.Core._CommandBarButtonEvents_ClickEventHandler(this.MyButton_Click);
    
    
       object oName = applicationObject.GetType().InvokeMember("Name",BindingFlags.GetProperty,null,applicationObject,null);
    
       // Display a simple message to show which application you started in.
       System.Windows.Forms.MessageBox.Show("This Addin is loaded by " + oName.ToString()   , "MyCOMAddin");
       oStandardBar = null;
       oCommandBars = null;
    }
    
    public void OnBeginShutdown(ref System.Array custom)
    {
       object omissing = System.Reflection.Missing.Value ;
       System.Windows.Forms.MessageBox.Show("MyCOMAddin Add-in is unloading.");
       MyButton.Delete(omissing);
       MyButton = null;
    }
    
    private void MyButton_Click(CommandBarButton cmdBarbutton,ref bool cancel) {
       System.Windows.Forms.MessageBox.Show("MyButton was Clicked","MyCOMAddin"); }
    					
  9. Compilare e verificare il componente aggiuntivo COM attenendosi alla seguente procedura:
    1. Dal menu Genera scegliere Genera soluzione. Si noti che la creazione del componente aggiuntivo COM determina la registrazione della classe .NET con l'interoperabilitÓ COM.
    2. Avviare una delle applicazioni Office selezionate come applicazioni host per il componente aggiuntivo, ad esempio Word o Excel.
    3. Dopo l'avvio del componente aggiuntivo, viene generato l'evento OnStartupComplete e viene visualizzata una finestra di messaggio. Chiudere la finestra di messaggio. Si noti che il componente aggiuntivo ha aggiunto alla barra degli strumenti standard un nuovo pulsante personalizzato denominato "My Custom Button".
    4. Fare clic su My Custom Button. L'evento Click del pulsante viene gestito dal componente aggiuntivo e viene visualizzata una finestra di messaggio. Chiudere la finestra di messaggio.
    5. Chiudere l'applicazione di Office.
    6. Alla chiusura dell'applicazione, viene generato l'evento OnBeginShutDown e viene visualizzata una finestra di messaggio. Chiudere la finestra di messaggio per terminare la dimostrazione.

Riferimenti

Per ulteriori informazioni sulla creazione di componenti aggiuntivi COM, fare clic sul numero dell'articolo della Microsoft Knowledge Base riportato di seguito:
190253 INFO: VB6 Designers Do Not Work in VB5
(c) Microsoft Corporation 2001, Tutti i diritti riservati. Con il contributo di Ranjit R. Sawant, Microsoft Corporation.

ProprietÓ

Identificativo articolo: 302901 - Ultima modifica: venerdý 3 ottobre 2003 - Revisione: 4.1
Le informazioni in questo articolo si applicano a
  • Microsoft Visual C# .NET 2002 Standard Edition
  • Microsoft Visual C# .NET 2003 Standard Edition
  • Microsoft Excel 2002 Standard Edition
  • Microsoft PowerPoint 2002 Standard Edition
  • Microsoft Word 2002 Standard Edition
  • Microsoft Outlook 2002 Standard Edition
Chiavi:á
kbautomation kbhowtomaster KB302901
LE INFORMAZIONI CONTENUTE NELLA MICROSOFT KNOWLEDGE BASE SONO FORNITE SENZA GARANZIA DI ALCUN TIPO, IMPLICITA OD ESPLICITA, COMPRESA QUELLA RIGUARDO ALLA COMMERCIALIZZAZIONE E/O COMPATIBILITA' IN IMPIEGHI PARTICOLARI. L'UTENTE SI ASSUME L'INTERA RESPONSABILITA' PER L'UTILIZZO DI QUESTE INFORMAZIONI. IN NESSUN CASO MICROSOFT CORPORATION E I SUOI FORNITORI SI RENDONO RESPONSABILI PER DANNI DIRETTI, INDIRETTI O ACCIDENTALI CHE POSSANO PROVOCARE PERDITA DI DENARO O DI DATI, ANCHE SE MICROSOFT O I SUOI FORNITORI FOSSERO STATI AVVISATI. IL DOCUMENTO PUO' ESSERE COPIATO E DISTRIBUITO ALLE SEGUENTI CONDIZIONI: 1) IL TESTO DEVE ESSERE COPIATO INTEGRALMENTE E TUTTE LE PAGINE DEVONO ESSERE INCLUSE. 2) I PROGRAMMI SE PRESENTI, DEVONO ESSERE COPIATI SENZA MODIFICHE, 3) IL DOCUMENTO DEVE ESSERE DISTRIBUITO INTERAMENTE IN OGNI SUA PARTE. 4) IL DOCUMENTO NON PUO' ESSERE DISTRIBUITO A SCOPO DI LUCRO.

Invia suggerimenti

 

Contact us for more help

Contact us for more help
Connect with Answer Desk for expert help.
Get more support from smallbusiness.support.microsoft.com