Создание службы Windows с помощью BackgroundService

Разработчики на платформе .NET Framework, вероятно, знакомы с приложениями служб Windows. До .NET Core и .NET 5+ разработчики, использующие платформу .NET Framework, могли создавать службы Windows для выполнения фоновых задач или выполнения долгосрочных процессов. Эта функциональность по-прежнему доступна, и вы можете создавать рабочие службы, запускаемые в качестве службы Windows.

Из этого руководства вы узнаете, как выполнять следующие задачи:

Необходимые компоненты

• Пакет SDK для .NET 8.0 или более поздней версии
• ОС Windows
• Интегрированная среда разработки .NET (IDE)
  • Можно использовать Visual Studio

Создание нового проекта

Чтобы создать новый проект службы рабочей роли с помощью Visual Studio, выберите Файл>Создать>Проект. В диалоговом окне Создание нового проекта выполните поиск по запросу "служба рабочей роли" и выберите шаблон "Служба рабочей роли". Если вы предпочитаете использовать .NET CLI, откройте используемый терминал в рабочем каталоге. Выполните команду dotnet new и замените <Project.Name> именем проекта.

dotnet new worker --name <Project.Name>

Дополнительные сведения о команде .NET CLI для создания проекта службы рабочей роли см. здесь.

Установка пакета NuGet

Чтобы взаимодействовать с собственными службами Windows из реализаций .NET IHostedService , необходимо установить Microsoft.Extensions.Hosting.WindowsServices пакет NuGet.

Чтобы установить его из Visual Studio, откройте диалоговое окно Управление пакетами NuGet. Выполните поиск по запросу "Microsoft.Extensions.Hosting.WindowsServices" и установите пакет. Если вы используете интерфейс командной строки .NET, выполните команду dotnet add package:

dotnet add package Microsoft.Extensions.Hosting.WindowsServices

Дополнительные сведения о команде добавления пакета в .NET CLI см. в разделе dotnet add package.

После успешного добавления пакетов файл проекта должен содержать следующие ссылки на пакеты:

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

Обновление файла проекта

Этот рабочий проект использует ссылочные типы C#, допускающие значение NULL. Чтобы включить их для всего проекта, обновите файл проекта соответствующим образом:

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

В приведенном выше изменении файла проекта добавляется узел <Nullable>enable<Nullable>. Дополнительные сведения см. в разделе Задание контекста, допускающего значение NULL.

Создание службы

Добавьте новый класс в проект с именем JokeService.cs и замените его содержимое следующим кодом 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);

Предыдущий исходный код службы шутки предоставляет один элемент функциональности, GetJoke метод. Это string возвращающий метод, представляющий шутку случайного программирования. Поле класса область используется _jokes для хранения списка шуток. Случайная шутка выбирается из списка и возвращается.

Перезапись класса Worker

Замените содержимое Worker из шаблона следующим кодом C# и переименуйте файл в 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);
        }
    }
}

В приведенном выше коде JokeService вставляется вместе с ILogger. Оба доступны для класса в качестве полей private readonly. В методе ExecuteAsync служба joke запрашивает шутку и записывает ее в средство ведения журнала. В этом случае средство ведения журнала реализуется журналом событий Windows — Microsoft.Extensions.Logging.EventLog.EventLogLogger. Записанные журналы сохраняются и доступны для ознакомления в Просмотре событий.

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

Перезапись класса Program

Замените содержимое файла шаблона Program.cs следующим кодом 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();

Метод расширения AddWindowsService настраивает приложение для работы в качестве службы Windows. Для имени службы задано значение ".NET Joke Service". Размещенная служба зарегистрирована для внедрения зависимостей.

Дополнительные сведения о регистрации служб см. в статье Внедрение зависимостей в .NET.

Публикация приложения

Чтобы создать приложение службы рабочей роли .NET в качестве службы Windows, лучше всего публиковать приложение как один исполняемый файл. Наличие автономного исполняемого файла с меньшей вероятностью приводит к ошибкам, так как в этом шаблоне не нужно размещать в файловой системе зависимые файлы. Но вы можете выбрать другую модальность публикации, и это совершенно допустимо, если вы правильно создаете файл *.exe, который может быть целевым для диспетчера управления службами 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>

Ранее выделенные строки файла проекта определяют следующие варианты поведения:

• <OutputType>exe</OutputType>. Создание консольного приложения.
• <PublishSingleFile Condition="'$(Configuration)' == 'Release'">true</PublishSingleFile>. Включение однофайловой публикации.
• <RuntimeIdentifier>win-x64</RuntimeIdentifier>: определяет RID для win-x64.
• <PlatformTarget>x64</PlatformTarget>: определяет 64-разрядный ЦП целевой платформы.

Чтобы опубликовать приложение из Visual Studio, можно создать профиль публикации, который сохраняется. Профиль публикации основан на XML и имеет расширение файла .pubxml. Visual Studio использует этот профиль для публикации приложения неявно, в то время как при использовании .NET CLI необходимо явно указать профиль публикации для его использования.

