Cenni preliminari sugli elementi e sui controlli host

Articolo
08/11/2011

Gli elementi e i controlli host sono tipi che consentono di fornire il modello di programmazione per le soluzioni Office create tramite gli strumenti di sviluppo di Office in Visual Studio. Rendono l'interazione con i modelli a oggetti di Microsoft Office Word e Microsoft Office Excel, basati su COM, analoga all'interazione con gli oggetti gestiti, ad esempio i controlli Windows Form.

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

Elementi host

Gli elementi host sono tipi che si trovano nella parte superiore delle gerarchie del modello a oggetti nei progetti Office. In Runtime di Visual Studio Tools per Office vengono definiti gli elementi host seguenti per le soluzioni Word ed Excel:

Ciascuno di questi tipi consente di estendere un oggetto presente a livello nativo nel modello a oggetti di Word o Excel (definito oggetto Office nativo). Ad esempio, l'elemento host Microsoft.Office.Tools.Word.Document consente di estendere l'oggetto Microsoft.Office.Interop.Word.Document, definito nell'assembly di interoperabilità primario per Word.

Gli elementi host, generalmente, dispongono della stessa funzionalità di base degli oggetti Office corrispondenti, ma sono potenziati dalle funzionalità seguenti:

Possibilità di ospitare i controlli gestiti, inclusi i controlli host e quelli Windows Form.
Modelli di eventi più ricchi. Alcuni eventi relativi a documenti, cartelle di lavoro e fogli di lavoro nei modelli a oggetti nativi di Word e di Excel vengono generati solo a livello di applicazione. Gli elementi host forniscono questi eventi a livello di documento, in modo da rendere più facile la gestione di eventi per un documento specifico.

Informazioni sugli elementi host nei progetti a livello di documento

Nei progetti a livello di documento, gli elementi host forniscono un punto di ingresso per il codice e dispongono di finestre di progettazione che consentono di sviluppare la soluzione.

Gli elementi host Microsoft.Office.Tools.Word.Document e Microsoft.Office.Tools.Excel.Worksheet dispongono di finestre di progettazione associate che rappresentano visivamente il documento o il foglio di lavoro, in maniera analoga a quanto avviene per una finestra di progettazione di Windows Form. Questa finestra di progettazione può essere utilizzata per modificare il contenuto del documento o del foglio di lavoro direttamente in Word o Excel e per trascinare i controlli nell'area di progettazione. Per ulteriori informazioni, vedere Elemento host documento e Elemento host foglio di lavoro.

L'elemento host Microsoft.Office.Tools.Excel.Workbook non funge da contenitore per i controlli che dispongono di un'interfaccia utente. La finestra di progettazione per questo elemento host funge invece da barra dei componenti che consente il trascinamento di un componente, ad esempio DataSet, nell'area di progettazione. Per ulteriori informazioni, vedere Elemento host cartella di lavoro.

Non è possibile creare elementi host a livello di codice nei progetti a livello di documento. Al contrario, si possono utilizzare le classi ThisDocument, ThisWorkbook o Sheetn, generate automaticamente da Visual Studio nel progetto in fase di progettazione. Queste classi generate derivano dagli elementi host e forniscono un punto di ingresso per il codice. Per ulteriori informazioni, vedere Limitazioni a livello di codice degli elementi e dei controlli host.

Informazioni sugli elementi host nei progetti a livello di applicazione

Quando si crea un componente aggiuntivo a livello di applicazione, per impostazione predefinita non si dispone dell'accesso a qualsiasi elemento host. Tuttavia, è possibile generare gli elementi host Microsoft.Office.Tools.Word.Document, Microsoft.Office.Tools.Excel.Workbook e Microsoft.Office.Tools.Excel.Worksheet nei componenti aggiuntivi di Word e di Excel in fase di esecuzione.

Dopo aver generato un elemento host, è possibile eseguire attività quali l'aggiunta di controlli ai documenti e la creazione di smart tag riconosciuti in un documento specifico. Per ulteriori informazioni, vedere Estensione in fase di esecuzione di documenti di Word e di cartelle di lavoro di Excel in componenti aggiuntivi a livello di applicazione.

Nota

Gli smart tag sono deprecati in Excel 2010 e Word 2010. Per ulteriori informazioni, vedere Cenni preliminari sugli smart tag.

Controlli host

I controlli host consentono di estendere vari oggetti dell'interfaccia utente (UI) nel modello a oggetti di Word ed Excel, ad esempio gli oggetti Microsoft.Office.Interop.Word.ContentControl e Microsoft.Office.Interop.Excel.Range.

I controlli host seguenti sono disponibili per i progetti Excel:

I controlli host seguenti sono disponibili per i progetti Word:

I controlli host aggiunti ai documenti di Office si comportano come gli oggetti nativi di Office, ma dispongono di funzionalità aggiuntive che includono eventi e funzionalità di associazione dati. Ad esempio, per acquisire gli eventi di un oggetto Microsoft.Office.Interop.Excel.Range nativo in Excel, è necessario per prima cosa gestire l'evento di modifica del foglio di lavoro. Quindi, è necessario determinare se la modifica è avvenuta all'interno di Microsoft.Office.Interop.Excel.Range. Invece, il controllo host Microsoft.Office.Tools.Excel.NamedRange contiene un evento Change che è possibile gestire direttamente.

La relazione tra un elemento host e i controlli host è molto simile a quella esistente tra un Windows Form e i controlli Windows Form. Analogamente al posizionamento di un controllo casella di testo su un Windows Form, un controllo Microsoft.Office.Tools.Excel.NamedRange deve essere posizionato su un elemento host Microsoft.Office.Tools.Excel.Worksheet. Nell'illustrazione seguente è indicata la relazione tra elementi host e controlli host.

