Erstellen eines Windows-Dienst-Installationsprogramms

Wenn Sie einen .NET Windows-Dienst erstellen (nicht mit einem .NET Framework Windows-Dienst zu verwechseln), sollten Sie ein Installationsprogramm (Installer) für Ihren Dienst erstellen. Ohne ein Installationsprogramm müssten Benutzer wissen, wie Sie Ihren Dienst installieren und konfigurieren. Ein Installationsprogramm bündelt die ausführbaren Dateien Ihrer App und stellt eine anpassbare Benutzererfahrung für die Installation zur Verfügung. Dieses Tutorial ist eine Fortsetzung des Tutorials Erstellen eines Windows-Diensts. Es wird gezeigt, wie Sie ein Installationsprogramm für Ihren .NET-Windows-Dienst erstellen.

In diesem Tutorial lernen Sie Folgendes:

• Installieren der Visual Studio Installer Projects -Erweiterung.
• Erstellen eines Setup-Projekts.
• Aktualisieren eines vorhandenen .NET Worker-Projekts zur Unterstützung der Installation.
• Automatisieren der Installation und Deinstallation mit dem Windows-Dienststeuerungs-Manager.

Voraussetzungen

• Es wird erwartet, dass Sie das Tutorial Erstellen eines Windows-Diensts abgeschlossen haben oder darauf vorbereitet sind, das Beispielrepository zu klonen.
• Das .NET 8.0 SDK oder höher
• Ein Windows-Betriebssystem
• In .NET integrierte Entwicklungsumgebung (Integrated Development Environment, IDE)
  • Nach Wunsch Visual Studio
• Ein vorhandener .NET Windows-Dienst

Installieren von Toolabhängigkeiten

Wix-Toolset

Installieren Sie zunächst das Wix-Toolset. Das Wix-Toolset besteht aus einer Reihe von Tools, die Windows-Installationspakete aus XML-Quellcode erstellen.

dotnet tool install --global wix

Installieren Sie als Nächstes die Erweiterung „HeatWave for VS2022“. Starten Sie nach der Installation Visual Studio neu, woraufhin neue Projektvorlagen als verfügbar angezeigt werden.

Erweiterung des Microsoft-Installationsprogramms

Installieren der Microsoft Visual Studio Installer Projects -Erweiterung. Starten Sie nach der Installation Visual Studio neu, woraufhin neue Projektvorlagen als verfügbar angezeigt werden.

Vorhandenes Projekt abrufen

Dieses Tutorial basiert auf der App, die im Rahmen des Tutorials Erstellen eines Windows-Diensts mit BackgroundService erstellt wurde. Sie können das Beispielrepository entweder klonen oder die App verwenden, die Sie im vorherigen Tutorial erstellt haben.

Tipp

Der gesamte Quellcode des Beispiels „Worker in .NET“ steht im Beispielbrowser zum Download zur Verfügung. Weitere Informationen finden Sie unter Durchsuchen von Codebeispielen: Worker in .NET.

Wix-Toolset

Öffnen Sie die Projektmappe in Visual Studio, und drücken Sie F5, um sicherzustellen, dass die App wie erwartet erstellt und ausgeführt wird. Drücken Sie STRG+C, um die App zu beenden.

Erweiterung des Microsoft-Installationsprogramms

Öffnen Sie die Projektmappe in Visual Studio, und drücken Sie F5, um sicherzustellen, dass die App wie erwartet erstellt und ausgeführt wird. Drücken Sie STRG+C, um die App zu beenden.

Behandeln von Installationsschaltern

Die Windows-Dienst-App muss Installationsschalter verarbeiten. Das Setup-Projekt ruft die Windows-Dienst-App während der Installation bzw. Deinstallation mit den Schaltern /Install und /Uninstall auf. Wenn diese Schalter vorhanden sind, verhält sich die App insofern anders, als dass sie die Installation oder Deinstallation nur mit der ausführbaren Windows-Dienststeuerungs-Manager-Datei (sc.exe) ausführt.