Щелкните правой кнопкой проект в Обозревателе решения, а затем выберите команду Опубликовать.... После этого выберите Добавить профиль публикации, чтобы создать профиль. В диалоговом окне Публикация выберите значение Папка в поле Цель.

В поле Расположение оставьте значение по умолчанию, а затем щелкните Готово. После создания профиля выберите Показать все настройки и проверьте Настройки профиля.

Убедитесь, что заданы такие параметры:

• Режим развертывания: автономно
• Производить один файл: проверено
• Включить компиляцию ReadyToRun: проверено
• Обрезать неиспользуемые сборки (в предварительной версии): флажок не установлен

Наконец, нажмите кнопку Опубликовать. Приложение компилируется, а полученный файл EXE публикуется в выходном каталоге /publish.

Кроме того, для публикации приложения можно использовать интерфейс командной строки .NET.

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

Дополнительные сведения см. в разделе dotnet publish.

Создание службы Windows

Если вы не знакомы с помощью PowerShell и хотите создать установщик для службы, см. статью "Создание установщика службы Windows". В противном случае для создания службы Windows используйте собственную команду диспетчера управления службами Windows (sc.exe). Откройте PowerShell от имени администратора.

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"

Вы увидите выходное сообщение:

[SC] CreateService SUCCESS

Дополнительные сведения см. в разделе sc.exe create.

Настройка службы Windows

После создания службы ее можно дополнительно настроить. Если вас устраивают настройки службы по умолчанию, перейдите к разделу Проверка функциональности службы.

Службы Windows предоставляют параметры конфигурации восстановления. Чтобы прочитать текущие значения конфигурации восстановления, можно запросить текущую конфигурацию, используя команду sc.exe qfailure "<Service Name>" (где <Service Name> — имя службы).

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

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

Команда выводит конфигурацию восстановления, которая является значениями по умолчанию, так как они еще не настроены.

Чтобы настроить восстановление, используйте команду sc.exe failure "<Service Name>", где <Service Name> — имя службы:

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

После успешной настройки можно снова запросить значения с помощью команды 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.

Вы увидите настроенные значения перезапуска.

Параметры восстановления службы и экземпляры .NET BackgroundService

При использовании .NET 6 в .NET добавлены новые функции обработки исключений для размещения. Перечисление BackgroundServiceExceptionBehavior было добавлено в Microsoft.Extensions.Hosting пространство имен и используется для указания поведения службы при возникновении исключения. Доступные параметры перечислены в следующей таблице:

Поведение по умолчанию до .NET 6 Ignore, которое привело к зомби-процессам (выполняющийся процесс, который ничего не делал). При использовании .NET 6 по умолчанию используется StopHostповедение по умолчанию, которое приводит к остановке узла при возникновении исключения. Но она останавливается чисто, что означает, что система управления службами Windows не перезагрузит службу. Чтобы правильно разрешить перезапуску службы, можно вызвать Environment.Exit с помощью кода выхода, отличного от нуля. Рассмотрим следующий выделенный 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);
        }
    }
}

Проверка функциональности службы

Чтобы увидеть приложение, созданное как служба Windows, откройте апплет Службы. Выберите ключ Windows (или нажмите сочетание клавиш Ctrl + Esc) и выполните поиск по запросу "службы". В апплете Службы вы сможете найти службу по ее имени.

Чтобы убедиться, что служба работает должным образом, необходимо выполнить следующие действия.

• Запуск службы
• Просмотр журналов
• Остановить службу

Запуск службы Windows

Чтобы запустить службу Windows, используйте команду sc.exe start:

sc.exe start ".NET Joke Service"

Появится результат, аналогичный указанному ниже.

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

Состояние службы изменится с START_PENDING на Выполняется.

Просмотреть журналы

Чтобы просмотреть журналы, откройте Средство просмотра событий. Выберите ключ Windows (или нажмите сочетание клавиш Ctrl + Esc) и выполните поиск по запросу "Event Viewer". Выберите узел Средство просмотра событий (локально)>Журналы Windows>Приложение. Вы должны увидеть запись уровня Предупреждения и Источник, который соответствует пространству имен приложений. Дважды щелкните запись или щелкните правой кнопкой мыши и выберите Свойства события, чтобы просмотреть подробные сведения.

После просмотра журналов в Журнале событий службу следует остановить. Она предназначена для записи одной случайной шутки в минуту. Такая реакция на событие и задумана, но это непрактично для рабочих служб.

Останов службы Windows

Чтобы остановить службу Windows, используйте команду sc.exe stop:

sc.exe stop ".NET Joke Service"

Появится результат, аналогичный указанному ниже.

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

Состояние службы перейдет с STOP_PENDING остановленного.

Удаление службы Windows

Чтобы удалить службу Windows, используйте собственную команду удаления (sc.exe) диспетчера служб Windows. Откройте PowerShell от имени администратора.

sc.exe delete ".NET Joke Service"

Вы увидите выходное сообщение:

[SC] DeleteService SUCCESS

Дополнительные сведения см. в разделе sc.exe delete.

См. также

• Создание установщика службы Windows
• Службы рабочей роли в .NET
• Создание службы очередей
• Использование служб с заданной областью в BackgroundService
• Реализация интерфейса IHostedService

Следующий