Windows-szolgáltatás létrehozása BackgroundService

A .NET-keretrendszer fejlesztői valószínűleg ismerik a Windows Service-alkalmazásokat. A .NET Core és a .NET 5+ előtt a .NET-keretrendszerre támaszkodó fejlesztők létrehozhatják a Windows-szolgáltatásokat háttérfeladatok végrehajtásához vagy hosszú ideig futó folyamatok végrehajtásához. Ez a funkció továbbra is elérhető, és windowsos szolgáltatásként futó Feldolgozói szolgáltatásokat is létrehozhat.

Ebben az oktatóanyagban megtanulhatja, hogyan:

Előfeltételek

• A .NET 8.0 SDK vagy újabb
• Windows operációs rendszer
• .NET integrált fejlesztési környezet (IDE)
  • Nyugodtan használhatja Visual Studio

Új projekt létrehozása

Ha új Worker Service-projektet szeretne létrehozni a Visual Studióval, válassza Fájl>Új>projekt...lehetőséget. Az Új projekt létrehozása párbeszédpanelen keresse meg a "Worker Service" kifejezést, és válassza a Worker Service sablont. Ha inkább a .NET CLI-t szeretné használni, nyissa meg kedvenc terminálját egy munkakönyvtárban. Futtassa a dotnet new parancsot, és cserélje le a <Project.Name> a kívánt projektnévre.

dotnet new worker --name <Project.Name>

További információért a .NET CLI új feldolgozói szolgáltatás projektparancsáról tekintse meg dotnet új feldolgozó.

NuGet-csomag telepítése

A natív Windows-szolgáltatások .NET-IHostedService implementációkból való használatához telepítenie kell a Microsoft.Extensions.Hosting.WindowsServices NuGet-csomag.

Ha ezt a Visual Studióból szeretné telepíteni, használja a NuGet-csomagok kezelése... párbeszédpanelt. Keressen rá a "Microsoft.Extensions.Hosting.WindowsServices" kifejezésre, és telepítse. Ha inkább a .NET CLI-t szeretné használni, futtassa a dotnet add package parancsot:

dotnet add package Microsoft.Extensions.Hosting.WindowsServices

A .NET CLI csomag hozzáadása parancsával kapcsolatos további információkért lásd dotnet add package.

A csomagok sikeres hozzáadása után a projektfájlnak a következő csomaghivatkozásokat kell tartalmaznia:

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

Projektfájl frissítése

Ez a feldolgozó projekt a C#null értékű hivatkozástípusait használja. A teljes projekt engedélyezéséhez frissítse a projektfájlt a következő módon:

<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="9.0.3" />
    <PackageReference Include="Microsoft.Extensions.Hosting.WindowsServices" Version="9.0.3" />
  </ItemGroup>
</Project>

Az előző projektfájl-módosítások hozzáadják a <Nullable>enable<Nullable> csomópontot. További információ: Null értékű környezet beállítása.

A szolgáltatás létrehozása

Adjon hozzá egy új osztályt a JokeService.csnevű projekthez, és cserélje le a tartalmát a következő C#-kódra:

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

Az előző viccszolgáltatás forráskódja egyetlen funkciót tesz elérhetővé, a GetJoke metódust. Ez egy string visszatérési módszer, amely véletlenszerű programozási viccet jelöl. Az osztály hatókörű _jokes mező a viccek listájának tárolására szolgál. Egy véletlenszerű vicc kerül kiválasztásra a listából és vissza van adva.

Az Worker osztály újraírása

Cserélje le a sablonból származó meglévő Worker a következő C#-kódra, és nevezze át a fájlt 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);
        }
    }
}

Az előző kódban a JokeService be van illesztve a ILogger-el együtt. Mindkettőt mezőként biztosítják az osztály számára. A ExecuteAsync metódusban a viccszolgáltatás egy viccet kér, és megírja a naplózónak. Ebben az esetben a naplózót a Windows eseménynaplója implementálja – Microsoft.Extensions.Logging.EventLog.EventLogLoggerProvider. Az Eseménynaplónaplók íródnak, és megtekinthetők.

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

Az Program osztály újraírása

Cserélje le a sablont Program.cs fájl tartalmát a következő C#-kódra:

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

