Création d’un programme d’installation de service Windows

2025-04-17

Lorsque vous créez un service Windows .NET (à ne pas confondre avec un service Windows .NET Framework), vous pouvez 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 continuation du didacticiel Créer un service Windows . Il montre comment créer un programme d’installation pour votre service Windows .NET.

Dans ce tutoriel, vous apprendrez comment le faire :

Installez l’extension Visual Studio Installer Projects.
Créez un projet d’installation.
Mettez à jour un projet .NET Worker existant pour prendre en charge l’installation.
Automatisez l’installation et la désinstallation avec le Gestionnaire de contrôle de service Windows.

Conditions préalables

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

Installer les 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 est un ensemble d’outils qui créent des packages d’installation Windows à partir du code source XML.

dotnet tool install --global wix

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

Obtenir un projet existant

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

Conseil / Astuce

Tous les exemples de code source « Workers in .NET » sont disponibles dans l’Explorateur d’exemples pour le téléchargement. 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 vous assurer que l’application génère et s’exécute comme prévu. Appuyez sur Ctrl+C pour arrêter l’application.

Gérer les commutateurs d’installation

L’application Windows Service doit gérer les commutateurs d’installation. Le projet d’installation appelle l’application Windows Service 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, car elle effectue uniquement l’installation ou la désinstallation à l’aide de l’exécutable windows Service Control Manager (sc.exe).

Pour que l’application appelle un processus distinct, installez le package NuGet CliWrap comme pratique. Pour installer le CliWrap package, utilisez la dotnet package add commande suivante :

dotnet add App.WindowsService.csproj package CliWrap

Pour plus d’informations, consultez dotnet package add.

Une fois CliWrap installé, ouvrez le fichier Program.cs du App.WindowsService projet. Après les directives 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;
}

Code précédent :

Déclare le nom du service comme une 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.

Quand aucun commutateur d’installation n’est présent, l’application se comporte comme avant, mais elle inclut désormais des fonctionnalités d’installation.

Remarque

La définition d’actions personnalisées et la gestion manuelle des commutateurs d’installation est considérée comme un anti-modèle. Bien que cette documentation montre comment procéder, vous pouvez envisager d’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 de configuration Wix, cliquez avec le bouton droit sur la solution dans l’Explorateur de solutions, puis sélectionnez Ajouter > un nouveau projet :

Boîte de dialogue Ajouter un nouveau projet : Nouveau projet Package MSI (Wix v4).

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

Configurer le projet 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 App.WindowsService projet. Cliquez avec le bouton droit sur le projet d’installation dans l’Explorateur de solutions, puis sélectionnez Ajouter une > référence de projet.

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

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

Une fois la référence du projet ajoutée, configurez le fichier Package.wxs . Ouvrez le fichier dans l’éditeur, puis remplacez le contenu par les éléments suivants :

<?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 d’installation, sélectionnez le projet dans l’Explorateur de solutions. Sélectionnez F4 pour ouvrir le volet des 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, et ainsi de suite.

Volet de propriétés du projet de programme d’installation.

Le projet 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 les > actions personnalisées.

Menu contextuel Actions personnalisées du projet de programme d’installation.

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

Boîte de dialogue Propriétés d’actions personnalisées : sélectionner un élément.

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).

Boîte de dialogue de propriétés d’actions personnalisées : sélectionner le dossier d’application.

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

Publier des propriétés d’éléments.

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

Une fois que vous avez terminé les deux, vous devez voir les éléments suivants :

Actions personnalisées avec les actions d’installation et de désinstallation définies.

Avec ces mises à jour, le projet d’installation a été configuré pour déléguer ses actions d’installation et de désinstallation pour appeler l’application Windows Service avec les arguments appropriés.

Installation de test

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

Pour tester le programme d’installation, publiez le projet App.WindowsService . Cliquez avec le bouton droit sur le projet dans l’Explorateur de solutions, puis sélectionnez Publier. Une fois publié avec le profil que vous avez créé dans le didacticiel précédent, l’exécutable se trouvera 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é Ajouter ou supprimer des programmes Windows pour appeler le programme d’installation.

Partager via