建立 Windows 服務安裝程式

當您建立 .NET Windows 服務 (請勿誤認為 .NET Framework Windows 服務) 時，您可能會想要為服務建立安裝程式。 如果沒有安裝程式，則使用者必須知道如何安裝和設定您的服務。 安裝程式會組合應用程式的可執行檔，並公開可自訂的安裝使用者體驗。 本教學課程是 建立 Windows 服務 教學課程的接續。 它會示範如何為您的 .NET Windows 服務建立安裝程式。

在本教學課程中，您將了解如何：

• 安裝 Visual Studio Installer 專案擴充功能。
• 建立安裝專案。
• 更新現有的 .NET 背景工作角色專案以支援安裝。
• 使用 Windows 服務控制管理員自動安裝與解除安裝。

必要條件

• 預期您已完成 建立 Windows 服務 教學課程，或已準備就緒來複製範例存放庫。
• .NET 8.0 SDK 或更新版本
• Windows 作業系統
• .NET 整合式開發環境 (IDE)
  • 歡迎使用 Visual Studio
• 現有的 .NET Windows 服務

安裝工具相依性

WiX 工具組

從安裝 Wix 工具組開始。 Wix 工具組是一組工具，可從 XML 組建 Windows 安裝套件。

dotnet tool install --global wix

接下來，安裝 適用於 VS2022 擴充功能的 HeatWave。 安裝之後，請重新啟動 Visual Studio，您會看到可用的新專案範本。

Microsoft 安裝程式延伸模組

安裝 Microsoft Visual Studio Installer 專案擴充功能。 安裝之後，請重新啟動 Visual Studio，您會看到可用的新專案範本。

取得現有專案

本教學課程是以 使用 BackgroundService 建立 Windows 服務 教學課程內容中建立的應用程式為基礎。 您可以複製範例存放庫，或使用您在上一個教學課程中建置的應用程式。

提示

所有「.NET 中的背景工作角色」範例原始程式碼都可在 [範例瀏覽器] 中下載。 如需詳細資訊，請參閱 瀏覽程式碼範例: .NET 中的背景工作角色。

WiX 工具組

在 Visual Studio 中開啟方案，然後選取 F5 以確保應用程式會如預期般建置和執行。 按 Ctrl+C 來停止應用程式。

Microsoft 安裝程式延伸模組

在 Visual Studio 中開啟方案，然後選取 F5 以確保應用程式會如預期般建置和執行。 按 Ctrl+C 來停止應用程式。

處理安裝參數

Windows 服務應用程式需要處理安裝參數。 安裝程式專案會分別在安裝和解除安裝期間，使用 /Install 和 /Uninstall 參數來呼叫 Windows 服務應用程式。 當這些參數存在時，應用程式的行為會有所不同，只會使用 Windows Service Control Manager 可執行檔 (sc.exe) 執行安裝或解除安裝。

若要讓應用程式呼叫個別的程式，請安裝 CliWrap NuGet 套件，以方便起見。 若要安裝 CliWrap 套件，請使用 dotnet add package 命令：

dotnet add App.WindowsService.csproj package CliWrap

如需詳細資訊，請參閱 dotnet add package。

安裝 CliWrap 後，開啟 App.WindowsService 專案的 Program.cs 檔案。 在 using 陳述式後，但在建立 IHost 前，新增下列程式碼：

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

上述 程式碼：

• 將服務名稱宣告為 const string 值。
• 檢查 args 是否有單一值。
• 從 AppContext.BaseDirectory 取得可執行檔路徑。
• 當 "/Install" 參數存在時，會呼叫 sc create ".NET Joke Service" binPath="path/to/App.WindowsService.exe" start=auto。
• 當 "/Uninstall" 參數存在時，會呼叫 sc stop ".NET Joke Service" 和 sc delete ".NET Joke Service"。

當沒有任何安裝參數存在時，應用程式的行為就如同先前一樣，但現在包含安裝功能。

注意

定義自訂動作，而手動處理安裝切換會被視為反模式。 雖然本文件示範了如何執行，但您可能想要考慮改用第三方 Wix工具組。

新增安裝專案

WiX 工具組

若要新增 Wix 設定專案，請以滑鼠右鍵按一下 [方案總管] 中的解決方案，然後選取 [新增] > [新專案]:

從可用的範本中選取 [MSI 套件 (Wix v4)]， 然後選取 [下一步]。 提供所需的 [名稱] 和 [位置]，然後選取 [建立]。

Microsoft 安裝程式延伸模組

若要新增安裝專案，請以滑鼠右鍵按一下 [方案總管] 中的方案，然後選取 [新增] > [新增專案]：

從可用的範本中選取 [設定專案]，然後選取 [下一步]。 提供所需的 [名稱] 和 [位置]，然後選取 [建立]。

設定安裝程式專案

WiX 工具組

若要設定安裝專案，您必須先新增 App.WindowsService 專案的參考。 以滑鼠右鍵按一下 [方案總管]，然後選取 [新增]>[專案參考]。

範本包含元件和當地語系化檔案的範例。 刪除這些檔案，只保留 Package.wxs 檔案。 您的專案現在應該包含 ProjectReference 元素，類似下方所示:

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

新增項目參考之後，請設定 Package.wxs 檔案。 在編輯器開啟檔案，並以下列內容取代:

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

當您組建專案時，輸出是 MSI 檔案，可用來安裝和解除安裝服務。

Microsoft 安裝程式延伸模組

若要設定安裝專案，請選取 [方案總管] 中的專案。 選取 F4 以開啟專案屬性窗格。 您可以設定應用程式的「新增」和「移除」圖示、作者、製造商、產品名稱、標題、目標平台等等。

安裝程式專案需要針對安裝行為定義兩個自訂動作。 以滑鼠右鍵按一下 [方案總管] 中的專案，然後選取 [檢視] > [自訂動作]。

從 [自訂動作] 視窗中，選取 [安裝] > [新增自訂動作]。

按兩下 [應用程式資料夾] (或選取 [新增輸出...]，並選取 [應用程式資料夾])，然後選取 [從 App.WindowsService (Active) 發佈項目]。

選取 [確定] 以確認選取項目。 以滑鼠右鍵按一下 [安裝] 底下的 [從 App.WindowsService (Active) 發佈項目] 節點，然後選取 [屬性]。

將 /Install 新增至「引數」。 請遵循和「解除安裝」相同的步驟，將 /Uninstall 新增至「引數」。

完成這兩項作業之後，您應該會看到下列內容：

透過這些更新，安裝程式專案已設定為委派其「安裝」和「解除安裝」動作，以適當引數呼叫 Windows Service 應用程式。

測試安裝

WiX 工具組

若要測試安裝程式，請發佈 App.WindowsService 專案。 以滑鼠右鍵按一下 [方案總管] 中的專案，然後選取 [發佈]。 一旦以您在上一個教學課程中建立的設定檔發行之後，可執行檔將會位於發佈目錄中。 接下來，您會 組建 設定專案並執行安裝程式。

您必須以系統管理員身分執行安裝。 若要這麼做，請在 MSI 檔案上按一下滑鼠右鍵，然後選取 [以系統管理員身分執行]。

安裝服務之後，您可以開啟 [服務] 來查看執行中的服務。 若要解除安裝服務，請使用 [Windows 新增或移除程式] 功能來呼叫安裝程式。

Microsoft 安裝程式延伸模組

若要測試安裝程式，請展開 Visual Studio 中的 [方案組態]，然後選取 [發行] (假設已選取 [偵錯])。 組建解決方案，然後以滑鼠右鍵按一下安裝專案，然後選取 [建置]。 根據預設，安裝專案不是組建的一部分。

選取 [檢視] > [輸出]，並確定 [顯示來自以下位置的輸出] 下拉式清單已選取 [建置]。 會顯示 Microsoft Installer (MSI) 檔案路徑。 複製路徑，然後開啟安裝程式。 執行安裝程式。

您必須以系統管理員身分執行安裝。 若要這麼做，請在 MSI 檔案上按一下滑鼠右鍵，然後選取 [以系統管理員身分執行]。

1.安裝程式歡迎對話框

2.安裝程式選取資料夾對話框

3.安裝程式確認對話框

4.安裝程式完成對話框

安裝服務之後，您可以開啟 [服務] 來啟動服務。 若要解除安裝服務，請使用 [Windows 新增或移除程式] 功能來呼叫安裝程式。

另請參閱

• .NET 中的背景工作服務
• 建立佇列服務
• 在 BackgroundService 中使用範圍服務
• 實作 IHostedService 介面