Een Windows-service-installatieprogramma maken

Artikel
12/15/2023

Wanneer u een .NET Windows-service maakt (niet te verwarren met een .NET Framework Windows-service), kunt u een installatieprogramma voor uw service maken. Zonder installatieprogramma moeten gebruikers weten hoe ze uw service moeten installeren en configureren. Een installatieprogramma bundelt de uitvoerbare bestanden van uw app en biedt een aanpasbare gebruikerservaring voor installatie. Deze zelfstudie is een vervolg van de zelfstudie Een Windows-service maken. Het laat zien hoe u een installatieprogramma maakt voor uw .NET Windows-service.

In deze zelfstudie leert u het volgende:

Installeer de visual Studio Installer Projects-extensie.
Maak een installatieproject.
Werk een bestaand .NET Worker-project bij om de installatie te ondersteunen.
Automatiseer de installatie en verwijdering met Windows Service Control Manager.

Vereisten

U hebt verwacht dat u de zelfstudie Een Windows-service maken hebt voltooid of bereid bent om de voorbeeldopslagplaats te klonen.
De .NET 8.0 SDK of hoger
Een Windows-besturingssysteem
Een .NET Integrated Development Environment (IDE)
- U kunt Visual Studio gerust gebruiken
Een bestaande .NET Windows-service

Hulpprogramma's installeren afhankelijkheden

Wix Toolset
Extensie voor Microsoft-installatieprogramma

Begin met het installeren van de Wix Toolset. De Wix Toolset is een set hulpprogramma's waarmee Windows-installatiepakketten worden gebouwd op basis van XML-broncode.

dotnet tool install --global wix

Installeer vervolgens de HeatWave voor VS2022-extensie. Nadat u Visual Studio hebt geïnstalleerd, start u Visual Studio opnieuw op en ziet u dat er nieuwe projectsjablonen beschikbaar zijn.

Bestaand project ophalen

Deze zelfstudie is gebaseerd op de app die is gemaakt als onderdeel van de zelfstudie Een Windows-service maken met behulp van BackgroundService . U kunt de voorbeeldopslagplaats klonen of de app gebruiken die u in de vorige zelfstudie hebt gemaakt.

Tip

Alle voorbeeldbroncode 'Workers in .NET' is beschikbaar in de voorbeeldenbrowser om te downloaden. Zie Codevoorbeelden bekijken: Workers in .NET voor meer informatie.

Wix Toolset
Extensie voor Microsoft-installatieprogramma

Open de oplossing in Visual Studio en selecteer F5 om ervoor te zorgen dat de app wordt gebouwd en uitgevoerd zoals verwacht. Druk op Ctrl+C om de app te stoppen.

Installatieswitches verwerken

De Windows Service-app moet installatieswitches afhandelen. Het installatieproject roept respectievelijk tijdens de installatie en verwijdering de Windows Service-app aan en /Install/Uninstall schakelt over. Wanneer deze switches aanwezig zijn, gedraagt de app zich anders, omdat de app alleen installatie of verwijdering uitvoert met behulp van het uitvoerbare bestand van Windows Service Control Manager (sc.exe).

Installeer het CliWrap NuGet-pakket als gemak om de app een afzonderlijk proces aan te roepen. Gebruik de dotnet add package opdracht om het CliWrap pakket te installeren:

dotnet add App.WindowsService.csproj package CliWrap

Zie dotnet add package voor meer informatie.

Als CliWrap dit is geïnstalleerd, opent u het bestand Program.cs van het App.WindowsService project. Voeg na de using instructies, maar voordat de IHost wordt gemaakt, de volgende code toe:

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;
}

Met de voorgaande code wordt:

Declareert de servicenaam als een const string waarde.
Hiermee wordt gecontroleerd args op één waarde.
Hiermee haalt u het uitvoerbare pad op van de AppContext.BaseDirectory.
Wanneer de "/Install" schakelaar aanwezig is, sc create ".NET Joke Service" binPath="path/to/App.WindowsService.exe" start=auto wordt aangeroepen.
Wanneer de "/Uninstall" schakelaar aanwezig sc stop ".NET Joke Service" is en sc delete ".NET Joke Service" worden aangeroepen.

Wanneer er geen installatieswitches aanwezig zijn, gedraagt de app zich zoals voorheen, maar bevat deze nu de installatiefunctionaliteit.

