Architettura delle personalizzazioni a livello di documento

Articolo
08/11/2011

In Visual Studio 2010 sono inclusi progetti per la creazione di personalizzazioni a livello di documento per Microsoft Office Word e Microsoft Office Excel. In questo argomento vengono descritti gli aspetti seguenti delle personalizzazioni a livello di documento:

Informazioni sulle personalizzazioni
Componenti delle personalizzazioni
Funzionamento delle personalizzazioni con le applicazioni di Microsoft Office

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

Per informazioni generali sulla creazione di personalizzazioni a livello di documento, vedere Cenni preliminari sullo sviluppo di soluzioni Office, Guida introduttiva alla programmazione delle personalizzazioni a livello di documento per Word e Guida introduttiva alla programmazione di personalizzazioni a livello di documento per Excel.

Informazioni sulle personalizzazioni

Quando si utilizzano gli strumenti di sviluppo di Office in Visual Studio per compilare una personalizzazione a livello di documento, si crea un assembly di codice gestito associato a un documento specifico. Una cartella di lavoro o un documento dispone di estensioni di codice gestito quando include un assembly collegato. Per ulteriori informazioni, vedere la classe Cenni preliminari sugli assembly nelle soluzioni Office.

Quando un utente apre il documento, l'assembly viene caricato dall'applicazione di Microsoft Office. Dopo il caricamento dell'assembly, la personalizzazione può rispondere agli eventi mentre il documento è aperto. Può inoltre effettuare chiamate nel modello a oggetti per automatizzare ed estendere l'applicazione mentre il documento è aperto e può utilizzare qualsiasi classe di .NET Framework.

L'assembly comunica con i componenti COM dell'applicazione tramite l'assembly di interoperabilità primario dell'applicazione. Per ulteriori informazioni, vedere Assembly di interoperabilità primari di Office e Cenni preliminari sullo sviluppo di soluzioni Office.

Se un utente apre contemporaneamente più personalizzazioni a livello di documento, ogni assembly viene caricato in un dominio applicazione diverso. Questo significa che una soluzione che funziona in modo non corretto non può causare l'errato funzionamento delle altre soluzioni. Le personalizzazioni a livello di documento sono progettate per funzionare con un solo documento in un solo dominio di applicazione e non per la comunicazione tra documenti. Per ulteriori informazioni sui domini applicazione, vedere Domini applicazione.

Nota

