Procedura dettagliata: distribuzione di una personalizzazione a livello di documento tramite un file di Windows Installer (System 2003)

Articolo
04/28/2010

Aggiornamento: novembre 2007

Si applica a
Le informazioni contenute in questo argomento riguardano solo i progetti Visual Studio Tools per Office e le versioni di Microsoft Office specificati. Tipo di progetto Progetti a livello di documento Versione Microsoft Office Microsoft Office 2003 Per ulteriori informazioni, vedere la classe Funzionalità disponibili in base ai tipi di progetto e applicazione.

Le informazioni contenute in questo argomento riguardano solo i progetti Visual Studio Tools per Office e le versioni di Microsoft Office specificati.

Tipo di progetto

Progetti a livello di documento

Versione Microsoft Office

Microsoft Office 2003

Per ulteriori informazioni, vedere la classe Funzionalità disponibili in base ai tipi di progetto e applicazione.

In questa procedura dettagliata viene illustrato come creare un file di Microsoft Windows Installer (con estensione msi) da utilizzare per distribuire una personalizzazione a livello di documento. Per ulteriori informazioni sulle personalizzazioni a livello di documento, vedere Architettura delle personalizzazioni a livello di documento.

In questa procedura dettagliata vengono illustrate le attività seguenti:

Creazione di un progetto di installazione da utilizzare per compilare un file di Windows Installer.
Modifica del progetto di installazione in modo che il file di Windows Installer installi la soluzione Visual Studio Tools per Office.
Aggiunta di un passaggio al progetto di installazione in modo che il file di Windows Installer modifichi il manifesto dell'applicazione incorporato nel documento della soluzione Visual Studio Tools per Office.

In questa procedura dettagliata si presuppone che nel computer di destinazione siano già installati i prerequisiti per l'esecuzione di soluzioni Visual Studio Tools per Office. Il file di Windows Installer compilato non verifica la presenza di tali componenti necessari, né provvede a installarli. Per informazioni sull'installazione dei prerequisiti, vedere Deploying Visual Studio 2005 Tools for Office Second Edition Solutions Using Windows Installer. Per informazioni sui prerequisiti necessari per l'esecuzione di soluzioni Visual Studio Tools per Office, vedere Procedura: preparare il computer degli utenti finali per l'esecuzione delle soluzioni Office (System 2003).

Nota:
Agli assembly delle soluzioni Visual Studio Tools per Office deve essere concessa l'attendibilità totale nei criteri di sicurezza dell'utente finale prima dell'esecuzione della soluzione. Il file di Windows Installer che viene compilato in questa procedura dettagliata non distribuisce i criteri di sicurezza necessari per eseguire la soluzione. Per informazioni su come aggiungere un'azione personalizzata per concedere l'attendibilità all'assembly di personalizzazione, vedere Deploying Visual Studio 2005 Tools for Office Second Edition Solutions Using Windows Installer (informazioni in lingua inglese). Per informazioni sulla sicurezza nelle soluzioni Visual Studio Tools per Office, vedere Requisiti di sicurezza per l'esecuzione delle soluzioni Office (System 2003) e Procedura consigliata per la sicurezza nelle soluzioni Office (System 2003). Per informazioni sull'impostazione di criteri di sicurezza nei computer degli utenti finali, vedere Distribuzione dei criteri di sicurezza.

Agli assembly delle soluzioni Visual Studio Tools per Office deve essere concessa l'attendibilità totale nei criteri di sicurezza dell'utente finale prima dell'esecuzione della soluzione. Il file di Windows Installer che viene compilato in questa procedura dettagliata non distribuisce i criteri di sicurezza necessari per eseguire la soluzione. Per informazioni su come aggiungere un'azione personalizzata per concedere l'attendibilità all'assembly di personalizzazione, vedere Deploying Visual Studio 2005 Tools for Office Second Edition Solutions Using Windows Installer (informazioni in lingua inglese). Per informazioni sulla sicurezza nelle soluzioni Visual Studio Tools per Office, vedere Requisiti di sicurezza per l'esecuzione delle soluzioni Office (System 2003) e Procedura consigliata per la sicurezza nelle soluzioni Office (System 2003). Per informazioni sull'impostazione di criteri di sicurezza nei computer degli utenti finali, vedere Distribuzione dei criteri di sicurezza.

Prerequisiti

Per completare questa procedura dettagliata, è necessario disporre dei seguenti componenti:

Visual Studio Tools per Office (componente facoltativo di Visual Studio 2008 Professional e Visual Studio Team System).
Microsoft Office Word 2003 o Microsoft Office Excel 2003.

Creazione del progetto

In questo passaggio, creare un progetto Cartella di lavoro di Excel. Se si desidera eseguire la procedura dettagliata con una soluzione Word o Excel esistente, partire dal titolo "Creazione di un progetto di installazione" e sostituire in tutti gli esempi di codice e in tutte le istruzioni il nome del progetto ExcelDeployment con il nome del progetto utilizzato.

Per creare un nuovo progetto

Creare un progetto Cartella di lavoro di Excel con il nome ExcelDeployment, utilizzando il modello di progetto per Office 2003.

Nella procedura guidata, scegliere Crea un nuovo documento. Per ulteriori informazioni, vedere la classe Procedura: creare progetti Visual Studio Tools per Office.

La nuova cartella di lavoro di Excel verrà aperta nella finestra di progettazione di Visual Studio e il progetto ExcelDeployment verrà aggiunto a Esplora soluzioni.

Aggiunta del codice su cui si basa la cartella di lavoro

Il progetto richiede del codice in modo da verificare che la soluzione funzioni correttamente all'apertura del documento. Per questa procedura dettagliata, aggiungere una finestra di messaggio al gestore eventi Startup della cartella di lavoro.

Per aggiungere una finestra di messaggio a un evento di inizializzazione

In Esplora soluzioni fare clic con il pulsante destro del mouse su ThisWorkbook.vb o ThisWorkbook.cs, quindi scegliere Visualizza codice dal menu di scelta rapida.

Aggiungere il codice riportato di seguito al gestore eventi Startup all'interno della classe ThisWorkbook per visualizzare una finestra di messaggio durante l'inizializzazione.

Private Sub ThisWorkbook_Startup(ByVal sender As Object, ByVal e As System.EventArgs) _
    Handles Me.Startup

    MessageBox.Show("The workbook is deployed successfully.")
End Sub

private void ThisWorkbook_Startup(object sender, System.EventArgs e)
{
    MessageBox.Show("The workbook is deployed successfully.");
}

Premere F5 per eseguire il progetto.

Verrà visualizzata la finestra di messaggio all'avvio di Excel.
Chiudere la finestra di messaggio.
Uscire da Excel.

Creazione di un progetto di installazione

I progetti di installazione forniscono file e codice che è possibile compilare per creare un file di Windows Installer per la soluzione. Per ulteriori informazioni, vedere la classe Progetti di installazione.

Per creare un progetto di installazione per la soluzione

Fare clic con il pulsante destro del mouse sul nodo della soluzione in Esplora soluzioni.
Scegliere Aggiungi dal menu di scelta rapida, quindi Nuovo progetto.

Verrà visualizzata la finestra di dialogo Aggiungi nuovo progetto.
Nel riquadro Tipi progetto espandere Altri tipi di progetto, quindi selezionare Installazione e distribuzione.
Nel riquadro Modelli selezionare Progetto di installazione.
Specificare ExcelSetup come nome del progetto.
Scegliere OK.

Il progetto di installazione verrà visualizzato in Esplora soluzioni. Per impostazione predefinita, il file di Windows Installer che verrà compilato utilizzando il progetto di installazione include una finestra di dialogo che consente all'utente finale di specificare il percorso di installazione della soluzione. Per ulteriori informazioni, vedere Finestra di dialogo dell'interfaccia utente Cartella di installazione.

Aggiunta della cartella di lavoro e dell'assembly della soluzione al progetto di installazione

L'output primario del progetto ExcelDeployment è costituito dalla cartella di lavoro e dall'assembly della soluzione. Aggiungere questi componenti al progetto di installazione.

Per aggiungere il documento e l'assembly al progetto di installazione

Fare clic con il pulsante destro del mouse sul nodo del progetto ExcelSetup in Esplora soluzioni.
Scegliere Visualizza dal menu di scelta rapida, quindi File System.
Fare clic con il pulsante destro del mouse su Cartella Applicazione nel riquadro di sinistra.
Scegliere Aggiungi dal menu di scelta rapida, quindi Output progetto.
Selezionare ExcelDeployment nella casella Progetto.
Selezionare Output primario nell'elenco dei tipi di output.
Scegliere OK.

