Creación de un instalador de servicio de Windows

Artículo
12/13/2023

Al crear un servicio de Windows de .NET (no confundir con un servicio de Windows de .NET Framework), es posible que quiera crear también un instalador para el servicio. Sin un instalador, los usuarios tendrían que saber cómo instalar y configurar el servicio. Un instalador agrupa los ejecutables de la aplicación y ofrece una experiencia de usuario de instalación personalizable. Este tutorial es una continuación del tutorial Creación de un servicio de Windows. Muestra cómo crear un instalador para el servicio Windows de .NET.

En este tutorial, aprenderá a:

Instalar la extensión Visual Studio Installer Projects.
Crear un proyecto de instalación.
Actualizar un proyecto de trabajo de .NET existente para admitir la instalación.
Automatizar la instalación y desinstalación con el Administrador de control de servicios de Windows.

Requisitos previos

Se espera que haya completado el tutorial Creación de un servicio de Windows o esté preparado para clonar el repositorio de ejemplo.
El SDK de .NET 8.0 o posterior
Un sistema operativo Windows
Un entorno de desarrollo integrado (IDE) de .NET
- No dude en usar Visual Studio
Un servicio de Windows de .NET existente

Instalación de dependencias de herramientas

Conjunto de herramientas de WiX
Extensión del instalador de Microsoft

Empiece por instalar el conjunto de herramientas de Wix. El conjunto de herramientas de Wix es un conjunto de herramientas que crean paquetes de instalación de Windows a partir del código fuente XML.

dotnet tool install --global wix

A continuación, instale la extensión de HeatWave para VS2022. Después de instalarla, reinicie Visual Studio y verá que hay nuevas plantillas de proyecto disponibles.

Obtención del proyecto existente

Este tutorial se basa en la aplicación creada como parte del tutorial Creación de un servicio de Windows mediante BackgroundService. Puede clonar el repositorio de ejemplo o usar la aplicación que creó en el tutorial anterior.

Sugerencia

Todo el ejemplo de "Trabajos en .NET" está disponible en el Explorador de ejemplos para su descarga. Para obtener más información, consulte Examinación de ejemplos de código: Trabajos en .NET.

Conjunto de herramientas de WiX
Extensión del instalador de Microsoft

Abra la solución en Visual Studio y seleccione F5 para asegurarse de que la aplicación se compila y se ejecuta según lo previsto. Presione CTRL+C para detener la aplicación.

Control de los modificadores de instalación

La aplicación servicio de Windows debe controlar los modificadores de instalación. El proyecto de instalación llamará a la aplicación de servicio de Windows con los modificadores /Install y /Uninstall durante la instalación y desinstalación, respectivamente. Cuando estos modificadores estén presentes, la aplicación se comportará de forma diferente, ya que solo realizará la instalación o desinstalación mediante el ejecutable del Administrador de control de servicios de Windows (sc.exe).

Para que la aplicación llame a un proceso independiente, instale el paquete NuGet CliWrap para mayor comodidad. Para instalar el paquete CliWrap, use el comando dotnet add package:

dotnet add App.WindowsService.csproj package CliWrap

Para más información, consulte dotnet add package.

Una vez instalado CliWrap, abra el archivo Program.cs del proyecto App.WindowsService. Agregue el código siguiente después de las instrucciones using, pero antes de que se cree 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;
}

El código anterior:

Declara el nombre del servicio como un valor const string.
Comprueba si hay un valor único en args.
Obtiene la ruta de acceso del archivo ejecutable de AppContext.BaseDirectory.
Cuando el modificador "/Install" está presente, se llama a sc create ".NET Joke Service" binPath="path/to/App.WindowsService.exe" start=auto.
Cuando el modificador "/Uninstall" está presente, se llama a sc stop ".NET Joke Service" y sc delete ".NET Joke Service".

Cuando no hay modificadores de instalación presentes, la aplicación se comporta como antes, pero ahora incluye la funcionalidad de instalación.

