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


Per la versione di questo articolo relativa a Microsoft C# .NET, vedere il seguente articolo della Microsoft Knowledge Base (gli articoli con prefisso "Q" contengono informazioni in inglese): 302901 .



Per la versione di questo articolo relativa a Microsoft Visual Basic 6.0, vedere il seguente articolo della Microsoft Knowledge Base (gli articoli con prefisso "Q" contengono informazioni in inglese): 238228 .



Per la versione di questo articolo relativa a Microsoft Visual C++ 6.0, vedere il seguente articolo della Microsoft Knowledge Base (gli articoli con prefisso "Q" contengono informazioni in inglese): 230689 .

CONTENUTO DELL'ATTIVITÀ

Sommario

Microsoft Office 2000 e versioni successive supportano 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 Basic .NET.


Interfaccia IDTExensibility2

Un componente aggiuntivo COM è un server COM in-process o una libreria a collegamento dinamico (DLL) ActiveX che implementa l'interfaccia
IDTExensibility2, come descritto nella libreria dei tipi di 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 dalla finestra di dialogo
      Componenti aggiuntivi COM.
    • ext_cm_CommandLine
      - Il componente aggiuntivo viene connesso dalla riga di comando. Si noti che questo parametro non riguarda la creazione di componenti aggiuntivi COM per applicazioni Office.
    • ext_cm_External
      - Il componente aggiuntivo viene connesso da un'applicazione esterna tramite l'automazione. Si noti che questo parametro non riguarda la creazione di componenti aggiuntivi COM per applicazioni 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 a tale componente aggiuntivo nell'insieme
    COMAddIns
    per l'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

Entrambi 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 chiave di registro:
HKEY_CURRENT_USER\Software\Microsoft\Office\OfficeApp\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 come 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 l'interfaccia
IDTExtensibility2
dovrebbero inoltre specificare un valore DWORD denominato CommandLineSafe per indicare se i componenti aggiuntivi possono essere utilizzati per operazioni che non supportano un'interfaccia utente. Un valore di 0x00 indica False, mentre un valore di 0x01 indica True.


Come creare un componente aggiuntivo COM con Visual Basic .NET

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 Basic .NET, attenersi alla seguente procedura:
  1. In Visual Basic .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 implementa
    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 Office di riconoscere e caricare il componente aggiuntivo.
È possibile eseguire l'intera procedura oppure creare un progetto .NET di tipo
Componente aggiuntivo condiviso. Verrà avviata la procedura di creazione guidata Extensibility, che facilita la creazione di un componente aggiuntivo COM in .NET.