Le personalizzazioni a livello di documento che si creano tramite gli strumenti di sviluppo di Office in Visual Studio sono progettate per essere utilizzate solo quando l'applicazione viene avviata da un utente finale. Se l'applicazione viene avviata a livello di codice (ad esempio, utilizzando l'automazione), la personalizzazione potrebbe non funzionare come previsto.

Informazioni sulle fasi di progettazione ed esecuzione

Per comprendere l'architettura delle personalizzazioni a livello di documento è utile conoscere le procedure di progettazione ed esecuzione di una soluzione.

Fase di progettazione

La procedura adottata nella fase di progettazione include i passaggi seguenti:

Lo sviluppatore crea un progetto a livello di documento in Visual Studio. Il progetto comprende il documento e l'assembly sottostante il documento. È possibile utilizzare un documento già esistente, ad esempio creato da un progettista, oppure un nuovo documento creato con il progetto.
Il progettista, che può corrispondere o meno allo sviluppatore che crea il progetto, definisce l'aspetto finale del documento per l'utente finale.

Fase di esecuzione

La procedura adottata nella fase di esecuzione include i passaggi seguenti:

L'utente finale apre un documento o una cartella di lavoro dotata di estensioni con codice gestito.
Il documento o la cartella di lavoro carica l'assembly compilato.
L'assembly risponde agli eventi mentre l'utente utilizza il documento o la cartella di lavoro.

Punto di vista dello sviluppatore e dell'utente finale

Poiché lo sviluppatore utilizza principalmente Visual Studio mentre l'utente finale utilizza Word o Excel, è possibile comprendere le personalizzazioni a livello di documento da due prospettive.

Punto di vista dello sviluppatore	Punto di vista dell'utente finale
Utilizzando Visual Studio lo sviluppatore scrive il codice accessibile da Word ed Excel. Sebbene venga apparentemente creato un file eseguibile in grado di eseguire Word o Excel, il processo presenta in realtà il funzionamento opposto. Il documento viene associato a un assembly e contiene un puntatore a tale assembly. All'apertura del documento, in Word o Excel viene individuato l'assembly e viene eseguito il codice in risposta a tutti gli eventi gestiti.	L'apertura del documento o della cartella di lavoro oppure la creazione di un nuovo documento da un modello viene eseguita dagli utenti della soluzione come per qualsiasi altro file di Microsoft Office. L'assembly fornisce personalizzazioni all'interno del documento o della cartella di lavoro, ad esempio la compilazione automatica con dati correnti o la visualizzazione di una finestra di dialogo in cui vengono richieste informazioni.

Utilizzando Visual Studio lo sviluppatore scrive il codice accessibile da Word ed Excel.

Sebbene venga apparentemente creato un file eseguibile in grado di eseguire Word o Excel, il processo presenta in realtà il funzionamento opposto. Il documento viene associato a un assembly e contiene un puntatore a tale assembly. All'apertura del documento, in Word o Excel viene individuato l'assembly e viene eseguito il codice in risposta a tutti gli eventi gestiti.

L'apertura del documento o della cartella di lavoro oppure la creazione di un nuovo documento da un modello viene eseguita dagli utenti della soluzione come per qualsiasi altro file di Microsoft Office.

L'assembly fornisce personalizzazioni all'interno del documento o della cartella di lavoro, ad esempio la compilazione automatica con dati correnti o la visualizzazione di una finestra di dialogo in cui vengono richieste informazioni.

Formati di documento supportati per le personalizzazioni a livello di documento

Quando si crea un progetto di personalizzazione, è possibile scegliere il formato di documento da utilizzare nel progetto. Per ulteriori informazioni, vedere la classe Procedura: creare progetti di Office in Visual Studio.

Nella tabella seguente sono elencati i formati di documento che è possibile utilizzare nelle personalizzazioni a livello di documento per Excel e Word.

Excel	Word
Cartella di lavoro di Excel (xlsx) Cartella di lavoro con attivazione macro di Excel (xlsm) Cartella di lavoro binaria di Excel (xlsb) Cartella di lavoro di Excel 97-2003 (xls) Modello di Excel (xltx) Modello con attivazione macro di Excel (xltm) Modello di Excel 97-2003 (xlt)	Documento di Word (docx) Documento di Word con attivazione macro (docm) Documento di Word 97-2003 (doc) Modello di Word (dotx) Modello di Word con attivazione macro (dotm) Modello di Word 97-2003 (dot)

Cartella di lavoro di Excel (xlsx)

Cartella di lavoro con attivazione macro di Excel (xlsm)

Cartella di lavoro binaria di Excel (xlsb)

Cartella di lavoro di Excel 97-2003 (xls)

Modello di Excel (xltx)

Modello con attivazione macro di Excel (xltm)

Modello di Excel 97-2003 (xlt)

Documento di Word (docx)

Documento di Word con attivazione macro (docm)

Documento di Word 97-2003 (doc)

Modello di Word (dotx)

Modello di Word con attivazione macro (dotm)

Modello di Word 97-2003 (dot)

Si consiglia di progettare le estensioni di codice gestito solo per documenti nei formati supportati. In caso contrario, alcuni eventi potrebbero non essere generati all'apertura del documento nell'applicazione. L'evento Open, ad esempio, non viene generato quando si utilizzano le estensioni di codice gestito con cartelle di lavoro salvate nel formato Foglio di calcolo XML di Excel o nel formato Pagina Web (htm, html).

Supporto per i documenti di Word con l'estensione di file xml

I modelli di progetto a livello di documento non consentono di creare progetti basati sui formati di file seguenti:

Documento XML di Word (*.xml)
Documento XML di Word 2003 (*.xml)

Se si desidera che gli utenti finali utilizzino le personalizzazioni in questi formati di file, compilare e distribuire una personalizzazione che utilizzi uno dei formati di file supportati specificati nella tabella precedente. Dopo avere installato la personalizzazione, gli utenti finali possono salvare il documento nel formato Documento XML di Word (*.xml) o nel formato Documento XML di Word 2003 (*.xml). La personalizzazione continuerà a funzionare come previsto.

Componenti delle personalizzazioni

I componenti principali di una personalizzazione sono il documento e l'assembly. Oltre a questi componenti esistono alcune altre parti che svolgono un ruolo importante nel modo in cui le applicazioni di Microsoft Office individuano e caricano le personalizzazioni.

Manifesto di distribuzione e manifesto dell'applicazione

Le personalizzazioni utilizzano i manifesti di distribuzione e dell'applicazione per identificare e caricare la versione più recente dell'assembly di personalizzazione. Il manifesto di distribuzione fa riferimento al manifesto dell'applicazione corrente, mentre il manifesto dell'applicazione fa riferimento all'assembly di personalizzazione e specifica la classe o le classi del punto di ingresso da eseguire nell'assembly. Per ulteriori informazioni, vedere Manifesti dell'applicazione e di distribuzione nelle soluzioni di Office.

Runtime di Visual Studio Tools per Office

Per eseguire le personalizzazioni a livello di documento che si creano tramite gli strumenti di sviluppo di Office in Visual Studio, nei computer degli utenti finali deve essere installato il Runtime di Visual Studio Tools per Office. Il Runtime di Visual Studio Tools per Office include componenti non gestiti che caricano l'assembly di personalizzazione e un set di assembly gestiti. Questi assembly gestiti forniscono il modello a oggetti che il codice della personalizzazione utilizza per automatizzare ed estendere l'applicazione host.

Per ulteriori informazioni, vedere Cenni preliminari su Visual Studio Tools per Office Runtime.

Funzionamento delle personalizzazioni con le applicazioni di Microsoft Office

Quando un utente apre un documento facente parte di una personalizzazione per Microsoft Office, l'applicazione utilizza il manifesto di distribuzione collegato al documento per trovare e caricare la versione più recente dell'assembly di personalizzazione. La posizione del manifesto di distribuzione è memorizzata in una proprietà di documento personalizzata detta _AssemblyLocation. La stringa che identifica questo percorso viene inserita nella proprietà quando si compila la soluzione.

Il manifesto di distribuzione punta al manifesto dell'applicazione, che a propria volta punta all'assembly più recente. Per ulteriori informazioni, vedere Manifesti dell'applicazione e di distribuzione nelle soluzioni di Office.

Nell'illustrazione seguente viene mostrata l'architettura di base di una personalizzazione a livello di documento.

Architettura della personalizzazione

Architettura di personalizzazione di Office 2007

Nota

Nelle soluzioni Office destinate a .NET Framework 4, le soluzioni effettuano chiamate nel modello a oggetti dell'applicazione host tramite le informazioni sul tipo di assembly di interoperabilità primario incorporate nell'assembly della soluzione, anziché chiamare direttamente l'assembly di interoperabilità primario. Per ulteriori informazioni, vedere Progettazione e creazione di soluzioni Office.

Processo di caricamento

Viene eseguita la procedura seguente quando un utente apre un documento facente parte di una soluzione Microsoft Office:

L'applicazione di Microsoft Office controlla le proprietà personalizzate del documento per verificare se vi siano estensioni di codice gestito associate al documento. Per ulteriori informazioni, vedere Cenni preliminari sulle proprietà personalizzate dei documenti.
Se esistono estensioni di codice gestito, l'applicazione carica VSTOEE.dll, che a propria volta carica VSTOLoader.dll. Si tratta di DLL non gestite che costituiscono i componenti del caricatore per Visual Studio 2010 Tools per Office Runtime. Per ulteriori informazioni, vedere Cenni preliminari su Visual Studio Tools per Office Runtime.
VSTOLoader.dll carica .NET Framework e avvia la parte gestita del Runtime di Visual Studio Tools per Office.
Se il documento viene aperto da un percorso diverso dal computer locale, il Runtime di Visual Studio Tools per Office verifica che il percorso del documento sia nell'elenco Percorsi attendibili in Impostazioni Centro sicurezza per la specifica applicazione di Office. Se il percorso del documento non è attendibile, la personalizzazione non è considerata attendibile e il processo di caricamento si arresta.
Il Runtime di Visual Studio Tools per Office installa la soluzione se ancora non è stata installata, scarica i manifesti dell'applicazione e di distribuzione più recenti ed esegue una serie di controlli di sicurezza. Per ulteriori informazioni, vedere Sicurezza delle soluzioni Office.
Se la personalizzazione viene considerata attendibile per l'esecuzione, il Runtime di Visual Studio Tools per Office utilizza i manifesti di distribuzione e dell'applicazione per verificare la disponibilità di aggiornamenti dell'assembly. Se è disponibile una versione nuova dell'assembly, il runtime la scarica nella cache ClickOnce sul computer client. Per ulteriori informazioni, vedere Distribuzione di soluzioni Office.
Il Runtime di Visual Studio Tools per Office crea un nuovo dominio applicazione nel quale caricare l'assembly di personalizzazione.
Il Runtime di Visual Studio Tools per Office carica l'assembly di personalizzazione nel dominio applicazione.
Il Runtime di Visual Studio Tools per Office chiama il gestore eventi Startup nell'assembly di personalizzazione. Per ulteriori informazioni, vedere Eventi nei progetti di Office.