Nota

La definición de acciones personalizadas y el control manual de conmutadores de instalación se considera un antipatrón. Aunque en esta documentación se muestra cómo hacerlo, puede que desee considerar el uso del conjunto de herramientas de WiX de terceros en su lugar.

Adición de un nuevo proyecto de instalación

Conjunto de herramientas de WiX
Extensión del instalador de Microsoft

Para agregar un nuevo proyecto de instalación de Wix, haga clic con el botón derecho en la solución en el Explorador de soluciones y seleccione Agregar > Nuevo proyecto:

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

Seleccione Paquete MSI (Wix v4) en las plantillas disponibles y, a continuación, seleccione Siguiente. Proporcione el nombre y la ubicación deseados y, después, seleccione Crear.

Para configurar el proyecto de instalación, primero debe agregar una referencia al proyecto App.WindowsService. Haga clic con el botón derecho en el proyecto de instalación en el Explorador de soluciones y seleccione Agregar > Referencia de proyecto.

La plantilla incluye archivos de componente y localización de ejemplo. Elimine estos archivos y deje solo el archivo Package.wxs. El proyecto ahora debe incluir un elemento ProjectReference similar al siguiente:

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

Una vez agregada la referencia del proyecto, configure el archivo Package.wxs. Abra el archivo en el editor y reemplace el contenido por lo siguiente:

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

Al compilar el proyecto, la salida es un archivo MSI que se puede usar para instalar y desinstalar el servicio.

Para configurar el proyecto de instalación, seleccione el proyecto en el Explorador de soluciones. Seleccione F4 para abrir el panel de propiedades del proyecto. Puede configurar los iconos "agregar" y "quitar" de la aplicación, el autor, el fabricante, el nombre del producto, el título, la plataforma de destino, etc.

Installer project properties pane.

El proyecto de instalador debe definir dos acciones personalizadas para el comportamiento de instalación. Haga clic con el botón derecho en el proyecto en el Explorador de soluciones y seleccione Ver > Acciones personalizadas.

Installer project Custom Actions context menu.

En la ventana Acciones personalizadas, seleccione Instalar > Agregar acción personalizada.

Custom Actions properties dialog: select item.

Haga doble clic en Carpeta de aplicación (o seleccione Agregar salida... con Carpeta de aplicación seleccionado) y seleccione Publicar elementos de App.WindowsService (Activo).

Custom Actions properties dialog: select item app folder.

Seleccione Aceptar para confirmar la selección. Haga clic con el botón derecho en el nodo Publish Items from App.WindowsService (Active) en Instalar y seleccione Propiedades.

Publish items properties.

Agregue /Install en Argumentos. Siga estos mismos pasos en Desinstalar, agregando /Uninstall en Argumentos.

Una vez que haya terminado, debería ver lo siguiente:

Custom Actions with Install and Uninstall actions defined.

Con estas actualizaciones, el proyecto de instalación se ha configurado para delegar sus acciones Instalar y Desinstalar para llamar a la aplicación servicio de Windows con los argumentos adecuados.

Prueba de la instalación

Conjunto de herramientas de WiX
Extensión del instalador de Microsoft

Para probar el instalador, publique el proyecto App.WindowsService. Haga clic con el botón derecho en el proyecto en el Explorador de soluciones y seleccione Publicar. Una vez publicado con el perfil que creó en el tutorial anterior, el ejecutable estará en el directorio publish. A continuación, compile el proyecto de instalación y ejecute el instalador.

Debe ejecutar la instalación como administrador. Para ello, haga clic con el botón derecho en el archivo .msi y, a continuación, seleccione Ejecutar como administrador.

Una vez instalado el servicio, puede abrir Servicios para ver el servicio en ejecución. Para desinstalar el servicio, use la característica Agregar o quitar programas de Windows para llamar al instalador.

Compartir a través de