Criar Serviço do Windows usando `BackgroundService`

Artigo
12/13/2023

Os desenvolvedores do .NET Framework provavelmente estão familiarizados com os aplicativos de serviço do Windows. Antes do .NET Core e do .NET 5+, os desenvolvedores que dependiam do .NET Framework podiam criar os Serviços do Windows para executar tarefas em segundo plano ou executar processos de longa execução. Essa funcionalidade ainda está disponível e você pode criar Serviços de Trabalho que são executados como um Serviço do Windows.

Neste tutorial, irá aprender a:

Publique um aplicativo de trabalho .NET como um único arquivo executável.
Crie um serviço do Windows.
Crie o aplicativo como um serviço do BackgroundService Windows.
Inicie e pare o Serviço do Windows.
Exibir logs de eventos.
Exclua o serviço do Windows.

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.

Importante

A instalação do SDK do .NET também instala o modelo e o Microsoft.NET.Sdk.Worker de trabalho. Em outras palavras, depois de instalar o SDK do .NET, você pode criar um novo trabalhador usando o comando dotnet new worker . Se você estiver usando o Visual Studio, o modelo ficará oculto até que a carga de trabalho opcional de ASP.NET e desenvolvimento da Web seja instalada.

Pré-requisitos

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

Criar um novo projeto

Para criar um novo projeto do Serviço de Trabalho com o Visual Studio, selecione Arquivo>Novo>Projeto....Na caixa de diálogo Criar um novo projeto, procure por "Serviço de Trabalho" e selecione Modelo de Serviço de Trabalhador. Se você preferir usar a CLI do .NET, abra seu terminal favorito em um diretório de trabalho. Execute o comando e substitua o dotnet new pelo nome do <Project.Name> projeto desejado.

dotnet new worker --name <Project.Name>

Para obter mais informações sobre o comando .NET CLI new worker service project, consulte dotnet new worker.

Gorjeta

Se você estiver usando o Visual Studio Code, poderá executar comandos da CLI do .NET a partir do terminal integrado. Para obter mais informações, consulte Visual Studio Code: Integrated Terminal.

Instalar o pacote NuGet

Para interoperar com os Serviços nativos do Windows a partir de implementações .NET IHostedService , você precisará instalar o Microsoft.Extensions.Hosting.WindowsServices pacote NuGet.

Para instalá-lo a partir do Visual Studio, use a caixa de diálogo Gerenciar pacotes NuGet... Procure por "Microsoft.Extensions.Hosting.WindowsServices" e instale-o. Se preferir usar a CLI do .NET, execute o dotnet add package comando:

dotnet add package Microsoft.Extensions.Hosting.WindowsServices

Para obter mais informações sobre o comando add package da CLI do .NET, consulte dotnet add package.

Depois de adicionar com êxito os pacotes, seu arquivo de projeto agora deve conter as seguintes referências de pacote:

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
  <PackageReference Include="Microsoft.Extensions.Hosting.WindowsServices" Version="8.0.0" />
</ItemGroup>

Atualizar arquivo de projeto

Este projeto de trabalho usa os tipos de referência anuláveis do C#. Para habilitá-los para todo o projeto, atualize o arquivo de projeto de acordo:

<Project Sdk="Microsoft.NET.Sdk.Worker">

  <PropertyGroup>
    <TargetFramework>net8.0-windows</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
    <RootNamespace>App.WindowsService</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
    <PackageReference Include="Microsoft.Extensions.Hosting.WindowsServices" Version="8.0.0" />
  </ItemGroup>
</Project>

As alterações do arquivo de projeto anterior adicionam o <Nullable>enable<Nullable> nó. Para obter mais informações, consulte Definindo o contexto anulável.

Criar o serviço

Adicione uma nova classe ao projeto chamada JokeService.cs e substitua seu conteúdo pelo seguinte código C#:

namespace App.WindowsService;

public sealed class JokeService
{
    public string GetJoke()
    {
        Joke joke = _jokes.ElementAt(
            Random.Shared.Next(_jokes.Count));

        return $"{joke.Setup}{Environment.NewLine}{joke.Punchline}";
    }