Notitie

Het definiëren van aangepaste acties en het handmatig afhandelen van installatieswitches wordt beschouwd als een antipatroon. Hoewel deze documentatie laat zien hoe u dit doet, kunt u overwegen om in plaats daarvan de Wix Toolset van derden te gebruiken.

Nieuw installatieproject toevoegen

Wix Toolset
Extensie voor Microsoft-installatieprogramma

Als u een nieuw Wix-installatieproject wilt toevoegen, klikt u met de rechtermuisknop op de oplossing in Solution Explorer en selecteert u Nieuw project toevoegen>:

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

Selecteer MSI-pakket (Wix v4) in de beschikbare sjablonen en selecteer vervolgens Volgende. Geef de gewenste naam en locatie op en selecteer Vervolgens Maken.

Installatieproject configureren

Wix Toolset
Extensie voor Microsoft-installatieprogramma

Als u het installatieproject wilt configureren, moet u eerst een verwijzing naar het App.WindowsService project toevoegen. Klik met de rechtermuisknop op het installatieproject in Solution Explorer en selecteer Vervolgens Projectverwijzing toevoegen>.

De sjabloon bevat voorbeeldonderdelen en lokalisatiebestanden. Verwijder deze, bestanden die alleen het bestand Package.wxs verlaten. Uw project moet nu een ProjectReference element bevatten dat er ongeveer als volgt uitziet:

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

Nadat de projectreferentie is toegevoegd, configureert u het bestand Package.wxs . Open het bestand in de editor en vervang de inhoud door het volgende:

<?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>

Wanneer u het project bouwt, is de uitvoer een MSI-bestand dat kan worden gebruikt om de service te installeren en te verwijderen.

Als u het installatieproject wilt configureren, selecteert u het project in Solution Explorer. Selecteer F4 om het deelvenster Projecteigenschappen te openen. U kunt de pictogrammen 'toevoegen' en 'verwijderen' van de app configureren, auteur, fabrikant, productnaam, titel, doelplatform, enzovoort.

Installer project properties pane.

Het installatieproject moet twee aangepaste acties voor installatiegedrag definiëren. Klik met de rechtermuisknop op het project in Solution Explorer en selecteer Aangepaste acties weergeven>.

Installer project Custom Actions context menu.

Selecteer In het venster Aangepaste acties de optie Aangepaste actie toevoegen installeren>.

Custom Actions properties dialog: select item.

Dubbelklik op de toepassingsmap (of selecteer Uitvoer toevoegen... met Toepassingsmap geselecteerd) en selecteer Items publiceren in App.WindowsService (actief).

Custom Actions properties dialog: select item app folder.

Selecteer OK om de selectie te bevestigen. Klik met de rechtermuisknop op het toegevoegde knooppunt Publiceren vanuit het knooppunt App.WindowsService (Actief) onder Installeren en selecteer Vervolgens Eigenschappen.

Publish items properties.

Toevoegen /Install aan de argumenten. Volg deze stappen voor Verwijderen en voeg deze toe aan /Uninstall de argumenten.

Als u beide hebt gedaan, ziet u het volgende:

Custom Actions with Install and Uninstall actions defined.

Met deze updates is het installatieproject geconfigureerd voor het delegeren van de acties installeren en verwijderen om met de juiste argumenten in te schakelen in de Windows Service-app.

Installatie testen

Wix Toolset
Extensie voor Microsoft-installatieprogramma

Publiceer het App.WindowsService-project om het installatieprogramma te testen. Klik met de rechtermuisknop op het project in Solution Explorer en selecteer Publiceren. Nadat het bestand is gepubliceerd met het profiel dat u in de vorige zelfstudie hebt gemaakt, bevindt het uitvoerbare bestand zich in de publicatiemap. Vervolgens bouwt u het installatieproject en voert u het installatieprogramma uit.

U moet de installatie uitvoeren als beheerder. Hiervoor klikt u met de rechtermuisknop op het MSI-bestand en selecteert u Uitvoeren als administrator.

Zodra de service is geïnstalleerd, kunt u Services openen om te zien of de service wordt uitgevoerd. Als u de service wilt verwijderen, gebruikt u de functie Windows Programma's toevoegen of verwijderen om het installatieprogramma aan te roepen.