Créer un programme d’installation de service Windows

Article
12/18/2023

Lors de la création d’un service Windows .NET (à ne pas confondre avec un service Windows .NET Framework), vous souhaiterez peut-être créer un programme d’installation pour votre service. Sans programme d’installation, les utilisateurs doivent savoir comment installer et configurer votre service. Un programme d’installation regroupe les exécutables de votre application, et expose une expérience utilisateur d’installation personnalisable. Ce tutoriel est une suite du tutoriel Créer un service Windows. Il montre comment créer un programme d’installation pour votre service Windows .NET.

Dans ce tutoriel, vous allez découvrir comment :

Installer l’extension Visual Studio Installer Projects.
Créer un projet d’installation.
Mettre à jour un projet .NET Worker existant pour prendre en charge l’installation.
Automatiser l’installation et la désinstallation avec le Gestionnaire de contrôle des services Windows.

Prérequis

Vous êtes censé avoir terminé le tutoriel Créer un service Windows ou être prêt à cloner l’exemple de dépôt.
Kit de développement logiciel (SDK) .NET 8.0 ou version ultérieure
Un système d’exploitation Windows
Un IDE (environnement de développement intégré) .NET
- N’hésitez pas à utiliser Visual Studio
Un service Windows .NET existant

Installer des dépendances d’outils

Ensemble d’outils WiX
Extension du programme d’installation Microsoft

Commencez par installer l’ensemble d’outils Wix. L’ensemble d’outils Wix génère des packages d’installation Windows à partir de code source XML.

dotnet tool install --global wix

Ensuite, installez l’extension HeatWave pour VS2022. Après l’installation, redémarrez Visual Studio ; vous verrez que de nouveaux modèles de projet sont disponibles.

Obtenir un projet existant

Ce tutoriel est basé sur l’application créée dans le cadre du tutoriel Créer un service Windows à l’aide de BackgroundService. Vous pouvez cloner l’exemple de dépôt ou utiliser l’application que vous avez créée dans le tutoriel précédent.

Conseil

Tout le code source d’exemple « Workers dans .NET » peut être téléchargé dans l’Explorateur d’exemples. Pour plus d’informations, consultez Parcourir les exemples de code : Workers dans .NET.

Ensemble d’outils WiX
Extension du programme d’installation Microsoft

Ouvrez la solution dans Visual Studio, puis sélectionnez F5 pour vérifier que l’application est générée et s’exécute comme prévu. Appuyez sur Ctrl+C pour arrêter l’application.

Gérer les commutateurs d’installation

L’application de service Windows doit gérer les commutateurs d’installation. Le projet d’installation appelle l’application de service Windows avec les commutateurs /Install et /Uninstall respectivement lors de l’installation et de la désinstallation. Lorsque ces commutateurs sont présents, l’application se comporte différemment, dans le sens où elle effectue uniquement l’installation ou la désinstallation à l’aide de l’exécutable du Gestionnaire de contrôle des services Windows (sc.exe).

Pour que l’application appelle un processus distinct, installez le package NuGet CliWrap à titre de commodité. Pour installer le package CliWrap, utilisez la commande dotnet add package :

dotnet add App.WindowsService.csproj package CliWrap

Pour plus d’informations, consultez dotnet add package.

Une fois CliWrap installé, ouvrez le fichier Program.cs du projet App.WindowsService. Après les instructions using, mais avant la création de IHost, ajoutez le code suivant :

using CliWrap;

const string ServiceName = ".NET Joke Service";

if (args is { Length: 1 })
{
    try
    {
        string executablePath =
            Path.Combine(AppContext.BaseDirectory, "App.WindowsService.exe");
    
        if (args[0] is "/Install")
        {
            await Cli.Wrap("sc")
                .WithArguments(new[] { "create", ServiceName, $"binPath={executablePath}", "start=auto" })
                .ExecuteAsync();
        }
        else if (args[0] is "/Uninstall")
        {
            await Cli.Wrap("sc")
                .WithArguments(new[] { "stop", ServiceName })
                .ExecuteAsync();
    
            await Cli.Wrap("sc")
                .WithArguments(new[] { "delete", ServiceName })
                .ExecuteAsync();
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex);
    }

    return;
}

