Architettura delle personalizzazioni a livello di documento

  • Articolo

Visual Studio 2013 include progetti per la creazione di personalizzazioni a livello di documento per Microsoft Office Word e Microsoft Office Excel. Questo argomento descrive gli aspetti seguenti delle personalizzazioni a livello di documento:

Informazioni sulle personalizzazioni

Quando si usano gli strumenti di sviluppo per Office in Visual Studio per aggiungere una personalizzazione a livello di documento, si crea un assembly di codice gestito associato a un determinato documento. Una cartella di lavoro o un documento dispone di estensioni di codice gestito quando include un assembly collegato. Per altre informazioni, vedere Progettare e creare 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. La personalizzazione può anche chiamare nel modello a oggetti per automatizzare ed estendere l'applicazione mentre il documento è aperto e può usare qualsiasi classe in .NET Framework.

L'assembly comunica con i componenti COM dell'applicazione tramite l'assembly di interoperabilità primario dell'applicazione. Per altre informazioni, vedere Assembly di interoperabilità primari di Office e Panoramica dello sviluppo di soluzioni Office (VSTO).

Se un utente apre contemporaneamente più personalizzazioni a livello di documento, ogni assembly viene caricato in un dominio dell'applicazione diverso. Questo significa che una soluzione che si comporta 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 altre informazioni sui domini applicazione, vedere Domini applicazione.

Nota

Le personalizzazioni a livello di documento create mediante gli strumenti di sviluppo per Office disponibili in Visual Studio sono progettate per essere usate solo quando l'applicazione viene avviata da un utente finale. Se l'applicazione viene avviata a livello di codice, ad esempio usando l'automazione, il componente aggiuntivo potrebbe non funzionare nel modo previsto.

Esperienze in fase di progettazione e di runtime

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

In fase di progettazione

L'esperienza in fase di progettazione include i passaggi seguenti:

  1. Lo sviluppatore crea un progetto a livello di documento in Visual Studio. Il progetto include il documento e l'assembly sottostante il documento. Il documento potrebbe esistere già (creato da una finestra di progettazione) oppure è possibile creare un nuovo documento insieme al progetto.

  2. Il progettista (lo sviluppatore che crea il progetto o un'altra persona) determina quale aspetto avrà il documento per l'utente finale.

esecuzione

L'esperienza in fase di esecuzione include i passaggi seguenti:

  1. L'utente finale apre un documento o una cartella di lavoro dotata di estensioni con codice gestito.

  2. Il documento o la cartella di lavoro carica l'assembly compilato.

  3. L'assembly risponde agli eventi mentre l'utente usa il documento o la cartella di lavoro.

Prospettiva dello sviluppatore e dell'utente finale confrontata

Poiché lo sviluppatore funziona principalmente in Visual Studio e l'utente finale funziona in Word o Excel, esistono due modi per comprendere le personalizzazioni a livello di documento.

Punto di vista dello sviluppatore Punto di vista dell'utente finale
Usando Visual Studio, lo sviluppatore scrive codice accessibile a 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, Word o Excel individua l'assembly ed esegue il codice in risposta a tutti gli eventi gestiti.		 Chi usa la soluzione, apre semplicemente il documento o la cartella di lavoro oppure crea un nuovo documento da un modello, come per qualsiasi altro file di Microsoft Office.

L'assembly fornisce le personalizzazioni all'interno del documento o della cartella di lavoro, ad esempio popolandolo automaticamente con dati correnti o visualizzando 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 usare nel progetto. Per altre informazioni, vedere Procedura: Creare progetti di Office in Visual Studio.

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

Excel Word
Cartella di lavoro di Excel (con estensione xlsx)

Cartella di lavoro abilitata per le macro di Excel (con estensione xlsm)

Cartella di lavoro binaria di Excel (con estensione xlsb)

Cartella di lavoro di Excel 97-2003 (xls)

Modello di Excel (.xltx)

Modello con attivazione macro di Excel (con estensione xltm)

Modello di Excel 97-2003 (con estensione xlt)		 Documento di Word (.docx)

Documento con attivazione macro di Word (.docm)

Documento di Word 97-2003 (.doc)

Modello di Word (.dotx)

Modello con attivazione macro di Word (con estensione dotm)

Modello di Word 97-2003 (punto)

Si consiglia di progettare le estensioni di codice gestito solo per documenti nei formati supportati. In caso contrario, è possibile che alcuni eventi non vengano generati all'apertura del documento nell'applicazione. Ad esempio, l'evento Open non viene generato quando si utilizzano estensioni di codice gestito con cartelle di lavoro salvate nel formato foglio di calcolo XML di Excel o nella pagina Web (.htm; . formato html).

Supporto per i documenti di Word con estensioni 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 vuole che gli utenti finali usino le personalizzazioni in questi formati di file, compilare e distribuire una personalizzazione che usi uno dei formati di file supportati specificati nella tabella precedente. Dopo aver 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) e 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, anche alcune altre parti svolgono un ruolo importante nel modo in cui le applicazioni di Microsoft Office individuano e caricano le personalizzazioni.

