Procedura: Creare un componente aggiuntivo COM per l'aggiunta di funzionalità personalizzate a InfoPath

Microsoft Office InfoPath 2007 supporta i componenti aggiuntivi COM che consentono di personalizzare la modifica del modulo. Sebbene si tratti di una nuova funzionalità in Office InfoPath 2007, altre applicazioni Office, ad esempio Microsoft Office Word e Microsoft Office Excel, supportano i componenti aggiuntivi COM sin dall'introduzione di Office 2000.

Il supporto di componenti aggiuntivi COM in Office InfoPath 2007 è disponibile nell'ambiente di modifica dei moduli. Non è possibile estendere l'ambiente di progettazione dei moduli mediante l'utilizzo di componenti aggiuntivi COM.

Interfaccia IDTExtensibility2

L'ambiente di modifica di InfoPath supporta l'interfaccia IDTExtensibility2, che deve essere implementata dagli sviluppatori dei componenti aggiuntivi COM. IDTExtensibility2 è un oggetto con duplice interfaccia che fornisce cinque metodi che fungono da eventi all'interno dell'ambiente di modifica. Tali metodi consentono al componente aggiuntivo COM di rispondere alle condizioni di avvio e di arresto dell'ambiente, elencate nella tabella seguente.

Interfaccia	Descrizione
OnAddInsUpdate (ByVal custom() As Variant)	Si verifica quando un componente aggiuntivo viene caricato o scaricato nell'ambiente.
OnBeginShutdown (ByVal custom() As Variant)	Si verifica quando è in corso l'arresto dell'ambiente.
OnConnection(ByVal Application As Object, ByVal ConnectMode As ext_ConnectMode, ByVal AddInInst As Object, ByVal custom() As Variant)	Si verifica al caricamento di un componente aggiuntivo nell'ambiente.
OnDisconnection (ByVal RemoveMode As ext_DisconnectMode, ByVal custom() As Variant)	Si verifica allo scaricamento di un componente aggiuntivo dall'ambiente.
OnStartupComplete (ByVal custom() As Variant)	Si verifica al completamento dell'avvio dell'ambiente.

Registrazione dei componenti aggiuntivi COM

Tutte le applicazioni di Office, compreso InfoPath, utilizzano il Registro di sistema per elencare i componenti aggiuntivi nell'insieme Componenti aggiuntivi COM, archiviare lo stato di connessione e le informazioni sull'avvio o sul carico delle richieste. Il nome di ogni componente aggiuntivo COM di InfoPath è visualizzato nella chiave seguente:

HKEY_CURRENT_USER\Software\Microsoft\Office\InfoPath\AddIns\

Per i componenti aggiuntivi COM installati per essere utilizzati da tutti gli utenti del computer client, la chiave del Registro di sistema è situata nell'hive del Registro di sistema HKLM:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\InfoPath\AddIns\

Il nome della chiave del Registro di sistema corrisponde al ProgIdAttribute del componente aggiuntivo e contiene i valori seguenti.

Nome	Tipo	Descrizione
FriendlyName	String	Il nome visualizzato nella finestra di dialogo Componenti aggiuntivi COM ed elencato nella pagina Componenti aggiuntivi del Centro protezione.
Description	String	La stringa visualizzata quando si seleziona il componente aggiuntivo nel Centro protezione.
LoadBehavior	DWORD	Specifica il modo in cui il componente aggiuntivo COM viene caricato. Il valore può essere una combinazione di 0, 1, 2, 8 e 16. Per ulteriori informazioni, vedere la tabella seguente.

Il valore DWORD di LoadBehavior deve contenere un valore che descrive il modo in cui il componente aggiuntivo COM viene caricato nell'ambiente di modifica e può essere uno dei valori elencati nella tabella seguente oppure una combinazione di tali valori. Ad esempio, un componente aggiuntivo COM creato in Visual Studio 2005 avrà un LoadBehavior pari a "3" caricato all'avvio dell'applicazione e sarà connesso.

