Criar um instalador do serviço Windows

Artigo
12/18/2023

Ao criar um serviço Windows do .NET (não confunda com um serviço Windows do .NET Framework), convém criar um instalador para seu serviço. Sem um instalador, os usuários teriam que saber como instalar e configurar seu serviço. Um instalador agrupa os executáveis do aplicativo e expõe uma experiência de usuário de instalação personalizável. Este tutorial é uma continuação do tutorial Criar um serviço Windows. Ele mostra como criar um instalador para o serviço Windows .NET.

Neste tutorial, você aprenderá como:

Instale a extensão Projetos do Instalador do Visual Studio.
Crie um projeto de instalação.
Atualize um projeto existente de trabalho do .NET para dar suporte à instalação.
Automatize a instalação e a desinstalação com o Gerenciador de Controle de Serviço do Windows.

Pré-requisitos

Espera-se que você tenha concluído o tutorial Criar um serviço Windows ou esteja preparado para clonar o repositório de exemplo.
O SDK do .NET 8.0 ou posterior
Sistema operacional Windows
Um ambiente de desenvolvimento integrado do .NET (IDE)
- Fique à vontade para usar o Visual Studio
Um serviço Windows do .NET existente

Comece instalando o Conjunto de Ferramentas Wix. O Conjunto de Ferramentas Wix é um conjunto de ferramentas que cria pacotes de instalação do Windows por meio de código-fonte XML.

dotnet tool install --global wix

Em seguida, instale a extensão HeatWave para VS2022. Após a instalação, reinicie o Visual Studio e você verá novos modelos de projeto disponíveis.

Obter projeto existente

Este tutorial se baseia no aplicativo criado como parte do tutorial Criar um serviço Windows usando BackgroundService. Você pode clonar o repositório de exemplo ou usar o aplicativo criado no tutorial anterior.

Dica

Todo o código-fonte do exemplo dos “Trabalhos no .NET” está disponível no Navegador de Exemplos para download. Para obter mais informações, confira Procurar exemplos de código: Trabalhos no .NET.

Conjunto de Ferramentas Wix
Extensão do instalador da Microsoft

Abra a solução no Visual Studio e selecione F5 para garantir que o aplicativo seja compilado e executado conforme o esperado. Pressione Ctrl+C para interromper o aplicativo.

Gerenciar comutadores de instalação

O aplicativo do serviço Windows precisa gerenciar os comutadores de instalação. O projeto de instalação chamará o aplicativo do serviço Windows com os comutadores /Install e /Uninstall durante a instalação e a desinstalação, respectivamente. Quando esses comutadores estiverem presentes, o aplicativo se comportará de maneira diferente, pois só executará a instalação ou a desinstalação usando o executável do Gerenciador de Controle de Serviço do Windows (sc.exe).

Para que o aplicativo chame um processo separado, instale o pacote NuGet CliWrap para fins de conveniência. Para instalar o pacote CliWrap, use o comando dotnet add package:

dotnet add App.WindowsService.csproj package CliWrap

Para obter mais informações, confira dotnet add package.

Após instalar o CliWrap, abra o arquivo Program.cs do projeto App.WindowsService. Depois das instruções using, mas antes da criação de IHost, adicione o seguinte código:

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

O código anterior:

Declara o nome do serviço como um valor const string.
Verifica se há um único valor em args.
Obtém o caminho executável do AppContext.BaseDirectory.
Quando o comutador "/Install" está presente, sc create ".NET Joke Service" binPath="path/to/App.WindowsService.exe" start=auto é chamado.
Quando o comutador "/Uninstall" está presente, sc stop ".NET Joke Service" e sc delete ".NET Joke Service" são chamados.

Quando nenhum comutador de instalação está presente, o aplicativo se comporta como antes, mas agora inclui a funcionalidade de instalação.

Observação

Definir ações personalizadas e gerenciar manualmente os comutadores de instalação é considerado um antipadrão. Embora esta documentação demonstre como fazer isso, prefira usar o Conjunto de Ferramentas Wix de terceiros.

Adicionar novo projeto de instalação

Conjunto de Ferramentas Wix
Extensão do instalador da Microsoft

Para adicionar um novo projeto de instalação do Wix, clique com o botão direito do mouse na solução no Gerenciador de Soluções e selecione Adicionar > Novo Projeto:

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

Selecione Pacote MSI (Wix v4) dentre os modelos disponíveis e escolha Avançar. Forneça o Nome e a Localização desejados e selecione Criar.

Configurar o projeto do instalador

Conjunto de Ferramentas Wix
Extensão do instalador da Microsoft

Para configurar o projeto de instalação, primeiro você deve adicionar uma referência ao projeto App.WindowsService. Clique com o botão direito do mouse no projeto de instalação no Gerenciador de Soluções e selecione Adicionar > Referência de Projeto.

O modelo inclui componente de exemplo e arquivos de localização. Exclua esses arquivos, deixando apenas o Package.wxs. Seu projeto agora deve incluir um elemento ProjectReference, semelhante ao seguinte:

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

Depois que a referência do projeto tiver sido adicionada, configure o arquivo Package.wxs. Abra o arquivo no editor e substitua o conteúdo pelo seguinte:

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

Quando você cria o projeto, a saída é um arquivo MSI que pode ser usado para instalar e desinstalar o serviço.

Para configurar o instalador do projeto, selecione o projeto no Gerenciador de Soluções. Selecione F4 para abrir o painel de propriedades do projeto. Você pode configurar os ícones "adicionar" e "remover" do aplicativo, bem como autor, fabricante, nome do produto, título, plataforma de destino e assim por diante.

Installer project properties pane.

O projeto do instalador precisa definir duas ações personalizadas para o comportamento de instalação. Clique com o botão direito do mouse no projeto no Gerenciador de Soluções e selecione Exibir > Ações Personalizadas.

Installer project Custom Actions context menu.

Na janela Ações Personalizadas, selecione Instalar > Adicionar Ação Personalizada.

Custom Actions properties dialog: select item.

Clique duas vezes na Pasta do Aplicativo (ou selecione Adicionar Saída... com a Pasta do Aplicativo selecionada) e escolha Publicar Itens por meio do App.WindowsService (Ativo).

Custom Actions properties dialog: select item app folder.

Selecione Ok para confirmar a seleção. Clique com o botão direito do mouse no nó Publicar Itens do App.WindowsService (Ativo) adicionado em Instalar e selecione Propriedades.

Publish items properties.

Adicione /Install aos Argumentos. Siga estas mesmas etapas para Desinstalar, adicionando /Uninstall aos Argumentos.

Depois de realizar as duas etapas, você deverá ver o seguinte:

Custom Actions with Install and Uninstall actions defined.

Com essas atualizações, o projeto de instalação foi configurado para delegar as ações Instalar e Desinstalar para chamar o aplicativo do serviço Windows com os argumentos apropriados.

Instalação de teste

Conjunto de Ferramentas Wix
Extensão do instalador da Microsoft

Para testar o instalador, publique o projeto App.WindowsService. Clique com o botão direito do mouse no projeto no Gerenciador de Soluções e selecione Publicar. Depois de publicado com o perfil criado no tutorial anterior, o executável será salvo no diretório de publicação. Em seguida, você Compila o projeto de instalação e executa o instalador.

Você precisa executar a instalação como administrador. Para isso, clique com o botão direito do mouse no arquivo MSI e selecione Executar como administrador.

Depois que o serviço for instalado, você poderá abrir Serviços para ver o serviço em execução. Para desinstalar o serviço, use o recurso Adicionar ou Remover Programas do Windows para chamar o instalador.

Compartilhar via