Criar um instalador de serviço do Windows

Artigo
12/15/2023

Quando você cria um serviço do Windows .NET (não deve ser confundido com um serviço do Windows do .NET Framework), convém criar um instalador para o 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 seu 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 do Windows. Ele mostra como criar um instalador para o seu serviço .NET Windows.

Neste tutorial, irá aprender a:

Instale a extensão Visual Studio Installer Projects.
Crie um projeto de configuração.
Atualize um projeto existente do .NET Worker para dar suporte à instalação.
Automatize a instalação e a desinstalação com o Gerenciador de Controle de Serviços do Windows.

Pré-requisitos

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

Comece instalando o Wix Toolset. O Wix Toolset é um conjunto de ferramentas que criam pacotes de instalação do Windows a partir do código-fonte XML.

dotnet tool install --global wix

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

Obter projeto existente

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

Gorjeta

Todo o código-fonte de exemplo "Workers in .NET" está disponível no Navegador de Amostras para download. Para obter mais informações, consulte Procurar exemplos de código: Trabalhadores 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 parar o aplicativo.

Manipular comutadores de instalação

O aplicativo de Serviço do Windows precisa lidar com opções de instalação. O projeto de instalação chamará o aplicativo de Serviço do Windows com /Install e alternará durante a instalação e /Uninstall a desinstalação, respectivamente. Quando essas opções estiverem presentes, o aplicativo se comportará de forma diferente, pois só executará a instalação ou desinstalação usando o executável do Gerenciador de Controle de Serviços do Windows (sc.exe).

Para que o aplicativo chame um processo separado, instale o pacote NuGet CliWrap como uma conveniência. Para instalar o pacote, use o CliWrapdotnet add package comando:

dotnet add App.WindowsService.csproj package CliWrap

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

Com CliWrap instalado, abra o arquivo Program.cs do App.WindowsService projeto. Após as using instruções, mas antes de ser IHost criado, 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 const string valor.
Verifica se há args um único valor.
Obtém o caminho executável do AppContext.BaseDirectory.
Quando o "/Install" interruptor está presente, sc create ".NET Joke Service" binPath="path/to/App.WindowsService.exe" start=auto é chamado.
Quando o "/Uninstall" interruptor está presente sc stop ".NET Joke Service" e sc delete ".NET Joke Service" são chamados.

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

Nota

Definir ações personalizadas e manipular manualmente as opções de instalação é considerado um antipadrão. Embora esta documentação demonstre como fazê-lo, convém considerar o uso do Wix Toolset de terceiros.

Adicionar novo projeto de configuração

Conjunto de ferramentas Wix
Extensão do instalador da Microsoft

Para adicionar um novo projeto de configuraçã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) nos modelos disponíveis e, em seguida, selecione Avançar. Forneça o Nome e o Local desejados e selecione Criar.

Configurar projeto de instalação

Conjunto de ferramentas Wix
Extensão do instalador da Microsoft

Para configurar o projeto de instalação, você primeiro deve adicionar uma referência ao App.WindowsService projeto. 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 componentes de exemplo e arquivos de localização. Exclua estes, arquivos deixando apenas o arquivo Package.wxs . Seu projeto agora deve incluir um ProjectReference elemento 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 ficheiro no editor e, em seguida, 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 projeto do instalador, 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, 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 selecione Publicar Itens 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 estes mesmos passos para Desinstalar, adicionando /Uninstall aos Argumentos.

Depois de fazer as duas coisas, você verá o seguinte:

Custom Actions with Install and Uninstall actions defined.

Com essas atualizações, o projeto de instalação foi configurado para delegar suas ações de Instalação e Desinstalação para chamar o aplicativo de Serviço do 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. Uma vez publicado com o perfil que você criou no tutorial anterior, o executável estará no diretório de publicação. Em seguida, crie o projeto de instalação e execute o instalador.

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

Depois que o serviço estiver 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.

Partilhar via