Valore	Descrizione
0	Disconnesso. Nella finestra di dialogo Componente aggiuntivo COM, lo stato del componente aggiuntivo è Inattivo.
1	Connesso. Nella finestra di dialogoComponente aggiuntivo COM, lo stato del componente aggiuntivo è Attivo.
2	Carica all'avvio. Il componente aggiuntivo viene caricato e connesso all'avvio dell'applicazione host.
8	Carica su richiesta. Il componente aggiuntivo viene caricato e connesso su richiesta dell'applicazione host, ad esempio quando si fa clic su un pulsante che utilizza la funzionalità del componente aggiuntivo.
16	Connetti la prima volta. Il componente aggiuntivo viene caricato e connesso la prima volta che l'utente esegue l'applicazione host dopo la registrazione del componente aggiuntivo.

Creazione di un componente aggiuntivo COM gestito in Visual Studio 2005

Per creare un componente aggiuntivo COM gestito mediante Microsoft Visual Studio 2005, creare un progetto Componente aggiuntivo condiviso di Visual Studio come descritto di seguito:

Fare clic su Start, scegliere Programmi, Microsoft Visual Studio 2005, quindi Microsoft Visual Studio 2005.
Scegliere Nuovo progetto dal menu File.
Nel riquadro Tipi di progetto della finestra di dialogo Nuovo progetto, scegliere Altri tipi di progetto, quindi fare clic su Extensibility.
Nel riquadro Modelli scegliere Componente aggiuntivo condiviso.
Nella casella Nome immettere un nome per il progetto Componente aggiuntivo condiviso.
Nella casella Percorso immettere il percorso di una cartella o fare clic su Sfoglia e selezionare il percorso di una cartella, quindi fare clic su OK. Verrà visualizzata la Creazione guidata componente aggiuntivo condiviso.
Nella Creazione guidata componente aggiuntivo condiviso fare clic su Avanti. Verrà visualizzata la pagina Selezionare un linguaggio di programmazione.
Scegliere Crea componente aggiuntivo utilizzando Visual Basic, quindi fare clic su Avanti. Verrà visualizzata la pagina Selezionare un'applicazione host.
Deselezionare le caselle accanto a ogni applicazione, ad eccezione di Microsoft InfoPath, quindi fare clic su Avanti. Verrà visualizzata la pagina Specificare un nome e una descrizione.
Nella casella Specificare il nome del componente aggiuntivo immettere il nome del componente aggiuntivo COM.
Nella casella Immettere la descrizione del componente aggiuntivo specificare la descrizione del componente aggiuntivo COM e fare clic su Avanti. Verrà visualizzata la pagina Scegliere le opzioni del componente aggiuntivo.
Selezionare le caselle Carica il componente aggiuntivo all'avvio dell'applicazione host e Rendi disponibile il componente aggiuntivo per tutti gli utenti del computer in cui è installato, non solo per l'utente che ha eseguito l'installazione.
Fare clic su Avanti per rivedere la pagina Riepilogo, quindi fare clic su Fine.

Dopo aver creato il progetto in Visual Studio, nella finestra Esplora soluzioni saranno visualizzati due progetti: il primo è il progetto per il componente aggiuntivo COM, mentre il secondo è un progetto di installazione per la distribuzione del componente aggiuntivo COM. La Creazione guidata componente aggiuntivo condiviso consente solo di inserire un riferimento alla libreria di oggetti di Microsoft Office 12.0. Pertanto, è necessario inserire un riferimento alla libreria di oggetti di InfoPath mediante i passaggi seguenti:

Fare doppio clic su Progetti per visualizzare le proprietà del progetto del componente aggiuntivo. Fare clic sulla scheda Riferimenti per visualizzare i riferimenti aggiunti automaticamente al progetto.
Fare clic sul pulsante Aggiungi per visualizzare la finestra di dialogo Aggiungi riferimento.
Nella scheda COM fare doppio clic su Libreria dei tipi di Microsoft.InfoPath 2.0, quindi scegliere OK.
Quando si aggiunge un riferimento alla Libreria dei tipi di Microsoft InfoPath 2.0 vengono aggiunti anche i riferimenti a tre assembly che è necessario rimuovere: ADODB, MSHTML e MSXML2. In Esplora soluzioni, in Riferimenti fare clic con il pulsante destro del mouse su ognuno di tali riferimenti, quindi scegliere Rimuovi.