    // Programming jokes borrowed from:
    // https://github.com/eklavyadev/karljoke/blob/main/source/jokes.json
    private readonly HashSet<Joke> _jokes = new()
    {
        new Joke("What's the best thing about a Boolean?", "Even if you're wrong, you're only off by a bit."),
        new Joke("What's the object-oriented way to become wealthy?", "Inheritance"),
        new Joke("Why did the programmer quit their job?", "Because they didn't get arrays."),
        new Joke("Why do programmers always mix up Halloween and Christmas?", "Because Oct 31 == Dec 25"),
        new Joke("How many programmers does it take to change a lightbulb?", "None that's a hardware problem"),
        new Joke("If you put a million monkeys at a million keyboards, one of them will eventually write a Java program", "the rest of them will write Perl"),
        new Joke("['hip', 'hip']", "(hip hip array)"),
        new Joke("To understand what recursion is...", "You must first understand what recursion is"),
        new Joke("There are 10 types of people in this world...", "Those who understand binary and those who don't"),
        new Joke("Which song would an exception sing?", "Can't catch me - Avicii"),
        new Joke("Why do Java programmers wear glasses?", "Because they don't C#"),
        new Joke("How do you check if a webpage is HTML5?", "Try it out on Internet Explorer"),
        new Joke("A user interface is like a joke.", "If you have to explain it then it is not that good."),
        new Joke("I was gonna tell you a joke about UDP...", "...but you might not get it."),
        new Joke("The punchline often arrives before the set-up.", "Do you know the problem with UDP jokes?"),
        new Joke("Why do C# and Java developers keep breaking their keyboards?", "Because they use a strongly typed language."),
        new Joke("Knock-knock.", "A race condition. Who is there?"),
        new Joke("What's the best part about TCP jokes?", "I get to keep telling them until you get them."),
        new Joke("A programmer puts two glasses on their bedside table before going to sleep.", "A full one, in case they gets thirsty, and an empty one, in case they don’t."),
        new Joke("There are 10 kinds of people in this world.", "Those who understand binary, those who don't, and those who weren't expecting a base 3 joke."),
        new Joke("What did the router say to the doctor?", "It hurts when IP."),
        new Joke("An IPv6 packet is walking out of the house.", "He goes nowhere."),
        new Joke("3 SQL statements walk into a NoSQL bar. Soon, they walk out", "They couldn't find a table.")
    };
}

readonly record struct Joke(string Setup, string Punchline);

O código-fonte do serviço de piada anterior expõe uma única parte da funcionalidade, o GetJoke método. Este é um string método de retorno que representa uma piada de programação aleatória. O campo de escopo de classe é usado para armazenar a lista de _jokes piadas. Uma piada aleatória é selecionada da lista e retornada.

Reescrever a `Worker` classe

Substitua o existente Worker do modelo pelo seguinte código C# e renomeie o arquivo para WindowsBackgroundService.cs:

namespace App.WindowsService;

public sealed class WindowsBackgroundService(
    JokeService jokeService,
    ILogger<WindowsBackgroundService> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        try
        {
            while (!stoppingToken.IsCancellationRequested)
            {
                string joke = jokeService.GetJoke();
                logger.LogWarning("{Joke}", joke);

                await Task.Delay(TimeSpan.FromMinutes(1), stoppingToken);
            }
        }
        catch (OperationCanceledException)
        {
            // When the stopping token is canceled, for example, a call made from services.msc,
            // we shouldn't exit with a non-zero exit code. In other words, this is expected...
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "{Message}", ex.Message);

            // Terminates this process and returns an exit code to the operating system.
            // This is required to avoid the 'BackgroundServiceExceptionBehavior', which
            // performs one of two scenarios:
            // 1. When set to "Ignore": will do nothing at all, errors cause zombie services.
            // 2. When set to "StopHost": will cleanly stop the host, and log errors.
            //
            // In order for the Windows Service Management system to leverage configured
            // recovery options, we need to terminate the process with a non-zero exit code.
            Environment.Exit(1);
        }
    }
}