Le code précédent :

Déclare le nom du service en tant que valeur const string.
Recherche si args contient une valeur unique.
Obtient le chemin d’exécutable à partir de AppContext.BaseDirectory.
Lorsque le commutateur "/Install" est présent, sc create ".NET Joke Service" binPath="path/to/App.WindowsService.exe" start=auto est appelé.
Lorsque le commutateur "/Uninstall" est présent, sc stop ".NET Joke Service" et sc delete ".NET Joke Service" sont appelés.

Lorsqu’aucun commutateur d’installation n’est présent, l’application se comporte comme auparavant, mais elle inclut désormais la fonctionnalité d’installation.

Notes

La définition d’actions personnalisées et la gestion manuelle des commutateurs d’installation sont considérées comme un anti-modèle. Bien que cette documentation montre comment procéder, vous préférerez peut-être utiliser l’ensemble d’outils Wix tiers à la place.

Ajouter un nouveau projet d’installation

Ensemble d’outils WiX
Extension du programme d’installation Microsoft

Pour ajouter un nouveau projet d’installation Wix, cliquez avec le bouton droit sur la solution dans l’Explorateur de solutions, puis sélectionnez Ajouter > Nouveau projet :

Add new project dialog: New MSI Package (Wix v4) Project.

Sélectionnez Package MSI (Wix v4) parmi les modèles disponibles, puis sélectionnez Suivant. Indiquez le Nom et l’Emplacement souhaités, puis sélectionnez Créer.

Configurer le projet de programme d’installation

Ensemble d’outils WiX
Extension du programme d’installation Microsoft

Pour configurer le projet d’installation, vous devez d’abord ajouter une référence au projet App.WindowsService. Cliquez avec le bouton droit sur le projet d’installation dans l’Explorateur de solutions, puis sélectionnez Ajouter > Référence de projet.

Le modèle inclut des exemples de fichiers de composant et de localisation. Supprimez ces fichiers, et conservez uniquement le fichier Package.wxs. Votre projet doit maintenant inclure un élément ProjectReference semblable à ce qui suit :

<Project Sdk="WixToolset.Sdk/4.0.0">
  <ItemGroup>
    <ProjectReference Include="..\App.WindowsService.csproj" />
  </ItemGroup>
</Project>

Une fois la référence de projet ajoutée, configurez le fichier Package.wxs. Ouvrez le fichier dans l’éditeur, puis remplacez le contenu par ce qui suit :

<?xml version="1.0" encoding="UTF-8"?>

<!-- Define the variables in "$(var.*) expressions" -->
<?define Name = ".NET Joke Service" ?>
<?define Manufacturer = "Microsoft" ?>
<?define Version = "1.0.0.0" ?>
<?define UpgradeCode = "9ED3FF33-8718-444E-B44B-69A2344B7E98" ?>

