Erstellen eines Windows-Dienst-Installationsprogramms

2025-04-18

Wenn Sie einen .NET-Windows-Dienst erstellen (nicht mit einem .NET Framework-Windows-Dienst zu verwechseln), sollten Sie ein Installationsprogramm für Ihren Dienst erstellen. Ohne ein Installationsprogramm müssten Benutzer wissen, wie Sie Ihren Dienst installieren und konfigurieren können. Ein Installationsprogramm bündelt die ausführbaren Dateien Ihrer App und macht eine anpassbare Benutzeroberfläche für die Installation verfügbar. Dieses Lernprogramm ist eine Fortsetzung des Lernprogramms zum Erstellen eines Windows-Diensts . Es zeigt, wie Sie ein Installationsprogramm für Ihren .NET Windows-Dienst erstellen.

In diesem Tutorial lernen Sie, wie Sie:

Installieren Sie die Visual Studio Installer Projects-Erweiterung.
Erstellen Sie ein Setupprojekt.
Aktualisieren Sie ein vorhandenes .NET Worker-Projekt, um die Installation zu unterstützen.
Automatisieren Sie die Installation und Deinstallation mit dem Windows Service Control Manager.

Voraussetzungen

Es wird erwartet, dass Sie das Lernprogramm zum Erstellen eines Windows-Diensts abgeschlossen haben oder bereit sind, das Beispiel-Repository zu klonen.
.NET 8.0 SDK oder höher
Ein Windows-Betriebssystem
Eine integrierte .NET-Entwicklungsumgebung (IDE)
- Sie können Visual Studio verwenden
Ein vorhandener .NET-Windows-Dienst

Installieren Sie zunächst das Wix-Toolset. Das Wix Toolset ist eine Reihe von Tools, mit denen Windows-Installationspakete aus XML-Quellcode erstellt werden.

dotnet tool install --global wix

Installieren Sie als Nächstes die Erweiterung HeatWave für VS2022. Starten Sie nach der Installation Visual Studio neu, und es sind neue Projektvorlagen verfügbar.

Vorhandenes Projekt abrufen

Dieses Lernprogramm basiert auf der App, die im Rahmen des Lernprogramms "Erstellen eines Windows-Diensts mit BackgroundService " erstellt wurde. Sie können entweder das Beispiel-Repository klonen oder die App verwenden, die Sie im vorherigen Lernprogramm erstellt haben.

Tipp

Der Quellcode "Workers in .NET" ist im Beispielbrowser zum Herunterladen verfügbar. Weitere Informationen finden Sie unter Durchsuchen von Codebeispielen: Worker in .NET.

Wix-Toolset
Microsoft Installer-Erweiterung

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

Installationsschalter behandeln

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 anders, da sie nur die Installation oder Deinstallation mit der ausführbaren Datei des Windows Service Control Managers (sc.exe) durchführt.

Damit die App einen separaten Prozess aufruft, installieren Sie das CliWrap NuGet-Paket als Komfort. Verwenden Sie den folgenden Befehl, um das CliWrap Paket zu installieren.

dotnet add App.WindowsService.csproj package CliWrap

Weitere Informationen finden Sie unter dotnet package add.

Öffnen Sie nach der Installation von CliWrap die Datei "Program.cs" des Projekts App.WindowsService. Fügen Sie nach den using Direktiven, aber vor der IHost Erstellung 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 vorherige 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 "/Install" Schalter vorhanden ist, sc create ".NET Joke Service" binPath="path/to/App.WindowsService.exe" start=auto wird aufgerufen.
Wenn der "/Uninstall" Schalter vorhanden ist, werden sc stop ".NET Joke Service" und sc delete ".NET Joke Service" aufgerufen.

Wenn keine Installationsoptionen vorhanden sind, verhält sich die App wie zuvor, aber sie enthält 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, aber Sie sollten stattdessen die Verwendung des Wix-Toolsets von Drittanbietern in Betracht ziehen.

Neues Setupprojekt hinzufügen

Wix-Toolset
Microsoft Installer-Erweiterung

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:

Dialogfeld zum Hinzufügen eines neuen Projekts: Neues MSI-Paketprojekt (Wix v4)

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.

Konfigurieren des Installationsprojekts

Wix-Toolset
Microsoft Installer-Erweiterung

Zum Konfigurieren des Setupprojekts müssen Sie zuerst 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, wobei nur die Datei "Package.wxs " übrig bleibt. Ihr Projekt sollte nun ein ProjectReference Element enthalten, ähnlich dem folgenden:

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

Konfigurieren Sie nach dem Hinzufügen der Projektreferenz die Datei "Package.wxs ". Öffnen Sie die Datei im Editor, und ersetzen Sie dann 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>

Beim Erstellen des Projekts handelt es sich bei der Ausgabe um eine MSI-Datei, die zum Installieren und Deinstallieren des Diensts verwendet werden kann.

Um das Installationsprogrammprojekt zu konfigurieren, wählen Sie das Projekt im Projektmappen-Explorer aus. Wählen Sie F4 aus, um den Projekteigenschaftenbereich zu öffnen. Sie können die Symbole "Hinzufügen" und "Entfernen" der App konfigurieren, Autor, Hersteller, Produktname, Titel, Zielplattform usw.

Bereich

Das Installationsprojekt 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 "Benutzerdefinierte Aktionen anzeigen" >aus.

Kontextmenü des Installer-Projekts

Wählen Sie im Fenster "Benutzerdefinierte Aktionen" die Option "Benutzerdefinierte Aktion installieren und hinzufügen" aus.

Dialogfeld

Doppelklicken Sie auf den Anwendungsordner (oder wählen Sie Ausgabe hinzufügen... aus, während Anwendungsordner ausgewählt ist), und wählen Sie Elemente aus App.WindowsService (Aktiv) aus.

Dialogfeld „Eigenschaften für benutzerdefinierte Aktionen“: Anwendungsordner auswählen.

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.

Veröffentlichen von Elementeigenschaften.

Füge /Install den Argumenten hinzu. Führen Sie die gleichen Schritte für die Deinstallation aus, und fügen Sie die Argumente hinzu/Uninstall.

Nachdem Sie beides abgeschlossen haben, sollten Sie Folgendes sehen:

Benutzerdefinierte Aktionen mit definierten Installations- und Deinstallationsaktionen.

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
Microsoft Installer-Erweiterung

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

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

Nachdem der Dienst installiert wurde, können Sie Dienste öffnen, um den Dienst anzuzeigen, der ausgeführt wird. Verwenden Sie zum Deinstallieren des Diensts das Feature "Windows-Programme hinzufügen oder entfernen ", um das Installationsprogramm aufzurufen.

Teilen über