L'output del progetto e le dipendenze verranno visualizzati nel riquadro di destra.
In Esplora soluzioni espandere Dipendenze rilevate nel nodo del progetto ExcelSetup.
Fare clic con il pulsante destro del mouse su tutte le dipendenze tranne quella relativa a Microsoft .NET Framework, quindi scegliere Escludi dal menu di scelta rapida.

Creazione di un progetto di azioni personalizzate

Le azioni personalizzate sono una funzionalità di Windows Installer È possibile utilizzarle per eseguire codice alla fine del processo di installazione in modo da effettuare operazioni che non possono essere eseguite durante l'installazione. Per ulteriori informazioni, vedere Azioni personalizzate.

Per creare un progetto di azioni personalizzate

Fare clic con il pulsante destro del mouse sul nodo della soluzione in Esplora soluzioni.
Scegliere Aggiungi dal menu di scelta rapida, quindi Nuovo progetto.

Verrà visualizzata la finestra di dialogo Aggiungi nuovo progetto.
Nel riquadro Tipi progetto espandere il nodo relativo al linguaggio di programmazione in uso, quindi selezionare Windows.
Nel riquadro Modelli selezionare Libreria di classi.
Specificare ExcelCustomAction come nome del progetto.
Scegliere OK.

Il nuovo progetto verrà visualizzato in Esplora soluzioni.
In Esplora soluzioni fare clic con il pulsante destro del mouse su Class1.vb o Class1.cs nel progetto ExcelCustomAction, quindi scegliere Elimina. Questo file non è necessario per la procedura dettagliata.

Creazione di un'azione personalizzata per la modifica del manifesto dell'applicazione

Quando si è eseguito il progetto premendo F5 in una fase precedente della procedura dettagliata, il manifesto dell'applicazione incorporato nella cartella di lavoro è stato modificato dal processo di compilazione in modo da puntare al percorso relativo dell'assembly. Se la cartella di lavoro e l'assembly rimangono nella stessa cartella dopo l'installazione, non è necessario modificare il manifesto dell'applicazione incorporato ed è possibile ignorare questa sezione. Tuttavia, se si desidera consentire all'utente di spostare la cartella di lavoro in una cartella differente dopo l'installazione della soluzione, è necessario modificare il manifesto dell'applicazione in modo che punti al percorso completo dell'assembly.

Il manifesto dell'applicazione incorporato nel documento della soluzione Visual Studio Tools per Office deve essere aggiornato mediante un'azione personalizzata da eseguire dopo il processo di installazione, poiché il percorso dell'assembly della soluzione resta sconosciuto finché l'utente non specifica il percorso durante l'installazione. Per modificare il manifesto dell'applicazione incorporato, utilizzare la classe ServerDocument. Per utilizzare la classe ServerDocument nel progetto di installazione, aggiungere codice a una classe Installer all'interno del progetto di azioni personalizzate.

Per creare un'azione personalizzata per la modifica del manifesto dell'applicazione

Fare clic con il pulsante destro del mouse sul progetto ExcelCustomAction in Esplora soluzioni.
Scegliere Aggiungi dal menu di scelta rapida, quindi Nuovo elemento.

Verrà visualizzata la finestra di dialogo Aggiungi nuovo elemento.
Selezionare Classe Installer, quindi specificare ManifestEditor come nome della classe.
Aggiungere un riferimento all'assembly Microsoft.VisualStudio.Tools.Applications.Runtime nel progetto ExcelCustomAction.
In Esplora soluzioni fare clic con il pulsante destro del mouse sul file ManifestEditor.cs o ManifestEditor.vb, quindi scegliere Visualizza codice.

Aggiungere l'istruzione Imports o using seguente all'inizio del file di codice.

Imports Microsoft.VisualStudio.Tools.Applications.Runtime

using Microsoft.VisualStudio.Tools.Applications.Runtime;

Copiare il codice riportato di seguito nella classe ManifestEditor.

Questo codice esegue l'override del metodo Install, che viene utilizzato per eseguire azioni di installazione personalizzate. Il codice imposta il percorso di installazione specificato dall'utente sulla proprietà AssemblyPath. Il percorso di installazione specificato dall'utente e i nomi del documento e dell'assembly vengono ottenuti a partire dalla proprietà Parameters.

Public Overrides Sub Install(ByVal stateSaver As System.Collections.IDictionary)
    UpdateApplicationManifest()
    MyBase.Install(stateSaver)
End Sub

