Tworzenie instalatora usługi systemu Windows

Artykuł
12/15/2023

Podczas tworzenia usługi systemu Windows platformy .NET (aby nie pomylić się z usługą .NET Framework dla systemu Windows), możesz utworzyć instalatora dla usługi. Bez instalatora użytkownicy musieliby wiedzieć, jak zainstalować i skonfigurować usługę. Instalator pakuje pliki wykonywalne aplikacji i uwidacznia dostosowywalne środowisko użytkownika instalacji. Ten samouczek jest kontynuacją samouczka Tworzenie usługi systemu Windows. Pokazano w nim, jak utworzyć instalatora dla usługi systemu Windows platformy .NET.

Z tego samouczka dowiesz się, jak wykonywać następujące czynności:

Zainstaluj rozszerzenie Instalator programu Visual Studio Projects.
Utwórz projekt instalacyjny.
Zaktualizuj istniejący projekt procesu roboczego platformy .NET, aby obsługiwał instalację.
Zautomatyzuj instalację i odinstalowywanie za pomocą Menedżera sterowania usługami systemu Windows.

Wymagania wstępne

Oczekuje się, że ukończysz samouczek Tworzenie usługi systemu Windows lub przygotujesz się do sklonowania przykładowego repozytorium.
Zestaw .NET 8.0 SDK lub nowszy
System operacyjny Windows
Zintegrowane środowisko projektowe (IDE) platformy .NET
- Korzystanie z programu Visual Studio jest bezpłatne
Istniejąca usługa systemu Windows platformy .NET

Zacznij od zainstalowania zestawu narzędzi Wix. Zestaw narzędzi Wix to zestaw narzędzi, które tworzą pakiety instalacyjne systemu Windows z kodu źródłowego XML.

dotnet tool install --global wix

Następnie zainstaluj rozszerzenie HeatWave dla programu VS2022. Po zainstalowaniu uruchom ponownie program Visual Studio i zobaczysz dostępne nowe szablony projektów.

Pobieranie istniejącego projektu

Ten samouczek jest oparty na aplikacji utworzonej w ramach samouczka Tworzenie usługi systemu Windows przy użyciu usługi BackgroundService . Możesz sklonować przykładowe repozytorium lub użyć aplikacji utworzonej w poprzednim samouczku.

Napiwek

Cały przykładowy kod źródłowy "Pracownicy na platformie .NET" jest dostępny w przeglądarce Samples Browser do pobrania. Aby uzyskać więcej informacji, zobacz Przeglądanie przykładów kodu: Procesy robocze na platformie .NET.

Zestaw narzędzi Wix
Rozszerzenie instalatora firmy Microsoft

Otwórz rozwiązanie w programie Visual Studio i wybierz pozycję F5 , aby upewnić się, że aplikacja kompiluje i działa zgodnie z oczekiwaniami. Naciśnij klawisze Ctrl+C, aby zatrzymać aplikację.

Obsługa przełączników instalacji

Aplikacja usługi systemu Windows musi obsługiwać przełączniki instalacyjne. Projekt instalacyjny wywoła aplikację usługi systemu Windows z odpowiednio przełącznikami /Install i /Uninstall podczas instalacji i odinstalowywania. Gdy te przełączniki są obecne, aplikacja będzie działać inaczej, ponieważ będzie wykonywać instalację lub dezinstalację tylko przy użyciu pliku wykonywalnego menedżera kontroli usług systemu Windows (sc.exe).

Aby aplikacja wywołała oddzielny proces, zainstaluj pakiet NuGet CliWrap jako wygodę. Aby zainstalować CliWrap pakiet, użyj dotnet add package polecenia :

dotnet add App.WindowsService.csproj package CliWrap

Aby uzyskać więcej informacji, zobacz dotnet add package (Dodawanie pakietu dotnet).

Po CliWrap zainstalowaniu otwórz plik App.WindowsService Program.cs projektu. Po instrukcji using , ale przed utworzeniem IHost dodaj następujący kod:

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

Powyższy kod ma następujące działanie:

Deklaruje nazwę usługi jako const string wartość.
args Sprawdza wartość pojedynczej wartości.
Pobiera ścieżkę pliku wykonywalnego z pliku AppContext.BaseDirectory.
Gdy "/Install" przełącznik jest obecny, sc create ".NET Joke Service" binPath="path/to/App.WindowsService.exe" start=auto jest wywoływany.
"/Uninstall" Gdy przełącznik jest obecny i sc stop ".NET Joke Service"sc delete ".NET Joke Service" jest wywoływany.

Gdy nie ma żadnych przełączników instalacji, aplikacja zachowuje się tak, jak wcześniej, ale teraz zawiera funkcje instalacji.

