Procédure pas à pas : déploiement d'une personnalisation au niveau du document à l'aide d'un fichier Windows Installer (Office System 2003)

Article
04/28/2010

Mise à jour : novembre 2007

S'applique à
Les informations de cette rubrique s'appliquent uniquement aux projets et versions Visual Studio Tools pour Office de Microsoft Office spécifiés. Type de projet Projets au niveau du document Version de Microsoft Office Microsoft Office 2003 Pour plus d'informations, consultez Fonctionnalités disponibles par type d'application et de projet.

Les informations de cette rubrique s'appliquent uniquement aux projets et versions Visual Studio Tools pour Office de Microsoft Office spécifiés.

Type de projet

Projets au niveau du document

Version de Microsoft Office

Microsoft Office 2003

Pour plus d'informations, consultez Fonctionnalités disponibles par type d'application et de projet.

Cette procédure pas à pas montre comment créer un fichier Microsoft Windows Installer (.msi) pouvant être utilisé pour déployer une personnalisation au niveau du document. Pour plus d'informations sur les personnalisations au niveau du document, consultez Architecture des personnalisations au niveau du document.

Cette procédure pas à pas illustre les tâches suivantes :

Création d'un projet d'installation que vous pourrez utiliser pour générer un fichier Windows Installer.
Modification du projet d'installation pour que le fichier Windows Installer installe votre solution Visual Studio Tools pour Office.
Ajout d'une étape au projet d'installation pour que le fichier Windows Installer modifie le manifeste d'application incorporé dans le document de la solution Visual Studio Tools pour Office.

Cette procédure pas à pas suppose que l'ordinateur cible dispose déjà des composants requis pour l'exécution de solutions Visual Studio Tools pour Office. Le fichier Windows Installer que vous générez n'installe pas ces composants requis, ni n'en vérifie la présence. Pour plus d'informations sur l'installation des composants requis, consultez Déploiement de solutions Visual Studio 2005 Tools pour Office Second Edition à l'aide de Windows Installer (en anglais). Pour plus d'informations sur les composants requis pour l'exécution de solutions Visual Studio Tools pour Office, consultez Comment : préparer les ordinateurs des utilisateurs finaux à exécuter des solutions Office (Office System 2003).

Remarque :
Pour que la solution puisse s'exécuter, les assemblys présents dans les solutions Visual Studio Tools pour Office doivent avoir au préalable reçu une confiance totale dans le cadre de la stratégie de sécurité de l'utilisateur final. Le fichier Windows Installer que vous générez au cours de cette procédure pas à pas ne déploie pas la stratégie de sécurité requise pour exécuter la solution. Pour plus d'informations sur l'ajout d'une action personnalisée pour accorder un niveau de confiance à l'assembly de personnalisation, consultez Déploiement de solutions Visual Studio 2005 Tools pour Office Second Edition à l'aide de Windows Installer (en anglais). Pour plus d'informations sur la sécurité dans les solutions Visual Studio Tools pour Office, consultez Spécifications de sécurité pour exécuter des solutions Office (Office System 2003) et Meilleures pratiques pour la sécurité dans les solutions Office (Office System 2003). Pour plus d'informations sur la définition de la stratégie de sécurité sur les ordinateurs des utilisateurs finaux, consultez Déploiement de la stratégie de sécurité.

Pour que la solution puisse s'exécuter, les assemblys présents dans les solutions Visual Studio Tools pour Office doivent avoir au préalable reçu une confiance totale dans le cadre de la stratégie de sécurité de l'utilisateur final. Le fichier Windows Installer que vous générez au cours de cette procédure pas à pas ne déploie pas la stratégie de sécurité requise pour exécuter la solution. Pour plus d'informations sur l'ajout d'une action personnalisée pour accorder un niveau de confiance à l'assembly de personnalisation, consultez Déploiement de solutions Visual Studio 2005 Tools pour Office Second Edition à l'aide de Windows Installer (en anglais). Pour plus d'informations sur la sécurité dans les solutions Visual Studio Tools pour Office, consultez Spécifications de sécurité pour exécuter des solutions Office (Office System 2003) et Meilleures pratiques pour la sécurité dans les solutions Office (Office System 2003). Pour plus d'informations sur la définition de la stratégie de sécurité sur les ordinateurs des utilisateurs finaux, consultez Déploiement de la stratégie de sécurité.

Composants requis

Les composants suivants sont nécessaires pour exécuter cette procédure pas à pas :

Visual Studio Tools pour Office (composant facultatif de Visual Studio 2008 Professional et Visual Studio Team System)
Microsoft Office Word 2003 ou Microsoft Office Excel 2003

Création du projet

Dans cette étape, vous allez créer un projet de classeur Excel. Si vous souhaitez exécuter la procédure pas à pas avec une solution Word ou Excel existante, démarrez la procédure au niveau du titre « Création du projet d'installation » et veillez à remplacer le nom du projet ExcelDeployment par le nom de votre projet dans tous les exemples de code et toutes les instructions.