La procedura di creazione guidata Extensibility crea un progetto Libreria di classi di Visual Basic .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. Le impostazioni di generazione del progetto hanno l'opzione
Registra per interoperabilità COM
selezionata. 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. Scegliere
    Nuovo
    dal menu
    File
    in Visual Studio .NET, quindi scegliere
    Progetto.
  2. Nella finestra di dialogo
    Nuovo progetto
    espandere
    Altri progetti
    in
    Tipi progetto, selezionare
    Progetti di estensibilità, quindi selezionare il modello
    Componente aggiuntivo condiviso.
  3. Digitare
    MyCOMAddin
    come nome del componente aggiuntivo, quindi scegliere
    OK.
  4. Quando viene visualizzata la finestra Creazione guidata Extensibility, attenersi alla seguente procedura:
    1. Nella pagina 1 selezionare
      Crea componente aggiuntivo utilizzando Visual Basic, quindi scegliere
      Avanti.
    2. Nella pagina 2 selezionare le seguenti applicazioni host, quindi scegliere
      Avanti:
      • Microsoft Word
      • Microsoft PowerPoint
      • Microsoft Outlook
      • Microsoft Excel
      • Microsoft Access
    3. Nella pagina 3 specificare un nome e una descrizione per il componente aggiuntivo, quindi scegliere
      Avanti.
      NOTA: il nome e la descrizione del componente aggiuntivo vengono visualizzati nella finestra di dialogo
      Componente aggiuntivo COM
      nell'applicazione Office.


    4. : il nome e la descrizione del componente aggiuntivo vengono visualizzati nella finestra di dialogo Nella pagina 4 selezionare tutte le opzioni disponibili, quindi scegliere
      Avanti.
    5. : il nome e la descrizione del componente aggiuntivo vengono visualizzati nella finestra di dialogo Scegliere
      Fine.
  5. Aggiungere il membro seguente alla classe
    Connect:
    Dim WithEvents MyButton As CommandBarButton
  6. Implementare il codice per tutti gli altri membri di
    IDTExtensibility2
    nella classe
    Connect, come illustrato di seguito:
        Public Sub OnBeginShutdown(ByRef custom As System.Array) Implements Extensibility.IDTExtensibility2.OnBeginShutdown
    On Error Resume Next
    ' Notify the user you are shutting down, and delete the button.
    MsgBox("Our custom Add-in is unloading.")
    MyButton.Delete()
    MyButton = Nothing

    End Sub

    Public Sub OnAddInsUpdate(ByRef custom As System.Array) Implements Extensibility.IDTExtensibility2.OnAddInsUpdate
    '
    End Sub

    Public Sub OnStartupComplete(ByRef custom As System.Array) Implements Extensibility.IDTExtensibility2.OnStartupComplete

    Dim oCommandBars As CommandBars
    Dim oStandardBar As CommandBar

    On Error Resume Next
    ' Set up a custom button on the "Standard" command bar.
    oCommandBars = applicationObject.CommandBars
    If oCommandBars Is Nothing Then
    ' Outlook has the CommandBars collection on the Explorer object.
    oCommandBars = applicationObject.ActiveExplorer.CommandBars
    End If

    oStandardBar = oCommandBars.Item("Standard")
    If oStandardBar Is Nothing Then
    ' Access names its main toolbar Database.

    oStandardBar = oCommandBars.Item("Database")

    End If

    ' In case the button was not deleted, use the exiting one.
    MyButton = oStandardBar.Controls.Item("My Custom Button")
    If MyButton Is Nothing Then

    MyButton = oStandardBar.Controls.Add(1)
    With MyButton
    .Caption = "My Custom Button"
    .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.

    .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 clicks the button,
    ' MSO loads the add-in automatically and then raises
    ' the Click event for the add-in to handle.

    .OnAction = "!<MyCOMAddin.Connect>"

    .Visible = True
    End With
    End If

    ' Display a simple message to show which application you started in.
    MsgBox("Started in " & applicationObject.Name & ".")


    oStandardBar = Nothing
    oCommandBars = Nothing


    End Sub

    Public Sub OnDisconnection(ByVal RemoveMode As Extensibility.ext_DisconnectMode, ByRef custom As System.Array) Implements Extensibility.IDTExtensibility2.OnDisconnection

    On Error Resume Next
    If RemoveMode <> Extensibility.ext_DisconnectMode.ext_dm_HostShutdown Then _
    Call OnBeginShutdown(custom)

    applicationObject = Nothing


    End Sub

    Public Sub OnConnection(ByVal application As Object, ByVal connectMode As Extensibility.ext_ConnectMode, ByVal addInInst As Object, ByRef custom As System.Array) Implements Extensibility.IDTExtensibility2.OnConnection


    MsgBox("On Connection In MyAddin")
    applicationObject = application
    addInInstance = addInInst


    ' If you aren't in startup, manually call OnStartupComplete.
    If (connectMode <> Extensibility.ext_ConnectMode.ext_cm_Startup) Then _
    Call OnStartupComplete(custom)

    End Sub


    Private Sub MyButton_Click(ByVal Ctrl As Microsoft.Office.Core.CommandBarButton, ByRef CancelDefault As Boolean) Handles MyButton.Click
    MsgBox("Our CommandBar button was pressed!")
    End Sub
  7. Compilare e verificare il componente aggiuntivo COM attenendosi alla seguente procedura:
    1. Scegliere
      Genera MyCOMAddin
      dal menu
      Genera. 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 OnConnection e viene visualizzata una finestra di messaggio. Alla chiusura della finestra di messaggio, viene generato l'evento OnStartupComplete e viene visualizzata una seconda finestra di messaggio. Chiudere la finestra di messaggio.
    4. Si noti che il componente aggiuntivo ha aggiunto alla barra degli strumenti standard un nuovo pulsante personalizzato denominato My Custom Button.
    5. Scegliere
      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.
    6. Chiudere l'applicazione Office.
    7. 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 Knowledge Base riportato di seguito (gli articoli con prefisso "Q" contengono informazioni in inglese):

190253 INFO: VB6 Designers Do Not Work in VB5


Per ulteriori informazioni sullo sviluppo di soluzioni Web per Internet Explorer, visitare i seguenti siti Web:


(c) Microsoft Corporation 2001, Tutti i diritti riservati. Con il contributo di Ranjit R. Sawant, Microsoft Corporation.

Proprietà

ID articolo: 302896 - Ultima revisione: 21 mag 2007 - Revisione: 1

Feedback