Creare un servizio Windows con BackgroundService

Gli sviluppatori di .NET Framework hanno probabilmente familiarità con le app del servizio Windows. Prima di .NET Core e .NET 5+, gli sviluppatori che si affidavano a .NET Framework potevano creare servizi Windows per eseguire attività in background o eseguire processi a esecuzione prolungata. Questa funzionalità è ancora disponibile ed è possibile creare servizi ruolo di lavoro eseguiti come servizio Windows.

Questa esercitazione illustra come:

Prerequisiti

• .NET 8.0 SDK o versioni successive
• Un sistema operativo Windows
• Ambiente di sviluppo integrato .NET (IDE)
  • È possibile usare Visual Studio

Crea un nuovo progetto

Per creare un nuovo progetto del servizio ruolo di lavoro con Visual Studio, selezionare File>Nuovo>Progetto.... Nella finestra di dialogo Crea un nuovo progetto cercare "Servizio del ruolo di lavoro" e selezionare Modello del servizio ruolo di lavoro. Se si preferisce usare l'interfaccia della riga di comando di .NET, aprire il terminale preferito in una directory di lavoro. Eseguire il comando dotnet new e sostituire il <Project.Name> con il nome del progetto desiderato.

dotnet new worker --name <Project.Name>

Per altre informazioni sul comando new worker service project dell'interfaccia della riga di comando di .NET, vedere dotnet new worker.

Installare il pacchetto NuGet

Per interagire con i servizi Windows nativi da implementazioni di IHostedService .NET, è necessario installare il pacchetto NuGet Microsoft.Extensions.Hosting.WindowsServices.

Per installarlo da Visual Studio, usare la finestra di dialogo Gestisci pacchetti NuGet.... Cercare "Microsoft.Extensions.Hosting.WindowsServices" e installarlo. Se si preferisce usare l'interfaccia della riga di comando di .NET, eseguire il comando dotnet add package:

dotnet add package Microsoft.Extensions.Hosting.WindowsServices

Per altre informazioni sul comando add package dell'interfaccia della riga di comando di .NET, vedere dotnet add package.

Dopo l'aggiunta corretta dei pacchetti, il file di progetto dovrebbe ora contenere i riferimenti al pacchetto seguenti:

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

Aggiornare il file di progetto

Questo progetto di ruolo di lavoro usa tipi di riferimento che ammettono i valori Null di C#. Per abilitarli per l'intero progetto, aggiornare di conseguenza il file di progetto:

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

Le modifiche precedenti apportate al file di progetto aggiungono il nodo <Nullable>enable<Nullable>. Per altre informazioni, vedere Impostazione del contesto Nullable.

Creare il servizio

Aggiungere una nuova classe al progetto denominato JokeService.cse sostituirne il contenuto con il codice C# seguente:

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

Il codice sorgente del servizio joke precedente espone una singola parte di funzionalità, il metodo GetJoke. Si tratta di un metodo che restituisce string che rappresenta una barzelletta casuale relativa alla programmazione. Il campo _jokes con ambito classe viene utilizzato per archiviare l'elenco di barzellette. Una barzelletta casuale viene selezionato dall'elenco e restituita.

Riscrivere la classe Worker

Sostituire la classe Worker esistente dal modello con il codice C# seguente e rinominare il file in 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);
        }
    }
}

Nel codice precedente JokeService viene inserito insieme a ILogger. Entrambi vengono resi disponibili per la classe come campi private readonly. Nel metodo ExecuteAsync il servizio joke richiede una barzelletta e la scrive nel logger. In questo caso il logger viene implementato dal Registro eventi di Windows - Microsoft.Extensions.Logging.EventLog.EventLogLogger. Vengono scritte informazioni nei log, che sono disponibili per la visualizzazione nel Visualizzatore eventi.

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

Riscrivere la classe Program

Sostituire i contenuti del file Program.cs del modello con il codice C# seguente:

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();

Il metodo di estensione AddWindowsService configura l'app in modo che funzioni come servizio Windows. Il nome del servizio è impostato su ".NET Joke Service". Il servizio ospitato è registrato per l'inserimento delle dipendenze.

Per altre informazioni sulla registrazione dei servizi, vedere Inserimento delle dipendenze in .NET.

Pubblicazione dell'app

Per creare l'app del servizio ruolo di lavoro .NET come servizio Windows, è consigliabile pubblicare l'app come file eseguibile singolo. Un file eseguibile autonomo è meno soggetto a errori, perché non sono presenti file dipendenti nel file system. È tuttavia possibile scegliere una modalità di pubblicazione diversa, che è perfettamente accettabile, purché si crei un file *.exe che può essere usato da Gestione controllo servizi Windows.

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>

Le righe evidenziate precedenti del file di progetto definiscono i comportamenti seguenti:

• <OutputType>exe</OutputType>: crea un'applicazione console.
• <PublishSingleFile Condition="'$(Configuration)' == 'Release'">true</PublishSingleFile>: abilita la pubblicazione a file singolo.
• <RuntimeIdentifier>win-x64</RuntimeIdentifier>: specifica il RID di win-x64.
• <PlatformTarget>x64</PlatformTarget>: specifica la CPU della piattaforma di destinazione a 64 bit.

Per pubblicare l'app da Visual Studio, è possibile creare un profilo di pubblicazione persistente. Il profilo di pubblicazione è basato su XML e ha l'estensione file .pubxml. Visual Studio usa questo profilo per pubblicare l'app in modo implicito, mentre se si usa l'interfaccia della riga di comando di .NET, è necessario specificare in modo esplicito il profilo di pubblicazione per usarlo.

Fare clic con il pulsante destro del mouse sul progetto in Esplora soluzioni e scegliere Pubblica. Selezionare quindi Aggiungi un profilo di pubblicazione per creare un profilo. Nella finestra di dialogo Pubblica selezionare Cartella come Destinazione.