No código anterior, o é injetado JokeService junto com um ILoggerarquivo . Ambos são disponibilizados para a classe como private readonly campos. ExecuteAsync No método, o serviço de piada solicita uma piada e a escreve para o madeireiro. Nesse caso, o registrador é implementado pelo log de eventos do Windows - Microsoft.Extensions.Logging.EventLog.EventLogLogger. Os logs são gravados e estão disponíveis para visualização no Visualizador de Eventos.

Nota

Por padrão, a gravidade do Log de Eventos é Warning. Isso pode ser configurado, mas para fins de demonstração os WindowsBackgroundService logs com o LogWarning método de extensão. Para direcionar especificamente o EventLog nível, adicione uma entrada nas appsettings.{ Environment}.json, ou forneça um EventLogSettings.Filter valor.

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    },
    "EventLog": {
      "SourceName": "The Joke Service",
      "LogName": "Application",
      "LogLevel": {
        "Microsoft": "Information",
        "Microsoft.Hosting.Lifetime": "Information"
      }
    }
  }
}

Para obter mais informações sobre como configurar níveis de log, consulte Provedores de log no .NET: Configurar o EventLog do Windows.

Reescrever a `Program` classe

Substitua o conteúdo do arquivo .cs programa modelo com o seguinte código C#:

using App.WindowsService;
using Microsoft.Extensions.Logging.Configuration;
using Microsoft.Extensions.Logging.EventLog;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
builder.Services.AddWindowsService(options =>
{
    options.ServiceName = ".NET Joke Service";
});

LoggerProviderOptions.RegisterProviderOptions<
    EventLogSettings, EventLogLoggerProvider>(builder.Services);

builder.Services.AddSingleton<JokeService>();
builder.Services.AddHostedService<WindowsBackgroundService>();

IHost host = builder.Build();
host.Run();

O AddWindowsService método de extensão configura o aplicativo para funcionar como um serviço do Windows. O nome do serviço é definido como ".NET Joke Service". O serviço hospedado está registrado para injeção de dependência.

Para obter mais informações sobre como registrar serviços, consulte Injeção de dependência no .NET.

Publicar a aplicação

Para criar o aplicativo .NET Worker Service como um Serviço do Windows, é recomendável publicar o aplicativo como um único arquivo executável. É menos propenso a erros ter um executável independente, pois não há arquivos dependentes ao redor do sistema de arquivos. Mas você pode escolher uma modalidade de publicação diferente, o que é perfeitamente aceitável, desde que crie um arquivo *.exe que possa ser direcionado pelo Gerenciador de Controle de Serviços do Windows.

Importante

Uma abordagem de publicação alternativa é criar o *.dll (em vez de um *.exe) e, quando você instala o aplicativo publicado usando o Gerenciador de Controle de Serviços do Windows, delega à CLI do .NET e passa a DLL. Para obter mais informações, consulte .NET CLI: comando dotnet.

sc.exe create ".NET Joke Service" binpath="C:\Path\To\dotnet.exe C:\Path\To\App.WindowsService.dll"

<Project Sdk="Microsoft.NET.Sdk.Worker">

  <PropertyGroup>
    <TargetFramework>net8.0-windows</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
    <RootNamespace>App.WindowsService</RootNamespace>
    <OutputType>exe</OutputType>
    <PublishSingleFile Condition="'$(Configuration)' == 'Release'">true</PublishSingleFile>
    <RuntimeIdentifier>win-x64</RuntimeIdentifier>
    <PlatformTarget>x64</PlatformTarget>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
    <PackageReference Include="Microsoft.Extensions.Hosting.WindowsServices" Version="8.0.0" />
  </ItemGroup>
</Project>

As linhas destacadas anteriores do arquivo de projeto definem os seguintes comportamentos:

<OutputType>exe</OutputType>: Cria um aplicativo de console.
<PublishSingleFile Condition="'$(Configuration)' == 'Release'">true</PublishSingleFile>: Permite a publicação de arquivo único.
<RuntimeIdentifier>win-x64</RuntimeIdentifier>: Especifica o RID de win-x64.
<PlatformTarget>x64</PlatformTarget>: Especifique a CPU da plataforma de destino de 64 bits.

Para publicar o aplicativo do Visual Studio, você pode criar um perfil de publicação persistente. O perfil de publicação é baseado em XML e tem a extensão de arquivo .pubxml . O Visual Studio usa esse perfil para publicar o aplicativo implicitamente, enquanto se você estiver usando a CLI do .NET — deverá especificar explicitamente o perfil de publicação para que ele seja usado.

Clique com o botão direito do mouse no projeto no Gerenciador de Soluções e selecione Publicar.... Em seguida, selecione Adicionar um perfil de publicação para criar um perfil . Na caixa de diálogo Publicar, selecione Pasta como destino.

Deixe o Local padrão e selecione Concluir. Depois que o perfil for criado, selecione Mostrar todas as configurações e verifique as configurações do seu perfil.

Certifique-se de que as seguintes configurações sejam especificadas:

Modo de implantação: autônomo
Produzir arquivo único: verificado
Ativar compilação ReadyToRun: verificado
Cortar montagens não utilizadas (na pré-visualização): não verificado

Por fim, selecione Publicar. O aplicativo é compilado e o arquivo .exe resultante é publicado no diretório de saída /publishing .

Como alternativa, você pode usar a CLI do .NET para publicar o aplicativo:

dotnet publish --output "C:\custom\publish\directory"

Para obter mais informações, veja dotnet publish.

Importante

Com o .NET 6, se você tentar depurar o aplicativo com a <PublishSingleFile>true</PublishSingleFile> configuração, não poderá depurar o aplicativo. Para obter mais informações, consulte Não é possível anexar ao CoreCLR ao depurar um aplicativo .NET 6 'PublishSingleFile'.

Criar o serviço do Windows

Se você não estiver familiarizado com o uso do PowerShell e preferir criar um instalador para seu serviço, consulte Criar um instalador de serviço do Windows. Caso contrário, para criar o Serviço do Windows, use o comando create nativo do Gerenciador de Controle de Serviços do Windows (sc.exe). Execute o PowerShell como Administrador.

sc.exe create ".NET Joke Service" binpath="C:\Path\To\App.WindowsService.exe"

Gorjeta

Se precisar alterar a raiz do conteúdo da configuração do host, você pode passá-la como um argumento de linha de comando ao especificar o binpath:

sc.exe create "Svc Name" binpath="C:\Path\To\App.exe --contentRoot C:\Other\Path"

Você verá uma mensagem de saída:

[SC] CreateService SUCCESS

Para obter mais informações, consulte sc.exe create.

Configurar o Serviço do Windows

Depois que o serviço for criado, você poderá configurá-lo opcionalmente. Se você estiver bem com os padrões de serviço, vá para a seção Verificar funcionalidade do serviço.

Os Serviços do Windows fornecem opções de configuração de recuperação. Você pode consultar a configuração atual usando o comando (onde <Service Name> é o sc.exe qfailure "<Service Name>" nome dos serviços) para ler os valores atuais da configuração de recuperação:

sc qfailure ".NET Joke Service"
[SC] QueryServiceConfig2 SUCCESS

SERVICE_NAME: .NET Joke Service
        RESET_PERIOD (in seconds)    : 0
        REBOOT_MESSAGE               :
        COMMAND_LINE                 :

O comando produzirá a configuração de recuperação, que são os valores padrão, já que eles ainda não foram configurados.

The Windows Service recovery configuration properties dialog.

Para configurar a recuperação, use onde sc.exe failure "<Service Name>"<Service Name> é o nome do seu serviço:

sc.exe failure ".NET Joke Service" reset=0 actions=restart/60000/restart/60000/run/1000
[SC] ChangeServiceConfig2 SUCCESS

Gorjeta

Para configurar as opções de recuperação, a sessão do terminal precisa ser executada como administrador.