<Wix xmlns="http://wixtoolset.org/schemas/v4/wxs">
    <Package Name="$(Name)"
             Manufacturer="$(Manufacturer)"
             Version="$(Version)"
             UpgradeCode="$(var.UpgradeCode)"
             Compressed="true">
        
        <!-- Allow upgrades and prevent downgrades -->
        <MajorUpgrade DowngradeErrorMessage="A later version of [ProductName] is already installed. Setup will now exit." />

        <!-- Define the directory structure -->
        <Directory Id="TARGETDIR" Name="SourceDir">
            <Directory Id="ProgramFiles64Folder">

                <!-- Create a folder inside program files -->
                <Directory Id="ROOTDIRECTORY" Name="$(var.Manufacturer)">

                    <!-- Create a folder within the parent folder given the name -->
                    <Directory Id="INSTALLFOLDER" Name="$(Name)" />
                </Directory>
            </Directory>
        </Directory>

        <!-- The files inside this DirectoryRef are linked to
             the App.WindowsService directory via INSTALLFOLDER -->
        <DirectoryRef Id="INSTALLFOLDER">

            <!-- Create a single component which is the App.WindowsService.exe file -->
            <Component Id="ServiceExecutable" Bitness="always64">
                
                <!-- Copies the App.WindowsService.exe file using the
                     project reference preprocessor variables -->
                <File Id="App.WindowsService.exe"
                      Source="$(var.App.WindowsService.TargetDir)publish\App.WindowsService.exe"
                      KeyPath="true" />

                <!-- Remove all files from the INSTALLFOLDER on uninstall -->
                <RemoveFile Id="ALLFILES" Name="*.*" On="both" />

                <!-- Tell WiX to install the Service -->
                <ServiceInstall Id="ServiceInstaller"
                                Type="ownProcess"
                                Name="App.WindowsService"
                                DisplayName="$(Name)"
                                Description="A joke service that periodically logs nerdy humor."
                                Start="auto"
                                ErrorControl="normal" />

                <!-- Tell WiX to start the Service -->
                <ServiceControl Id="StartService"
                                Start="install"
                                Stop="both"
                                Remove="uninstall"
                                Name="App.WindowsService"
                                Wait="true" />
            </Component>
        </DirectoryRef>

        <!-- Tell WiX to install the files -->
        <Feature Id="Service" Title="App.WindowsService Setup" Level="1">
            <ComponentRef Id="ServiceExecutable" />
        </Feature>

    </Package>
</Wix>

Lorsque vous générez le projet, la sortie est un fichier MSI qui peut être utilisé pour installer et désinstaller le service.

Pour configurer le projet de programme d’installation, sélectionnez le projet dans l’Explorateur de solutions. Sélectionnez F4 pour ouvrir le volet de propriétés du projet. Vous pouvez configurer les icônes « ajouter » et « supprimer » de l’application, l’auteur, le fabricant, le nom du produit, le titre, la plateforme cible, etc.

Installer project properties pane.

Le projet de programme d’installation doit définir deux actions personnalisées pour le comportement d’installation. Cliquez avec le bouton droit sur le projet dans l’Explorateur de solutions, puis sélectionnez Afficher > Actions personnalisées.

Installer project Custom Actions context menu.

Dans la fenêtre Actions personnalisées, sélectionnez Installer > Ajouter une action personnalisée.

Custom Actions properties dialog: select item.

Double-cliquez sur le Dossier d’application (ou sélectionnez Ajouter une sortie avec Dossier d’application sélectionné), puis sélectionnez Publier des éléments à partir d’App.WindowsService (actif).

Custom Actions properties dialog: select item app folder.

Sélectionnez Ok pour confirmer la sélection. Cliquez avec le bouton droit sur le nœud Publier des éléments à partir d’App.WindowsService (Actif) que vous avez ajouté sous Installer, puis sélectionnez Propriétés.

Publish items properties.

Ajoutez /Install aux Arguments. Suivez ces mêmes étapes pour Désinstaller, en ajoutant /Uninstall aux Arguments.

Une fois ces deux opérations effectuées, vous devriez voir ce qui suit :

Custom Actions with Install and Uninstall actions defined.

Avec ces mises à jour, le projet d’installation a été configuré de façon à ce que ses actions Installer et Désinstaller appellent l’application de service Windows avec les arguments appropriés.

Tester l’installation

Ensemble d’outils WiX
Extension du programme d’installation Microsoft

Pour tester le programme d’installation, publiez le projet App.WindowsService. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet, puis sélectionnez Publier. Une fois publié avec le profil que vous avez créé dans le tutoriel précédent, l’exécutable se trouve dans le répertoire de publication. Ensuite, vous générez le projet d’installation et exécutez le programme d’installation.

Vous devez exécuter l’installation en tant qu’administrateur. Pour ce faire, cliquez avec le bouton droit sur le fichier MSI, puis sélectionnez Exécuter en tant qu'administrateur.

Une fois le service installé, vous pouvez ouvrir Services pour voir le service en cours d’exécution. Pour désinstaller le service, utilisez la fonctionnalité Ajout/Suppression de programmes Windows pour appeler le programme d’installation.