Damit die App einen gesonderten Prozess aufruft, installieren Sie zur Bequemlichkeit das NuGet-Paket CliWrap. Um das Paket CliWrap zu installieren, verwenden Sie den Befehl dotnet add package:

dotnet add App.WindowsService.csproj package CliWrap

Weitere Informationen finden Sie unter dotnet add package.

Öffnen Sie mit installiertem CliWrap die Datei Program.cs des App.WindowsService-Projekts. Fügen Sie hinter den using-Anweisungen, aber vor der Erstellung von IHost, den folgenden Code hinzu:

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

Der vorangehende Code:

• Deklariert den Dienstnamen als const string-Wert.
• Überprüft die args auf einen einzelnen Wert.
• Ruft den ausführbaren Pfad aus dem AppContext.BaseDirectory ab.
• Wenn der Schalter "/Install" vorhanden ist, wird sc create ".NET Joke Service" binPath="path/to/App.WindowsService.exe" start=auto aufgerufen.
• Wenn der Schalter "/Uninstall" vorhanden ist, werden sc stop ".NET Joke Service" und sc delete ".NET Joke Service" aufgerufen.

Wenn keine Installationsschalter vorhanden sind, verhält sich die App wie zuvor, enthält aber jetzt Installationsfunktionen.

Hinweis

Das Definieren benutzerdefinierter Aktionen und das manuelle Behandeln von Installationsswitches wird als Antimuster betrachtet. In dieser Dokumentation wird zwar veranschaulicht, wie dies funktioniert, es wird jedoch die Verwendung des Wix-Toolsets von Drittanbietern empfohlen.

Hinzufügen eines neuen Setup-Projekts

Wix-Toolset

Klicken Sie zum Hinzufügen eines neuen Wix-Setupprojekts im Projektmappen-Explorer mit der rechten Maustaste auf die Projektmappe, und wählen Sie Hinzufügen > Neues Projekt aus:

Wählen Sie in den verfügbaren Vorlagen MSI-Paket (Wix v4) und dann Weiter aus. Geben Sie den gewünschten Namen und Speicherort an, und wählen Sie dann Erstellen aus.

Erweiterung des Microsoft-Installationsprogramms

Klicken Sie zum Hinzufügen eines neuen Setup-Projekts im Projektmappen-Explorer mit der rechten Maustaste auf die Projektmappe, und wählen Sie Hinzufügen > Neues Projekt aus:

Wählen Sie aus den verfügbaren Vorlagen Setup-Projekt und dann Weiter aus. Geben Sie den gewünschten Namen und Speicherort an, und wählen Sie dann Erstellen aus.

Konfigurieren des Installationsprogrammprojekts

Wix-Toolset

Zum Konfigurieren des Setupprojekts müssen Sie zunächst einen Verweis auf das App.WindowsService-Projekt hinzufügen. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Setupprojekt, und wählen Sie dann Hinzufügen > Projektverweis aus.

Die Vorlage enthält Beispielkomponenten- und Lokalisierungsdateien. Löschen Sie diese Dateien, und lassen Sie nur die Datei Package.wxs übrig. Ihr Projekt sollte nun ein ProjectReference-Element wie das folgende enthalten:

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

Nachdem der Projektverweis hinzugefügt wurde, konfigurieren Sie die Datei Package.wxs. Öffnen Sie die Datei im Editor, und ersetzen Sie den Inhalt durch Folgendes:

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

Wenn Sie das Projekt erstellen, ist die Ausgabe eine MSI-Datei, die zum Installieren und Deinstallieren des Diensts verwendet werden kann.

Erweiterung des Microsoft-Installationsprogramms

Wählen Sie zum Konfigurieren des Installationsprogrammprojekts das Projekt im Projektmappen-Explorer aus. Drücken Sie F4, um den Bereich mit den Projekteigenschaften zu öffnen. Sie können für die App die Symbole „Hinzufügen“ und „Entfernen“, den Autor, Hersteller, Produktnamen, Titel, die Zielplattform usw. konfigurieren.

Das Installationsprogrammprojekt muss zwei benutzerdefinierte Aktionen für das Installationsverhalten definieren. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie dann Anzeigen > Benutzerdefinierte Aktionen aus.

