创建 Windows 服务安装程序

创建 .NET Windows 服务（不要与 .NET Framework Windows 服务混淆）时，你可能希望为服务创建一个安装程序。 如果没有安装程序，用户就必须知道如何安装和配置服务。 安装程序将捆绑应用的可执行文件，并提供自定义安装用户体验。 本教程是创建 Windows 服务教程的延续。 它演示如何为 .NET Windows 服务创建安装程序。

本教程介绍以下操作：

• 安装 Visual Studio 安装程序项目扩展。
• 创建安装项目。
• 更新现有的 .NET 辅助角色项目以支持安装。
• 使用 Windows 服务控制管理器自动安装和卸载。

先决条件

• 你应已完成创建 Windows 服务教程，或准备好克隆示例存储库。
• .NET 8.0 SDK 或更高版本
• Windows OS
• .NET 集成开发环境 (IDE)
  • 随意使用 Visual Studio
• 现有的 .NET Windows 服务

安装工具依赖项

Wix 工具集

首先安装 Wix 工具集。 Wix 工具集是从 XML 源代码生成 Windows 安装包的一组工具。

dotnet tool install --global wix

接下来，安装 HeatWave for VS2022 扩展。 安装后，重启 Visual Studio，你将看到可用的新项目模板。

Microsoft 安装程序扩展

安装 Microsoft Visual Studio 安装程序项目扩展。 安装后，重启 Visual Studio，你将看到可用的新项目模板。

获取现有项目

本教程基于使用 BackgroundService 创建 Windows 服务教程中创建的应用。 可以克隆示例存储库，也可以使用在上一教程中生成的应用。

提示

所有“.NET 中的辅助角色”示例源代码都可以在示例浏览器中下载。 有关详细信息，请参阅浏览代码示例：.NET 中的辅助角色。

Wix 工具集

在 Visual Studio 中打开解决方案，然后选择 F5 以确保应用按预期生成和运行。 按 Ctrl+C 可停止应用。

Microsoft 安装程序扩展

在 Visual Studio 中打开解决方案，然后选择 F5 以确保应用按预期生成和运行。 按 Ctrl+C 可停止应用。

处理安装开关

Windows 服务应用需要处理安装开关。 安装项目将在安装和卸载期间分别使用 /Install 和 /Uninstall 开关调用 Windows 服务应用。 存在这些开关时，应用的行为会有所不同，因为应用仅使用 Windows 服务控制管理器可执行文件 (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 发布项(活动)”。

选择“确定”确认选择。 右键单击“安装”下添加的“从 App.WindowsService 发布项(活动)”节点，然后选择“属性”。

将 /Install 添加到“参数”。 对“卸载”执行相同的步骤，将 /Uninstall 添加到“参数”。

完成这两项操作后，应会看到以下内容：

通过这些更新，安装项目已配置为委托其“安装”和“卸载”操作，以使用适当的参数调用 Windows 服务应用。

测试安装

Wix 工具集

若要测试安装程序，请发布 App.WindowsService 项目。 在“解决方案资源管理器”中右键单击该项目，然后选择“发布”。 使用在上一教程中创建的配置文件发布后，可执行文件将位于发布目录中。 接下来，生成安装项目并运行安装程序。

需要以管理员身份运行安装。 为此，请右键单击 MSI 文件，然后选择“以管理员身份运行”。

安装服务后，可以打开“服务”来运行该服务。 若要卸载该服务，请使用“Windows 添加或删除程序”功能调用安装程序。

Microsoft 安装程序扩展

若要测试安装程序，请在 Visual Studio 中展开“解决方案配置”，然后选择“发布”（假设已选中“调试”）。 生成解决方案，然后右键单击安装项目并选择“生成”。 默认情况下，安装项目不是生成的一部分。

选择“查看”>“输出”，并确保“显示输出来源”下拉菜单中已选择“生成”。 将显示 Microsoft Installer (MSI) 文件路径。 复制路径并打开安装程序。 运行安装程序。

需要以管理员身份运行安装。 为此，请右键单击 MSI 文件，然后选择“以管理员身份运行”。

1. 安装程序欢迎对话框

2. 安装程序选择文件夹对话框

3. 安装程序确认对话框

4. 安装程序完成对话框

安装服务后，可以打开“服务”来启动该服务。 若要卸载该服务，请使用“Windows 添加或删除程序”功能调用安装程序。

另请参阅

• .NET 中的辅助角色服务
• 创建队列服务
• 在 BackgroundService 内使用作用域服务
• 实现 IHostedService 接口