Private Sub UpdateApplicationManifest()

    ' Get the parameters passed to the task.
    Dim targetDir As String = Me.Context.Parameters("targetdir")
    Dim documentName As String = Me.Context.Parameters("documentname")
    Dim assemblyName As String = Me.Context.Parameters("assemblyname")

    ' Get the application manifest from the document.
    Dim documentPath As String = System.IO.Path.Combine(targetDir, documentname)
    Dim serverDocument1 As ServerDocument = New ServerDocument(documentPath, _
            System.IO.FileAccess.ReadWrite)

    Try
        Dim appManifest1 As AppManifest = serverDocument1.AppManifest
        Dim assemblyPath As String = System.IO.Path.Combine(targetDir, assemblyName)
        appManifest1.Dependency.AssemblyPath = assemblyPath
        serverDocument1.Save()

    Finally
        If Not serverDocument1 Is Nothing Then
            serverDocument1.Close()
        End If
    End Try
End Sub

// Override the Install method to update the customization location
// in the application manifest.
public override void Install(System.Collections.IDictionary stateSaver)
{
    UpdateApplicationManifest();
    base.Install(stateSaver);
}

// Update the application manifest according to the the install location.
private void UpdateApplicationManifest()
{
    // Get the parameters passed to the task.
    string targetDir = this.Context.Parameters["targetdir"];
    string documentName = this.Context.Parameters["documentname"];
    string assemblyName = this.Context.Parameters["assemblyname"];

    // Get the application manifest from the document.
    string documentPath = System.IO.Path.Combine(targetDir, documentName);
    ServerDocument serverDocument1 = new ServerDocument(documentPath,
        System.IO.FileAccess.ReadWrite);

    try
    {
        AppManifest appManifest1 = serverDocument1.AppManifest;
        string assemblyPath = System.IO.Path.Combine(targetDir, assemblyName);
        appManifest1.Dependency.AssemblyPath = assemblyPath;
        serverDocument1.Save();
    }
    finally
    {
        if (serverDocument1 != null)
        {
            serverDocument1.Close();
        }
    }
}

Fare clic con il pulsante destro del mouse sul progetto ExcelCustomAction in Esplora soluzioni, quindi scegliere Compila.

Aggiunta di un'azione personalizzata al progetto di installazione

Ora è possibile attivare il file di Windows Installer affinché esegua l'azione personalizzata che modifica il manifesto dell'applicazione. Per eseguire questa operazione, aggiungere l'output primario del progetto ExcelCustomAction al progetto di installazione.

Per aggiungere l'output primario del progetto di azioni personalizzate al progetto di installazione

Fare clic con il pulsante destro del mouse sul nodo del progetto ExcelSetup in Esplora soluzioni.
Scegliere Visualizza dal menu di scelta rapida, quindi Azioni personalizzate.
Nell'Editor delle azioni personalizzate fare clic con il pulsante destro del mouse sul nodo Installa, quindi scegliere Aggiungi azione personalizzata.
Nella casella Cerca in selezionare Cartella Applicazione, quindi fare clic su Aggiungi output.
Selezionare ExcelCustomAction nella casella Progetto.
Selezionare Output primario nell'elenco dei tipi di output, quindi scegliere OK.
Verificare che Output primario da ExcelCustomAction (Attivo) sia stato aggiunto all'elenco degli output primari del progetto di installazione, quindi scegliere OK.
Nell'Editor delle azioni personalizzate espandere Installa.
Fare clic con il pulsante destro del mouse su Output primario da ExcelCustomAction (Attivo), quindi scegliere Finestra Proprietà.
Nella finestra Proprietà impostare la proprietà CustomActionData sulla stringa seguente.
```
/targetdir="[TARGETDIR]\" /documentname="ExcelDeployment.xls" /assemblyname="ExcelDeployment.dll"
```
Per informazioni sulla proprietà CustomActionData, vedere Proprietà CustomActionData.
Fare clic con il pulsante destro del mouse sul progetto ExcelSetup in Esplora soluzioni, quindi scegliere Compila.

Verifica del progetto

Ora è possibile verificare il progetto per assicurarsi che la soluzione venga installata quando si esegue il file di Windows Installer nel computer di sviluppo.

Per verificare il progetto

Fare clic con il pulsante destro del mouse sul progetto ExcelSetup in Esplora soluzioni, quindi scegliere Esegui.
Seguire le istruzioni dell'installazione guidata e specificare una cartella di installazione nel computer di sviluppo.
Aprire la cartella di lavoro di Excel dalla cartella di installazione.
Verificare che venga visualizzata la finestra di messaggio.

Vedere anche

Condividi tramite