Depois de configurado com êxito, você pode consultar os valores mais uma vez usando o sc.exe qfailure "<Service Name>" comando:

sc qfailure ".NET Joke Service"
[SC] QueryServiceConfig2 SUCCESS

SERVICE_NAME: .NET Joke Service
        RESET_PERIOD (in seconds)    : 0
        REBOOT_MESSAGE               :
        COMMAND_LINE                 :
        FAILURE_ACTIONS              : RESTART -- Delay = 60000 milliseconds.
                                       RESTART -- Delay = 60000 milliseconds.
                                       RUN PROCESS -- Delay = 1000 milliseconds.

Você verá os valores de reinicialização configurados.

The Windows Service recovery configuration properties dialog with restart enabled.

Opções de recuperação de serviço e instâncias .NET `BackgroundService`

Com o .NET 6, novos comportamentos de tratamento de exceções de hospedagem foram adicionados ao .NET. O BackgroundServiceExceptionBehavior enum foi adicionado ao Microsoft.Extensions.Hosting namespace e é usado para especificar o comportamento do serviço quando uma exceção é lançada. A tabela a seguir lista as opções disponíveis:

Opção	Description
Ignore	Ignore as exceções lançadas no `BackgroundService`.
StopHost	O `IHost` será interrompido quando uma exceção não tratada for lançada.

O comportamento padrão antes do .NET 6 é Ignore, que resultou em processos zumbis (um processo em execução que não fez nada). Com o .NET 6, o comportamento padrão é , o que resulta na interrupção do host quando uma exceção é StopHostlançada. Mas ele para limpamente, o que significa que o sistema de gerenciamento de serviços do Windows não reiniciará o serviço. Para permitir corretamente que o serviço seja reiniciado, você pode ligar Environment.Exit com um código de saída diferente de zero. Considere o seguinte bloco realçado catch :

namespace App.WindowsService;

public sealed class WindowsBackgroundService(
    JokeService jokeService,
    ILogger<WindowsBackgroundService> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        try
        {
            while (!stoppingToken.IsCancellationRequested)
            {
                string joke = jokeService.GetJoke();
                logger.LogWarning("{Joke}", joke);

                await Task.Delay(TimeSpan.FromMinutes(1), stoppingToken);
            }
        }
        catch (OperationCanceledException)
        {
            // When the stopping token is canceled, for example, a call made from services.msc,
            // we shouldn't exit with a non-zero exit code. In other words, this is expected...
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "{Message}", ex.Message);

            // Terminates this process and returns an exit code to the operating system.
            // This is required to avoid the 'BackgroundServiceExceptionBehavior', which
            // performs one of two scenarios:
            // 1. When set to "Ignore": will do nothing at all, errors cause zombie services.
            // 2. When set to "StopHost": will cleanly stop the host, and log errors.
            //
            // In order for the Windows Service Management system to leverage configured
            // recovery options, we need to terminate the process with a non-zero exit code.
            Environment.Exit(1);
        }
    }
}

Verificar a funcionalidade do serviço

Para ver o aplicativo criado como um Serviço do Windows, abra Serviços. Selecione a tecla Windows (ou Ctrl + Esc) e pesquise em "Serviços". A partir da aplicação Serviços, deverá conseguir encontrar o seu serviço pelo respetivo nome.

Importante

Por padrão, os usuários regulares (não administradores) não podem gerenciar serviços do Windows. Para verificar se este aplicativo funciona conforme o esperado, você precisará usar uma conta de administrador.

Para verificar se o serviço está funcionando conforme o esperado, você precisa:

Iniciar o serviço
Ver os registos
Parar o serviço

Importante

Para depurar o aplicativo, certifique-se de que você não está tentando depurar o executável que está sendo executado ativamente no processo de Serviços do Windows.

Unable to start program.

Iniciar o Serviço Windows

Para iniciar o Serviço do Windows, use o sc.exe start comando:

sc.exe start ".NET Joke Service"

Você verá uma saída semelhante à seguinte:

SERVICE_NAME: .NET Joke Service
    TYPE               : 10  WIN32_OWN_PROCESS
    STATE              : 2  START_PENDING
                            (NOT_STOPPABLE, NOT_PAUSABLE, IGNORES_SHUTDOWN)
    WIN32_EXIT_CODE    : 0  (0x0)
    SERVICE_EXIT_CODE  : 0  (0x0)
    CHECKPOINT         : 0x0
    WAIT_HINT          : 0x7d0
    PID                : 37636
    FLAGS

O Status do serviço fará a transição para START_PENDING Executando.

Ver registos

Para visualizar logs, abra o Visualizador de Eventos. Selecione a tecla Windows (ou Ctrl + Esc) e procure "Event Viewer"por . Selecione o nó Visualizador de Eventos (Local)>Aplicativo de Logs>do Windows. Você verá uma entrada de nível de Aviso com uma Origem correspondente ao namespace de aplicativos. Clique duas vezes na entrada ou clique com o botão direito do mouse e selecione Propriedades do evento para exibir os detalhes.

Depois de ver os logs no Log de Eventos, você deve parar o serviço. Ele foi projetado para registrar uma piada aleatória uma vez por minuto. Este é um comportamento intencional, mas não é prático para serviços de produção.

Pare o Serviço do Windows

Para parar o Serviço do Windows, use o sc.exe stop comando:

sc.exe stop ".NET Joke Service"

Você verá uma saída semelhante à seguinte:

SERVICE_NAME: .NET Joke Service
    TYPE               : 10  WIN32_OWN_PROCESS
    STATE              : 3  STOP_PENDING
                            (STOPPABLE, NOT_PAUSABLE, ACCEPTS_SHUTDOWN)
    WIN32_EXIT_CODE    : 0  (0x0)
    SERVICE_EXIT_CODE  : 0  (0x0)
    CHECKPOINT         : 0x0
    WAIT_HINT          : 0x0

O status do serviço será transferido de STOP_PENDING parado.

Excluir o serviço do Windows

Para excluir o Serviço do Windows, use o comando delete nativo do Gerenciador de Controle de Serviços do Windows (sc.exe). Execute o PowerShell como Administrador.

Importante

Se o serviço não estiver no estado Parado , ele não será excluído imediatamente. Verifique se o serviço foi interrompido antes de emitir o comando delete.

sc.exe delete ".NET Joke Service"

Você verá uma mensagem de saída:

[SC] DeleteService SUCCESS

Para obter mais informações, consulte sc.exe delete.

Consulte também

Seguinte

Criar um instalador de serviço do Windows

Partilhar via

Criar Serviço do Windows usando `BackgroundService`

Pré-requisitos

Criar um novo projeto

Instalar o pacote NuGet

Atualizar arquivo de projeto

Criar o serviço

Reescrever a `Worker` classe

Reescrever a `Program` classe

Publicar a aplicação

Criar o serviço do Windows

Configurar o Serviço do Windows

Opções de recuperação de serviço e instâncias .NET `BackgroundService`

Verificar a funcionalidade do serviço

Iniciar o Serviço Windows

Ver registos

Pare o Serviço do Windows

Excluir o serviço do Windows

Consulte também

Seguinte

Recursos adicionais

Partilhar via

Criar Serviço do Windows usando BackgroundService

Pré-requisitos

Criar um novo projeto

Instalar o pacote NuGet

Atualizar arquivo de projeto

Criar o serviço

Reescrever a Worker classe

Reescrever a Program classe

Publicar a aplicação

Criar o serviço do Windows

Configurar o Serviço do Windows

Opções de recuperação de serviço e instâncias .NET BackgroundService

Verificar a funcionalidade do serviço

Iniciar o Serviço Windows

Ver registos

Pare o Serviço do Windows

Excluir o serviço do Windows

Consulte também

Seguinte

Recursos adicionais

Criar Serviço do Windows usando `BackgroundService`

Reescrever a `Worker` classe

Reescrever a `Program` classe

Opções de recuperação de serviço e instâncias .NET `BackgroundService`