Visualizzazione delle impostazioni del Registro di sistema

Per visualizzare le impostazioni del Registro di sistema che saranno create durante l'installazione del componente aggiuntivo COM, attenersi ai passaggi seguenti:

Fare clic con il pulsante destro del mouse sul nodo principale del progetto di installazione in Esplora soluzioni, scegliere Visualizza, Editor, quindi Registro di sistema.
Nel riquadro sinistro fare clic sul segno più per espandere HKEY_LOCAL_MACHINE, Software, Microsoft, InfoPath, quindi Componenti aggiuntivi.
Fare clic sul nome corrispondente al ProgID del progetto del componente aggiuntivo condiviso.

Per modificare una proprietà, fare clic con il pulsante destro del mouse sulla proprietà, scegliere Finestra Proprietà, quindi modificare la relativa casella Valore.

Compilazione e distribuzione del componente aggiuntivo condiviso

Per compilare il componente aggiuntivo COM gestito per testarlo sul computer sul quale è stato sviluppato il progetto Componente aggiuntivo condiviso, fare clic con il pulsante destro del mouse sul nodo principale del progetto in Esplora soluzioni e scegliere Genera. Se il progetto viene generato senza errori, è possibile avviare l'ambiente di modifica di InfoPath e iniziare a utilizzare il componente aggiuntivo COM gestito. Se è in esecuzione un'istanza di InfoPath, è necessario chiuderla prima di generare il progetto. Potrebbe inoltre essere necessario aprire la finestra di dialogo Componenti aggiuntivi COM per verificare che il componente aggiuntivo COM sia registrato. Per aprire la finestra di dialogo Componenti aggiuntivi COM, attenersi alle istruzioni seguenti:

Aprire l'ambiente di modifica di InfoPath. Il modo più facile per eseguire tale operazione è aprire un modello di modulo esistente, sulla cui base verrà creato un nuovo modulo.
Scegliere Centro protezione dal menu Strumenti.
Scegliere la categoria Componenti aggiuntivi a sinistra.
Nella sezione Gestisci accanto alla parte inferiore della finestra di dialogo Centro protezione selezionare Componenti aggiuntivi COM dall'elenco e fare clic sul pulsante Vai.
Nella finestra di dialogo Componenti aggiuntivi COM verrà visualizzato il nome del componente aggiuntivo appena generato con accanto una casella di controllo. Se la casella di controllo non è presente, il componente aggiuntivo COM non è stato caricato correttamente a causa di un errore, che sarà elencato nella sezione Caricamento della finestra di dialogo.

Per compilare il componente aggiuntivo COM gestito per l'utilizzo in un computer diverso da quello in cui è stato sviluppato il progetto Componente aggiuntivo condiviso, è necessario eseguire ulteriori passaggi per la protezione del codice. Per informazioni sulla protezione dei progetti Componente aggiuntivo condiviso da utilizzare su altri computer, vedere i tre articoli seguenti:

Distribuzione di componenti aggiuntivi COM gestiti in Office XP

Utilizzo della soluzione shim del componente aggiuntivo COM per la distribuzione di componenti aggiuntivi COM gestiti in Office XP

Isolamento delle estensioni di Office con la Creazione guidata shim COM

Importante:
Se non si isola il componente aggiuntivo COM, si potrebbero verificare perdite di memoria e l'applicazione potrebbe diventare instabile.

Nota:
Se gli assembly di .NET Framework o altri assembly necessari al progetto di installazione non sono già installati sui computer di destinazione, il file con estensione msi potrebbe non essere installato correttamente. Inoltre, non è possibile distribuire il file msi e tentare successivamente di installarlo poiché è necessario distribuire anche gli altri file di supporto nella stessa cartella in cui è posizionato il file msi originale generato da Visual Studio.