A AddWindowsService bővítménymetódus úgy konfigurálja az alkalmazást, hogy Windows-szolgáltatásként működjön. A szolgáltatás neve ".NET Joke Service"értékre van állítva. Az üzemeltetett szolgáltatás regisztrálva van a függőséginjektáláshoz.

További információ a szolgáltatások regisztrálásáról: Függőséginjektálás a .NET-ben.

Az alkalmazás közzététele

A .NET Worker Service alkalmazás Windows-szolgáltatásként való létrehozásához ajánlott az alkalmazást egyetlen végrehajtható fájlként közzétenni. Kisebb a hibalehetőség, ha egy önálló végrehajtható fájl van, mivel a fájlrendszerben nincsenek függő fájlok. De választhat egy másik közzétételi módot, amely tökéletesen elfogadható, amíg létrehoz egy *.exe fájlt, amelyet a Windows Service Control Manager megcélozhat.

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="9.0.3" />
    <PackageReference Include="Microsoft.Extensions.Hosting.WindowsServices" Version="9.0.3" />
  </ItemGroup>
</Project>

A projektfájl előző kiemelt sorai a következő viselkedéseket határozzák meg:

• <OutputType>exe</OutputType>: Létrehoz egy konzolalkalmazást.
• <PublishSingleFile Condition="'$(Configuration)' == 'Release'">true</PublishSingleFile>: Engedélyezi az egyfájlos közzétételt.
• <RuntimeIdentifier>win-x64</RuntimeIdentifier>: A win-x64RID-je van meghatározva.
• <PlatformTarget>x64</PlatformTarget>: Adja meg a célplatform 64 bites processzorát.

Ha közzé szeretné tenni az alkalmazást a Visual Studióból, létrehozhat egy megmaradó közzétételi profilt. A közzétételi profil XML-alapú, és .pubxml fájlkiterjesztéssel rendelkezik. A Visual Studio ezzel a profillal teszi közzé az alkalmazást implicit módon, míg ha a .NET CLI-t használja, explicit módon meg kell adnia a használni kívánt közzétételi profilt.

Kattintson a jobb gombbal a projektre a Megoldáskezelő, és válassza a Közzététellehetőséget. Ezután válassza a Közzétételi profil hozzáadása lehetőséget a profil létrehozásához. A Közzététel párbeszédpanelen válassza ki a Mappa mappát mint Cél.

Hagyja meg az alapértelmezett hely, majd válassza a Befejezéslehetőséget. A profil létrehozása után válassza Az összes beállítás megjelenítéselehetőséget, és ellenőrizze a profilbeállításokat.

Győződjön meg arról, hogy a következő beállítások vannak megadva:

• üzembehelyezési mód: Önálló
• Egyetlen fájl létrehozása: bejelölve
• ReadyToRun fordítás engedélyezése: bejelölve
• Nem használt szerelvények vágása (előzetes verzióban): nincs bejelölve

Végül válassza a Közzététellehetőséget. A rendszer lefordítja az alkalmazást, és az eredményként kapott .exe fájlt közzéteszi a /publish kimeneti könyvtárban.

Másik lehetőségként a .NET CLI-vel is közzéteheti az alkalmazást:

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

További információ: dotnet publish.

A Windows-szolgáltatás létrehozása

Ha nem ismeri a PowerShell használatát, és inkább szeretne egy telepítőt létrehozni a szolgáltatáshoz, olvassa el Windows-szolgáltatástelepítő létrehozásacímű témakört. Ellenkező esetben a Windows szolgáltatás létrehozásához használja a natív Windows Service Control Manager (sc.exe) létrehozási parancsát. Futtassa a PowerShellt rendszergazdaként.

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"

Megjelenik egy kimeneti üzenet:

[SC] CreateService SUCCESS

További információért lásd sc.exelétrehozását.

A Windows szolgáltatás konfigurálása

A szolgáltatás létrehozása után igény szerint konfigurálhatja. Ha megfelel a szolgáltatás alapértelmezéseinek, ugorjon a Szolgáltatás működésének ellenőrzése szakaszra.

A Windows Services helyreállítási konfigurációs lehetőségeket biztosít. Az aktuális konfigurációt a sc.exe qfailure "<Service Name>" (ahol <Service Name> a szolgáltatások neve) paranccsal kérdezheti le az aktuális helyreállítási konfigurációs értékek olvasásához:

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

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

A parancs a helyreállítási konfigurációt adja ki, amely az alapértelmezett érték – mivel még nincsenek konfigurálva.