Uwaga

Definiowanie akcji niestandardowych i ręczne obsługiwanie przełączników instalacyjnych jest uznawane za antywzór. Chociaż ta dokumentacja pokazuje, jak to zrobić, warto rozważyć użycie zestawu narzędzi Wix innej firmy.

Dodawanie nowego projektu instalacyjnego

Zestaw narzędzi Wix
Rozszerzenie instalatora firmy Microsoft

Aby dodać nowy projekt instalacyjny Wix, kliknij prawym przyciskiem myszy rozwiązanie w Eksplorator rozwiązań i wybierz polecenie Dodaj > nowy projekt:

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

Wybierz pozycję Pakiet MSI (Wix v4) z dostępnych szablonów, a następnie wybierz pozycję Dalej. Podaj żądaną nazwę i lokalizację, a następnie wybierz pozycję Utwórz.

Konfigurowanie projektu instalatora

Zestaw narzędzi Wix
Rozszerzenie instalatora firmy Microsoft

Aby skonfigurować projekt instalacyjny, należy najpierw dodać odwołanie do App.WindowsService projektu. Kliknij prawym przyciskiem myszy projekt instalacyjny w Eksplorator rozwiązań, a następnie wybierz polecenie Dodaj > odwołanie do projektu.

Szablon zawiera przykładowe pliki składników i lokalizacji. Usuń te pliki, pozostawiając tylko plik Package.wxs . Projekt powinien teraz zawierać ProjectReference element podobny do następującego:

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

Po dodaniu odwołania do projektu skonfiguruj plik Package.wxs . Otwórz plik w edytorze, a następnie zastąp zawartość następującym kodem:

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

Podczas kompilowania projektu dane wyjściowe to plik MSI, którego można użyć do zainstalowania i odinstalowania usługi.

Aby skonfigurować projekt instalatora, wybierz projekt w Eksplorator rozwiązań. Wybierz klawisz F4 , aby otworzyć okienko właściwości projektu. Możesz skonfigurować ikony "dodaj" i "usuń" aplikacji, autora, producenta, nazwę produktu, tytuł, platformę docelową itd.

Installer project properties pane.

Projekt instalatora musi zdefiniować dwie akcje niestandardowe na potrzeby zachowania instalacji. Kliknij prawym przyciskiem myszy projekt w Eksplorator rozwiązań, a następnie wybierz pozycję Wyświetl > akcje niestandardowe.

Installer project Custom Actions context menu.

W oknie Akcje niestandardowe wybierz pozycję Zainstaluj > dodaj akcję niestandardową.

Custom Actions properties dialog: select item.

Kliknij dwukrotnie folder aplikacji (lub wybierz pozycję Dodaj dane wyjściowe... z wybraną pozycją Folder aplikacji), a następnie wybierz pozycję Publikuj elementy z pozycji App.WindowsService (Aktywny).

Custom Actions properties dialog: select item app folder.

Wybierz przycisk OK , aby potwierdzić wybór. Kliknij prawym przyciskiem myszy dodane elementy publikowania z węzła App.WindowsService (Aktywne) w obszarze Zainstaluj, a następnie wybierz pozycję Właściwości.

Publish items properties.

Dodaj /Install do argumentów. Wykonaj te same kroki dla polecenia Odinstaluj, dodając /Uninstall argumenty.

Po wykonaniu obu tych czynności powinny zostać wyświetlone następujące elementy:

Custom Actions with Install and Uninstall actions defined.

Dzięki tym aktualizacjom projekt instalacyjny został skonfigurowany do delegowania akcji Instalowanie i odinstalowywanie w celu wywołania aplikacji usługi systemu Windows z odpowiednimi argumentami.

Instalacja testowa

Zestaw narzędzi Wix
Rozszerzenie instalatora firmy Microsoft

Aby przetestować instalator, opublikuj projekt App.WindowsService . Kliknij prawym przyciskiem myszy projekt w Eksplorator rozwiązań, a następnie wybierz pozycję Publikuj. Po opublikowaniu przy użyciu profilu utworzonego w poprzednim samouczku plik wykonywalny będzie znajdować się w katalogu publikowania. Następnie skompilujesz projekt instalacyjny i uruchomisz instalatora.

Musisz uruchomić instalację jako administrator. W tym celu kliknij prawym przyciskiem myszy plik MSI, a następnie wybierz polecenie Uruchom jako administrator.

Po zainstalowaniu usługi możesz otworzyć usługę, aby wyświetlić uruchomioną usługę. Aby odinstalować usługę, użyj funkcji Dodaj lub Usuń programy systemu Windows, aby wywołać instalatora.

Udostępnij za pośrednictwem