Relazione tra elementi e controlli host

È inoltre possibile utilizzare i controlli Windows Form nelle soluzioni Office aggiungendoli direttamente nell'area del documento di Word ed Excel. Per ulteriori informazioni, vedere Cenni preliminari sui controlli Windows Form nei documenti di Office.

Nota

L'aggiunta di controlli host o di controlli Windows Form a un documento secondario di Word non è supportata.

Aggiunta di controlli host ai documenti

Nei progetti a livello di documento è possibile aggiungere controlli host ai documenti di Word o ai fogli di lavoro di Excel in fase di progettazione nei modi seguenti:

Aggiungere i controlli host al documento in fase di progettazione in maniera analoga a quanto avviene per l'aggiunta di un oggetto nativo.
Trascinare i controlli host dalla Casella degli strumenti nei documenti e nei fogli di lavoro. I controlli host di Excel sono disponibili nella scheda Controlli Excel dei progetti Excel, mentre i controlli host di Word sono disponibili nella scheda Controlli Word dei progetti Word.
Trascinare i controlli host dalla finestra Origini dati nei documenti e nei fogli di lavoro. In questo modo è possibile aggiungere controlli già associati ai dati. Per ulteriori informazioni, vedere Associazione di dati ai controlli nelle soluzioni Office.

Nei progetti a livello di documento e in quelli a livello di applicazione, è inoltre possibile aggiungere alcuni controlli host ai documenti in fase di esecuzione. Per ulteriori informazioni, vedere Aggiunta di controlli ai documenti di Office in fase di esecuzione.

Per ulteriori informazioni sull'aggiunta dei controlli host ai documenti, vedere i seguenti argomenti:

Assegnazione di nomi ai controlli host

Quando si trascina un controllo host dalla Casella degli strumenti nel documento, al controllo verrà assegnato automaticamente un nome composto dal tipo del controllo e da un numero incrementale. I segnalibri saranno, ad esempio, denominati bookmark1 e bookmark2 e così via. Se si utilizza la funzionalità nativa di Word o Excel per aggiungere il controllo, è possibile assegnare un nome specifico al momento della creazione. È anche possibile rinominare i controlli modificando il valore della proprietà Name nella finestra Proprietà.

Nota

Nell'assegnazione di nomi ai controlli host non è possibile utilizzare parole riservate. Se ad esempio si aggiunge un controllo NamedRange a un foglio di lavoro e si cambia il nome in System, durante la compilazione del progetto si verificheranno errori.

Eliminazione di controlli host

Nei progetti a livello di documento, è possibile eliminare i controlli host in fase di progettazione selezionando il controllo nel foglio di lavoro di Excel o nel documento di Word e premendo il tasto CANC. Per eliminare i controlli NamedRange in Excel è tuttavia necessario utilizzare la finestra di dialogo Definisci nome. Per ulteriori informazioni, vedere How to: Delete NamedRange Controls at Design Time.

Se si aggiunge un controllo a un documento in fase di progettazione, non rimuoverlo a livello di codice in fase di esecuzione; al successivo tentativo di utilizzo del controllo nel codice, verrà generata un'eccezione. Il metodo Delete di un controllo host determina la rimozione dei soli controlli host aggiunti al documento in fase di esecuzione. Se si chiama il metodo Delete di un controllo host creato in fase di progettazione, viene generata un'eccezione.

Ad esempio, il metodo Delete di un oggetto NamedRange consente di eliminare correttamente solo l'oggetto NamedRange se è stato aggiunto a livello di codice al foglio di lavoro, ovvero l'operazione nota come creazione dei controlli host in modo dinamico. I controlli host creati dinamicamente possono essere rimossi anche passando il nome del controllo al metodo Remove della proprietà Worksheet.Controls o Document.Controls. Per ulteriori informazioni, vedere Aggiunta di controlli ai documenti di Office in fase di esecuzione.

Se un utente finale elimina un controllo host dal documento in fase di esecuzione, la soluzione potrebbe non riuscire. Per proteggere i controlli host dall'eliminazione è possibile utilizzare le funzionalità di protezione dei documenti. Per ulteriori informazioni, vedere Procedure dettagliate ed esempi di sviluppo di applicazioni per Microsoft Office.

Nota

Non rimuovere i controlli a livello di codice utilizzando il gestore eventi Shutdown del documento o del foglio di lavoro. Gli elementi dell'interfaccia utente non sono più disponibili quando si verifica l'evento Shutdown. Se si desidera rimuovere i controlli prima della chiusura dell'applicazione, aggiungere il codice a un altro gestore eventi come BeforeClose o BeforeSave.

Programmazione per gli eventi dei controlli host

Uno dei modi in cui i controlli host estendono gli oggetti Office è tramite l'aggiunta di eventi. Ad esempio, anche se l'oggetto Microsoft.Office.Interop.Excel.Range in Excel e l'oggetto Microsoft.Office.Interop.Word.Bookmark in Word non dispongono di eventi, Runtime di Visual Studio Tools per Office estende tali oggetti aggiungendo eventi programmabili. È possibile accedere a questi eventi e codificarli in maniera analoga a quanto avviene per l'accesso agli eventi dei controlli presenti in Windows Form, ovvero tramite l'elenco a discesa degli eventi di Visual Basic e la pagina delle proprietà degli eventi in C#. Per ulteriori informazioni, vedere Procedura dettagliata: programmazione per eventi di un controllo NamedRange.

Nota

In Microsoft Excel non impostare la proprietà EnableEvents dell'oggetto Application su false. L'impostazione di questa proprietà su false impedisce ad Excel di generare eventi, compresi quelli dei controlli host.