A helyreállítás konfigurálásához használja azt a sc.exe failure "<Service Name>", ahol <Service Name> a szolgáltatás neve:

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

A sikeres konfigurálás után a sc.exe qfailure "<Service Name>" paranccsal ismét lekérdezheti az értékeket:

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.

Ekkor megjelennek a konfigurált újraindítási értékek.

Szolgáltatás helyreállítási lehetőségek és .NET BackgroundService példányok

A .NET 6-tal új üzemeltetési kivételkezelési viselkedések lettek hozzáadva a .NET-hez. A BackgroundServiceExceptionBehavior szám hozzá lett adva a Microsoft.Extensions.Hosting névtérhez, és a szolgáltatás viselkedésének megadására szolgál kivétel esetén. Az alábbi táblázat az elérhető lehetőségeket sorolja fel:

A .NET 6 előtti alapértelmezett viselkedés Ignore, ami zombifolyamatokat eredményezett (egy futó folyamat, amely nem csinált semmit). A .NET 6-ban az alapértelmezett viselkedés a StopHost, ami kivétel dobásakor azt eredményezi, hogy a gazdagép leállításra kerül. Ez azonban teljesen leáll, ami azt jelenti, hogy a Windows szolgáltatásfelügyeleti rendszere nem indítja újra a szolgáltatást. A szolgáltatás újraindításának helyes engedélyezése érdekében megadhat egy nem nulla kilépési kódot a Environment.Exit hívásához. Kérjük, vegye figyelembe a következő kiemelt catch blokkot:

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

A szolgáltatás működésének ellenőrzése

A Windows-szolgáltatásként létrehozott alkalmazás megtekintéséhez nyissa meg a Services. Válassza a Windows billentyűt (vagy Ctrl + Esc), és keressen a "Szolgáltatások" között. A Services alkalmazásban képesnek kell lennie megtalálni a szolgáltatást annak neve alapján.

Annak ellenőrzéséhez, hogy a szolgáltatás a várt módon működik-e, a következőkre van szükség:

• A szolgáltatás indítása
• A naplók megtekintése
• A szolgáltatás leállítása

A Windows szolgáltatás indítása

A Windows-szolgáltatás elindításához használja a sc.exe start parancsot:

sc.exe start ".NET Joke Service"

Az alábbihoz hasonló kimenet jelenik meg:

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

A szolgáltatás állapotSTART_PENDING állapotból futóállapotba vált át.

Naplók megtekintése

A naplók megtekintéséhez nyissa meg az Eseménynapló. Válassza a Windows billentyűt (vagy Ctrl + Esc), és keresse meg a "Event Viewer". Válassza ki az Eseménynapló (helyi)>Windows-naplók>alkalmazás csomópontot. Egy Figyelmeztetés szintű bejegyzésnek kell megjelennie olyan forrásként, amely az alkalmazások névterének felel meg. Kattintson duplán a bejegyzésre, vagy kattintson a jobb gombbal, és válassza Esemény tulajdonságai lehetőséget a részletek megtekintéséhez.

Miután naplókat látott az Események naplója-ben, le kell állítania a szolgáltatást. Úgy tervezték, hogy percenként egyszer naplózzanak egy véletlenszerű viccet. Ez szándékos viselkedés, de nem praktikus a gyártási szolgáltatásokhoz.

A Windows szolgáltatás leállítása

A Windows szolgáltatás leállításához használja a sc.exe stop parancsot:

sc.exe stop ".NET Joke Service"

Az alábbihoz hasonló kimenet jelenik meg:

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

A szolgáltatás állapot átáll STOP_PENDING-ről leállítottra.

A Windows-szolgáltatás törlése

A Windows-szolgáltatás törléséhez használja a natív Windows Service Control Manager (sc.exe) törlési parancsát. Futtassa a PowerShellt rendszergazdaként.

sc.exe delete ".NET Joke Service"

Megjelenik egy kimeneti üzenet:

[SC] DeleteService SUCCESS

További információért lásd: sc.exe töröl.

Lásd még:

• Windows-szolgáltatás telepítőjének létrehozása
• Worker szolgáltatások a .NET-ben
• Sorbaállási szolgáltatás létrehozása
• Kontrollált hatókörű szolgáltatások használata egy BackgroundService
• A IHostedService felület implementálása

Következő