Pour créer un projet

À l'aide du modèle de projet pour Office 2003, créez un projet de classeur Excel nommé ExcelDeployment.

Dans l'Assistant, sélectionnez Créer un nouveau document. Pour plus d'informations, consultez Comment : créer des projets Visual Studio Tools pour Office.

Visual Studio ouvre le nouveau classeur Excel dans le concepteur et ajoute le projet ExcelDeployment à l'Explorateur de solutions.

Ajout du code-behind du classeur

Le projet nécessite du code pour permettre de vérifier le bon fonctionnement de la solution à l'ouverture du document. Pour cette procédure pas à pas, ajoutez un message au gestionnaire d'événements Startup du classeur.

Pour ajouter un message à un événement d'initialisation

Dans l'Explorateur de solutions, cliquez avec le bouton droit sur ThisWorkbook.vb ou ThisWorkbook.cs, puis cliquez sur Afficher le code dans le menu contextuel.

Ajoutez le code suivant au gestionnaire de l'événement Startup à l'intérieur de la classe ThisWorkbook pour afficher un message pendant l'initialisation.

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.");
}

Appuyez sur F5 pour exécuter le projet.

Excel démarre et le message apparaît.
Fermez le message.
Quittez Excel.

Création d'un projet d'installation

Les projets d'installation fournissent des fichiers et du code que vous pouvez compiler pour créer un fichier Windows Installer pour votre solution. Pour plus d'informations, consultez Projets d'installation.

Pour créer un projet d'installation pour votre solution

Cliquez avec le bouton droit sur le nœud de la solution dans l'Explorateur de solutions.
Dans le menu contextuel, pointez sur Ajouter, puis cliquez sur Nouveau projet.

La boîte de dialogue Ajouter un nouveau projet s'affiche.
Dans le volet Types de projets, développez Autres types de projets et sélectionnez Configuration et déploiement.
Dans le volet Modèles, sélectionnez Projet d'installation.
Nommez le projet ExcelSetup.
Cliquez sur OK.

Le projet d'installation apparaît dans l'Explorateur de solutions. Par défaut, le fichier Windows Installer que vous allez générer à l'aide de ce projet d'installation inclut une boîte de dialogue qui permet à l'utilisateur final de spécifier l'emplacement d'installation de la solution. Pour plus d'informations, consultez Dossier d'installation, boîte de dialogue de l'interface utilisateur.

Ajout du classeur et de l'assembly de solution au projet d'installation

La sortie principale du projet ExcelDeployment se compose du classeur et l'assembly de solution. Ajoutez ces composants au projet d'installation.

Pour ajouter le document et l'assembly au projet d'installation

Cliquez avec le bouton droit sur le nœud du projet ExcelSetup dans l'Explorateur de solutions.
Dans le menu contextuel, pointez vers Affichage, puis cliquez sur Système de fichiers.
Cliquez avec le bouton droit sur Dossier d'application dans le volet gauche.
Dans le menu contextuel, pointez sur Ajouter, puis cliquez sur Sortie du projet.
Sélectionnez ExcelDeployment dans la zone Projet.
Sélectionnez Sortie principale dans la liste des types de sortie.
Cliquez sur OK.

La sortie de projet et les dépendances s'affichent dans le volet droit.
Dans l'Explorateur de solutions, développez Dépendances détectées sous le nœud du projet ExcelSetup.
Cliquez avec le bouton droit sur chaque dépendance à l'exception de Microsoft .NET Framework, puis cliquez sur Exclure dans le menu contextuel.

Création d'un projet d'action personnalisée

Les actions personnalisées constituent une fonctionnalité de Windows Installer. Vous pouvez les utiliser pour exécuter du code au terme du processus d'installation, afin d'effectuer des actions qui ne peuvent pas être réalisées au cours de l'installation. Pour plus d'informations, consultez Actions personnalisées.

Pour créer un projet d'action personnalisée

Cliquez avec le bouton droit sur le nœud de la solution dans l'Explorateur de solutions.
Dans le menu contextuel, pointez sur Ajouter, puis cliquez sur Nouveau projet.

La boîte de dialogue Ajouter un nouveau projet s'affiche.
Dans le volet Types de projets, développez le nœud de votre langage de programmation, puis sélectionnez Windows.
Dans le volet Modèles, sélectionnez Bibliothèque de classes.
Nommez le projet ExcelCustomAction.
Cliquez sur OK.

Le nouveau projet s'affiche dans l'Explorateur de solutions.
Dans l'Explorateur de solutions, cliquez avec le bouton droit sur Class1.vb ou Class1.cs, sous le projet ExcelCustomAction, puis cliquez sur Supprimer. Ce fichier est inutile pour cette procédure pas à pas.

Création d'une action personnalisée qui modifie le manifeste d'application