Se gli assembly di .NET Framework o altri assembly necessari al progetto di installazione non sono già installati sui computer di destinazione, il file con estensione msi potrebbe non essere installato correttamente. Inoltre, non è possibile distribuire il file msi e tentare successivamente di installarlo poiché è necessario distribuire anche gli altri file di supporto nella stessa cartella in cui è posizionato il file msi originale generato da Visual Studio.

Codifica nel componente aggiuntivo COM

Gli eventi dell'applicazione che si verificano nell'ambiente di modifica dei moduli di InfoPath possono essere acquisiti da un componente aggiuntivo COM. Il componente aggiuntivo COM può utilizzare gli eventi seguenti nell'oggetto ApplicationEvents per rispondere alle azioni dell'utente:

Evento	Descrizione
Evento NewXDocument	Si verifica alla creazione di un nuovo modulo.
Evento Quit	Si verifica alla chiusura di InfoPath.
Evento WindowActivate	Si verifica all'attivazione di una finestra del documento.
Evento WindowDeactivate	Si verifica alla disattivazione di una finestra del documento.
Evento WindowSize	Si verifica al ridimensionamento o spostamento di una finestra del documento.
Evento XDocumentBeforeClose	Si verifica immediatamente prima della chiusura di un documento aperto.
Evento XDocumentBeforePrint	Si verifica immediatamente prima della stampa di un documento aperto.
Evento XDocumentBeforeSave	Si verifica immediatamente prima del salvataggio di un documento aperto.
Evento XDocumentChange	Si verifica alla creazione di un nuovo modulo, quando viene aperto un modulo esistente o quando un altro modulo viene impostato come modulo attivo.
Evento XDocumentOpen	Si verifica all'apertura di un documento.

Per acquisire tali eventi nel componente aggiuntivo COM, è necessario dichiarare le seguenti variabili a livello di classe nella classe Connect:

InfoPathApplication = DirectCast( _
   application, Microsoft.Office.Interop.InfoPath._Application3)
InfoPathApplicationEvents = DirectCast( _
   InfoPathApplication.Events, _
   Microsoft.Office.Interop.InfoPath.ApplicationEvents)

La prima riga esegue il cast dell'Object dell'applicazione generica ricevuto dal componente aggiuntivo all'oggetto _Application3. La seconda riga esegue il cast della proprietà Events dell'oggetto _Application3 (rappresentato dalla variabile InfoPathApplication) all'oggetto ApplicationEvents.

Per creare gestori eventi, selezionare InfoPathApplicationEvents dall'elenco a discesa Nome classe nella parte superiore della finestra di Visual Studio, quindi selezionare l'evento da gestire nella casella a discesa Nome metodo nella parte superiore della finestra di Visual Studio. Ad esempio, se si desidera controllare quando viene salvato un modulo, gestire l'evento XDocumentBeforeSave. La selezione di XDocumentBeforeSave dall'elenco a discesa Nome metodo consente di inserire automaticamente la procedura seguente:

Private Sub InfoPathApplicationEvents_XDocumentBeforeSave( _
   ByVal pDocument As Microsoft.Office.Interop.InfoPath._XDocument, _
   ByRef pfCancel As Boolean) _
   Handles InfoPathApplicationEvents.XDocumentBeforeSave

End Sub

Qualsiasi evento dell'oggetto ApplicationEvents può essere gestito dal componente aggiuntivo COM utilizzando lo stesso metodo.

Vedere anche

Altre risorse

Creazione di un componente aggiuntivo COM di Microsoft Office 2000
Creazione di componenti aggiuntivi COM gestiti di Office in Visual Studio .NET
Utilizzo delle routine evento IDTExtensibility2
Procedura: Creare un componente aggiuntivo COM di Office in Visual Basic .NET
Procedura: Creare un componente aggiuntivo COM di Office in Visual C# .NET

Last updated on 2010-04-27