Lasciare il Percorso predefinitoe e quindi selezionare Fine. Dopo aver creato il profilo, selezionare Mostra tutte le impostazioni e verificare le Iimpostazioni del profilo.

Verificare che siano specificate le impostazioni seguenti:

• Modalità di distribuzione: autonoma
• Produci un singolo file: opzione selezionata
• Abilita la compilazione con ReadyToRun: opzione selezionata
• Taglia gli assembly inutilizzati (in anteprima): opzione deselezionata

Selezionare infine Pubblica. L'app viene compilata e il file EXE risultante viene pubblicato nella directory di output /publish.

In alternativa, è possibile usare l'interfaccia della riga di comando di .NET per pubblicare l'app:

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

Per ulteriori informazioni, vedere dotnet publish.

Creare il servizio Windows

Se non si ha familiarità con l'uso di PowerShell e si preferisce creare un programma di installazione per il servizio, vedere Creare un programma di installazione del servizio Windows. In caso contrario, per creare il servizio Windows usare il comando di creazione (sc.exe) nativo di Gestione controllo servizi Windows. Eseguire PowerShell come amministratore.

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

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

Verrà visualizzato un messaggio di output:

[SC] CreateService SUCCESS

Per altre informazioni, vedere sc.exe create.

Configurare il servizio Windows

Dopo aver creato il servizio, è facoltativamente possibile configurarlo. Se le impostazioni predefinite del servizio sono appropriate per le esigenze specifiche, passare alla sezione Verificare la funzionalità del servizio.

I servizi Windows offrono opzioni di configurazione di ripristino. È possibile eseguire una query sulla configurazione corrente usando il comando sc.exe qfailure "<Service Name>" (dove <Service Name> è il nome dei servizi) per leggere i valori di configurazione di ripristino correnti:

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

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

Il comando restituirà la configurazione di ripristino, ovvero i valori predefiniti perché non sono ancora stati configurati.

Per configurare il ripristino, usare sc.exe failure "<Service Name>" dove <Service Name> è il nome del servizio:

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

Dopo la configurazione, è possibile eseguire di nuovo una query sui valori usando il comando sc.exe qfailure "<Service Name>":

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.

Verranno visualizzati i valori di riavvio configurati.

Opzioni di ripristino del servizio e istanze di BackgroundService .NET

Con .NET 6, sono stati aggiunti a .NET nuovi comportamenti di gestione delle eccezioni di hosting. L'enumerazione BackgroundServiceExceptionBehavior è stata aggiunta allo spazio dei nomi Microsoft.Extensions.Hosting e viene usata per specificare il comportamento del servizio quando viene generata un'eccezione. Nella tabella seguente sono elencate le opzioni disponibili:

Il comportamento predefinito prima di .NET 6 è Ignore, che generava processi zombie, ovvero un processo in esecuzione che non ha eseguito alcuna operazione. Con .NET 6, il comportamento predefinito è StopHost, che comporta l'arresto dell'host quando viene generata un'eccezione. Ma l'arresto viene eseguito in modo pulito, ovvero il sistema di gestione dei servizi Windows non riavvia il servizio. Per consentire correttamente il riavvio del servizio, è possibile chiamare Environment.Exit con un codice di uscita diverso da zero. Si consideri il blocco catch evidenziato seguente:

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

Verificare la funzionalità del servizio

Per visualizzare l'app creata come servizio Windows, aprire Servizi. Selezionare il tasto Windows (o CTRL + ESC) e cercare da "Servizi". Dall'app Servizi dovrebbe essere possibile trovare il servizio in base al nome.

Per verificare che il servizio funzioni come previsto, è necessario:

• avviare il servizio
• Visualizzare i log
• Interrompi il servizio

Avviare il servizio Windows

Per avviare il servizio Windows, usare il comando sc.exe start:

sc.exe start ".NET Joke Service"

Verrà visualizzato un output simile al seguente:

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

Lo Stato del servizio passerà da START_PENDING a In esecuzione.

Visualizzare i log

Per visualizzare i log, aprire il Visualizzatore eventi. Selezionare il tasto Windows (o CTRL + ESC) e cercare "Event Viewer". Selezionare il nodo Visualizzatore eventi (locale)>Registri di Windows>Applicazione. Verrà visualizzata una voce di livello Avviso con un'Origine corrispondente allo spazio dei nomi delle app. Fare doppio clic sulla voce oppure fare clic con il pulsante destro del mouse e scegliere Proprietà evento per visualizzare i dettagli.

Dopo aver visualizzato i log nel Registro eventi, è necessario arrestare il servizio. È progettato per registrare una barzelletta casuale una volta al minuto. Si tratta di un comportamento intenzionale, ma non risulta funzionale per i servizi di produzione.

Arrestare il servizio Windows

Per arrestare il servizio Windows, usare il comando sc.exe stop:

sc.exe stop ".NET Joke Service"

Verrà visualizzato un output simile al seguente:

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

Lo Stato del servizio passerà da STOP_PENDING ad Arrestato.

Eliminare il servizio Windows

Per eliminare il servizio Windows, usare il comando di eliminazione (sc.exe) nativo di Gestione controllo servizi Windows. Eseguire PowerShell come amministratore.

sc.exe delete ".NET Joke Service"

Verrà visualizzato un messaggio di output:

[SC] DeleteService SUCCESS

Per altre informazioni, vedere sc.exe delete.

Vedi anche

• Creare un programma di installazione del servizio Windows
• Servizi ruolo di lavoro in .NET
• Creare un servizio di accodamento
• Usare i servizi con ambito all'interno di una classe BackgroundService
• Implementare l'interfaccia IHostedService

Avanti