Wählen Sie im Fenster Benutzerdefinierte Aktionen die Option Installieren > Benutzerdefinierte Aktion hinzufügen aus.

Doppelklicken Sie auf den Anwendungsordner (oder wählen Sie Ausgabe hinzufügen… aus, wobei der Anwendungsordner ausgewählt ist), und wählen Sie Elemente aus „App.WindowsService (Aktiv)“ veröffentlichen aus.

Wählen Sie OK aus, um die Auswahl zu bestätigen. Klicken Sie unter Installieren mit der rechten Maustaste auf den Knoten Elemente aus App.WindowsService (Aktiv) veröffentlichen, und wählen Sie dann Eigenschaften aus.

Fügen Sie den Argumenten das Argument /Install hinzu. Führen Sie die gleichen Schritte für Deinstallieren aus, und fügen Sie den /UninstallArgumenten das Argument hinzu.

Sobald Sie beides ausgeführt haben, sollten Sie Folgendes sehen:

Mit diesen Updates wurde das Setup-Projekt so konfiguriert, dass es seine Installieren- und Deinstallieren-Aktionen delegiert, um die Windows-Dienst-App mit den entsprechenden Argumenten aufzurufen.

Testen der Installation

Wix-Toolset

Um das Installationsprogramm zu testen, veröffentlichen Sie das Projekt App.WindowsService. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie Veröffentlichen aus. Nach der Veröffentlichung mit dem Profil, das Sie im vorherigen Tutorial erstellt haben, befindet sich die ausführbare Datei im Veröffentlichungsverzeichnis. Als Nächstes erstellen Sie das Setupprojekt und führen das Installationsprogramm aus.

Sie müssen die Installation als Administrator*in ausführen. Klicken Sie dazu mit der rechten Maustaste auf die MSI-Datei, und wählen Sie Als Administrator ausführen aus.

Nachdem der Dienst installiert wurde, können Sie Services öffnen, um den ausgeführten Dienst anzuzeigen. Um den Dienst zu deinstallieren, verwenden Sie das Windows-Feature Programme hinzufügen oder entfernen, um das Installationsprogramm aufzurufen.

Erweiterung des Microsoft-Installationsprogramms

Um das Installationsprogramm zu testen, erweitern Sie Projektmappenkonfigurationen in Visual Studio, und wählen Sie Release aus (vorausgesetzt, Debuggen wurde ausgewählt). Erstellen Sie die Projektmappe, klicken Sie dann mit der rechten Maustaste auf das Setup-Projekt, und wählen Sie Erstellen aus. Setup-Projekte sind standardmäßig nicht Teil des Builds.

Wählen Sie Anzeigen > Ausgabe aus, und stellen Sie sicher, dass in der Dropdownliste Ausgabe anzeigen von die Option Build (Erstellen) ausgewählt ist. Der MSI-Dateipfad (Microsoft Installer) wird angezeigt. Kopieren Sie den Pfad, und öffnen Sie das Installationsprogramm. Führen Sie das Installationsprogramm aus.

Sie müssen die Installation als Administrator*in ausführen. Klicken Sie dazu mit der rechten Maustaste auf die MSI-Datei, und wählen Sie Als Administrator ausführen aus.

1. Begrüßungsdialogfeld des Installationsprogramms

2. Dialogfeld „Ordner auswählen“ des Installationsprogramms

3. Dialogfeld „Bestätigen“ des Installationsprogramms

4. Dialogfeld „Installationsprogramm abgeschlossen“

Nachdem der Dienst installiert wurde, können Sie Dienste öffnen, um den Dienst zu starten. Um den Dienst zu deinstallieren, verwenden Sie das Windows-Feature Programme hinzufügen oder entfernen, um das Installationsprogramm aufzurufen.

Siehe auch

• Workerdienste in .NET
• Erstellen eines Warteschlangendiensts
• Verwenden bereichsbezogener Dienste in einem BackgroundService
• Implementieren der IHostedService-Schnittstelle