Lorsque vous avez exécuté votre projet dans cette procédure pas à pas en appuyant sur F5, le processus de génération a modifié le manifeste d'application incorporé dans le classeur, pour pointer sur le chemin d'accès relatif de l'assembly. Si le classeur et l'assembly restent dans le même dossier après l'installation, vous n'avez pas besoin de modifier le manifeste d'application incorporé ; vous pouvez ignorer cette section. Toutefois, si vous souhaitez permettre à l'utilisateur de déplacer le classeur vers un autre dossier après l'installation de la solution, vous devez modifier le manifeste d'application pour pointer vers le chemin d'accès complet de l'assembly.

Vous devez mettre à jour le manifeste d'application incorporé dans le document de la solution Visual Studio Tools pour Office en exécutant une action personnalisée au terme du processus d'installation. En effet, l'emplacement de l'assembly de solution reste inconnu tant que l'utilisateur ne l'a pas spécifié au cours de l'installation. Modifiez le manifeste d'application incorporé à l'aide de la classe ServerDocument. Pour utiliser la classe ServerDocument dans votre projet d'installation, ajoutez un code à une classe Installer au sein du projet d'action personnalisée.

Pour créer une action personnalisée qui modifie le manifeste d'application

Cliquez avec le bouton droit sur le nœud ExcelCustomAction dans l'Explorateur de solutions.
Dans le menu contextuel, pointez sur Ajouter, puis cliquez sur Nouvel élément.

La boîte de dialogue Ajouter un nouvel élément s'affiche alors.
Sélectionnez Classe Installer et nommez la classe ManifestEditor.
Ajoutez une référence à l'assembly Microsoft.VisualStudio.Tools.Applications.Runtime au projet ExcelCustomAction.
Dans l'Explorateur de solutions, cliquez avec le bouton droit sur le fichier ManifestEditor.cs ou ManifestEditor.vb, puis cliquez sur Afficher le code.

Ajoutez l'instruction Imports ou using suivante en haut du fichier de code.

Imports Microsoft.VisualStudio.Tools.Applications.Runtime

using Microsoft.VisualStudio.Tools.Applications.Runtime;

Copiez le code suivant dans la classe ManifestEditor.

Ce code substitue la méthode Install utilisée pour exécuter des actions d'installation personnalisées. Le code affecte pour valeur à l'emplacement d'installation spécifié par l'utilisateur la propriété AssemblyPath. Le chemin d'installation ainsi que les noms du document et de l'assembly spécifiés par l'utilisateur sont obtenus à partir de la propriété 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();
        }
    }
}

Cliquez avec le bouton droit sur le projet ExcelCustomAction dans l'Explorateur de solutions, puis cliquez sur Générer.

Ajout de l'action personnalisée au projet d'installation

Le ficher Windows Installer peut à présent exécuter l'action personnalisée qui modifie le manifeste d'application. Pour cela, vous devez ajouter la sortie principale du projet ExcelCustomAction au projet d'installation.

Pour ajouter la sortie principale du projet d'action personnalisée au projet d'installation

Cliquez avec le bouton droit sur le nœud du projet ExcelSetup dans l'Explorateur de solutions.
Pointez sur Afficher dans le menu contextuel, puis cliquez sur Actions personnalisées.
Dans l'Éditeur des actions personnalisées, cliquez avec le bouton droit sur le nœud Installer, puis cliquez sur Ajouter une action personnalisée.
Dans la zone Regarder dans, sélectionnez Dossier d'application, puis cliquez sur Ajouter une sortie.
Sélectionnez ExcelCustomAction dans la zone Projet.
Sélectionnez Sortie principale dans la liste des types de sortie, puis cliquez sur OK.
Vérifiez que Sortie principale de ExcelCustomAction (Actif) est ajouté à la liste des sorties principales destinées au projet d'installation, puis cliquez sur OK.
Dans l'Éditeur des actions personnalisées, développez Installer.
Cliquez avec le bouton droit sur Sortie principale de ExcelCustomAction (Actif), puis cliquez sur Fenêtre Propriétés.
Dans la fenêtre Propriétés, affectez la propriété CustomActionData à la chaîne suivante.
```
/targetdir="[TARGETDIR]\" /documentname="ExcelDeployment.xls" /assemblyname="ExcelDeployment.dll"
```
Pour plus d'informations sur la propriété CustomActionData, consultez CustomActionData, propriété.
Cliquez avec le bouton droit sur le projet ExcelSetup dans l'Explorateur de solutions, puis cliquez sur Générer.

Test du projet

Vous pouvez à présent tester le projet pour vous assurer que la solution s'installe correctement lorsque vous exécutez le fichier Windows Installer sur votre ordinateur de développement.

Pour tester le projet

Cliquez avec le bouton droit sur le projet ExcelSetup dans l'Explorateur de solutions, puis cliquez sur Exécuter.
Suivez les instructions de l'Assistant Installation et spécifiez un dossier installation sur votre ordinateur de développement.
Ouvrez le classeur Excel à partir du dossier d'installation.
Vérifiez que le message s'affiche.

Voir aussi

Partager via