Manifesto della distribuzione e manifesto dell'applicazione

Le personalizzazioni usano i manifesti della distribuzione e dell'applicazione per identificare e caricare la versione più recente dell'assembly di personalizzazione. Il manifesto della distribuzione fa riferimento al manifesto dell'applicazione corrente. 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 altre informazioni, vedere Manifesti dell'applicazione e della distribuzione nelle soluzioni Office.

Runtime di Visual Studio Tools per Office

Per eseguire personalizzazioni a livello di documento create usando gli strumenti di sviluppo di Office in Visual Studio, i computer degli utenti finali devono avere installato il Strumenti di Visual Studio per il runtime di Office. Il Strumenti di Visual Studio per il runtime di Office include componenti non gestiti che caricano l'assembly di personalizzazione e anche un set di assembly gestiti. Questi assembly gestiti forniscono il modello a oggetti usato dal codice della personalizzazione per automatizzare ed estendere l'applicazione host.

Per altre informazioni, vedere Panoramica degli strumenti di Visual Studio per il runtime di Office.

Funzionamento delle personalizzazioni con le applicazioni di Microsoft Office

Quando un utente apre un documento che fa parte di una personalizzazione per Microsoft Office, l'applicazione usa il manifesto della distribuzione collegato al documento per trovare e caricare la versione più recente dell'assembly di personalizzazione. Il percorso del manifesto di distribuzione viene archiviato in una proprietà del documento personalizzata denominata AssemblyLocation. La stringa che identifica questo percorso viene inserita nella proprietà quando si compila la soluzione.

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

La figura seguente mostra l'architettura di base di una personalizzazione a livello di documento.

2007 Office customization architecture

Nota

Nelle soluzioni Office destinate a .NET Framework 4, le soluzioni chiamano nel modello a oggetti dell'applicazione host usando informazioni sul tipo di assembly di interoperabilità primario (PIA) incorporate nell'assembly della soluzione, anziché chiamare direttamente nell'assembly di interoperabilità primario. Per altre informazioni, vedere Progettare e creare soluzioni Office.

Processo di caricamento

I passaggi seguenti si verificano quando un utente apre un documento che fa parte di una soluzione Microsoft Office.

  1. L'applicazione di Microsoft Office controlla le proprietà personalizzate per verificare se sono presenti estensioni di codice gestito associate al documento. Per altre informazioni, vedere Panoramica delle proprietà personalizzate dei documenti.

  2. Se sono presenti estensioni di codice gestito, l'applicazione carica VSTO edizione Enterprise.dll, che carica VSTOLoader.dll. Si tratta di DLL non gestite che sono i componenti del caricatore per il runtime di Visual Studio 2010 Tools per Office. Per altre informazioni, vedere Strumenti di Visual Studio per la panoramica del runtime di Office.

  3. VSTOLoader.dll carica .NET Framework e avvia la parte gestita del Strumenti di Visual Studio per il runtime di Office.

  4. Se il documento viene aperto da un percorso diverso dal computer locale, il Strumenti di Visual Studio per il runtime di Office verifica che il percorso del documento si trova nell'elenco Percorsi attendibili nel Centro protezione Impostazioni per quel particolare app Office lication. Se il percorso del documento non è attendibile, la personalizzazione non è considerata attendibile e il processo di caricamento si arresta.

  5. Il Strumenti di Visual Studio per il runtime di Office installa la soluzione se non è ancora stata installata, scarica i manifesti dell'applicazione e della distribuzione più recenti ed esegue una serie di controlli di sicurezza. Per altre informazioni, vedere Proteggere le soluzioni Office.

  6. Se la personalizzazione è attendibile per l'esecuzione, il runtime di Strumenti di Visual Studio per Office usa il manifesto della distribuzione e il manifesto dell'applicazione per verificare la presenza di aggiornamenti dell'assembly. Se è disponibile una nuova versione dell'assembly, il runtime scarica la nuova versione dell'assembly nella cache ClickOnce nel computer client. Per altre informazioni, vedere Distribuire una soluzione Office.

  7. Il Strumenti di Visual Studio per il runtime di Office crea un nuovo dominio applicazione in cui caricare l'assembly di personalizzazione.

  8. Il Strumenti di Visual Studio per il runtime di Office carica l'assembly di personalizzazione nel dominio dell'applicazione.

  9. Il Strumenti di Visual Studio per il runtime di Office chiama il gestore eventi di avvio nell'assembly di personalizzazione. Per altre informazioni, vedere Eventi nei progetti di Office.

Contenuto correlato