Размещение ASP.NET Core в службе Windows

Приложение ASP.NET Core можно разместить в Windows в качестве службы Windows без использования IIS. При размещении в качестве службы Windows приложение автоматически запускается после перезагрузки сервера.

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

• Пакет SDK для ASP.NET Core 7.0 или более поздней версии
• PowerShell 6.2 или более поздней версии

Шаблон службы рабочей роли

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

1. Создайте приложение службы рабочей роли на основе шаблона .NET Core.
2. Установите пакет NuGet Microsoft.Extensions.Hosting.WindowsServices.
3. Согласно указаниям в разделе Конфигурация приложения измените приложение службы рабочей роли так, чтобы оно могло выполняться как служба Windows.

Visual Studio

1. Создание проекта
2. Выберите службу рабочей роли. Выберите Далее.
3. В поле Имя проекта укажите имя проекта или оставьте имя по умолчанию. Нажмите кнопку создания.
4. В диалоговом окне Создать службу рабочей роли выберите Создать.

Visual Studio для Mac

1. Создание проекта
2. В разделе .NET Core на боковой панели выберите Приложение.
3. В разделе ASP.NET Core выберите Рабочая роль. Выберите Далее.
4. Для параметра Требуемая версия .NET Framework выберите .NET Core 3.0 или более поздней версии. Выберите Далее.
5. Введите имя в поле Имя проекта. Нажмите кнопку создания.

Интерфейс командной строки.NET

Используйте шаблон службы рабочей роли (worker) с командой dotnet new из командной оболочки. В приведенном ниже примере создается приложение службы рабочей роли с именем ContosoWorker. Папка для приложения ContosoWorker создается автоматически при выполнении команды.

dotnet new worker -o ContosoWorker

конфигурация приложения;

Обновите Program.cs для вызова AddWindowsService. Когда приложение работает в качестве службы Windows, AddWindowsServiceвыполните следующие действия:

• Задает для узла время существования WindowsServiceLifetime.
• Задает для корневого каталога содержимого значение AppContext.BaseDirectory. Дополнительные сведения см. в разделе Текущий каталог и корневой каталог содержимого.
• Включает ведение журнала событий:
  • В качестве имени источника по умолчанию используется имя приложения.
  • Уровень ведения журнала по умолчанию — как минимум Предупреждение для приложения на базе шаблона ASP.NET Core, вызывающего CreateDefaultBuilder для сборки узла.
  • Уровень ведения журнала по умолчанию переопределяется с помощью ключа Logging:EventLog:LogLevel:Default в appsettings.json/appsettings.{Environment}.json или в другом поставщике конфигурации.
  • Только администраторы могут создавать источники событий. Если источник событий создать нельзя, используя имя приложения, для источника Приложение регистрируется предупреждение и журналы событий отключаются.

Рассмотрим следующий класс ServiceA:

namespace SampleApp.Services;

public class ServiceA : BackgroundService
{
    public ServiceA(ILoggerFactory loggerFactory)
    {
        Logger = loggerFactory.CreateLogger<ServiceA>();
    }

    public ILogger Logger { get; }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        Logger.LogInformation("ServiceA is starting.");

        stoppingToken.Register(() => Logger.LogInformation("ServiceA is stopping."));

        while (!stoppingToken.IsCancellationRequested)
        {
            Logger.LogInformation("ServiceA is doing background work.");

            await Task.Delay(TimeSpan.FromSeconds(5), stoppingToken);
        }

        Logger.LogInformation("ServiceA has stopped.");
    }
}

Следующий файл Program.cs вызывает AddHostedService для регистрации ServiceA:

using SampleApp.Services;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.AddWindowsService();
builder.Services.AddHostedService<ServiceA>();

var app = builder.Build();

app.MapRazorPages();

app.Run();

Этот раздел сопровождают следующие примеры приложений:

• Пример фоновой рабочей службы: пример не веб-приложения на основе шаблона рабочей службы, использующего размещенные службы для фоновых задач.
• Пример службы веб-приложений. Пример веб-приложения Razor Pages, которое выполняется как служба Windows с размещенными службами для фоновых задач.

Инструкции по MVC см. в статьях Общие сведения ASP.NET Core MVC и Миграция с ASP.NET Core 2.2 на 3.0.

Тип развертывания

Дополнительные сведения и рекомендации по сценариям развертывания см. в статье Развертывание приложений .NET Core.

SDK

Для службы на основе веб-приложений, которая использует платформы MVC или Razor Pages, укажите веб-пакет SDK в файле проекта.

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

Если служба выполняет только фоновые задачи (например, размещенные службы), укажите пакет SDK рабочей роли в файле проекта:

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

Зависящее от платформы развертывание (FDD)

Зависящее от платформы развертывание (FDD) требует наличия в целевой системе общей для всей системы версии .NET Core. Если сценарий с FDD используется согласно инструкций в этой статье, пакет SDK создаcт исполняемый файл (.exe), который называется исполняемым файлом, зависящим от платформы.

При использовании веб-пакета SDK, файл web.config, который обычно создается при публикации приложения ASP.NET Core, не требуется для приложения служб Windows. Отмените создание файла web.config, добавив свойство <IsTransformWebConfigDisabled> со значением true.

<PropertyGroup>
  <TargetFramework>net7.0</TargetFramework>
  <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
</PropertyGroup>

Автономное развертывание

Для автономного развертывания необязательно наличие общей платформы в системе размещения. Среда выполнения и зависимости приложения развертываются с приложением.

Идентификатор среды выполнения Windows включается в <PropertyGroup>, где содержится целевая платформа:

<RuntimeIdentifier>win-x64</RuntimeIdentifier>

Чтобы выполнить публикацию для нескольких идентификаторов RID, сделайте следующее.

• Укажите список идентификаторов RID, разделив их точкой с запятой.
• Используйте имя свойства <RuntimeIdentifiers> (во множественном числе).

Дополнительные сведения см. в каталоге RID для .NET Core.

Учетная запись пользователя службы

Создайте для службы учетную запись пользователя с помощью командлета New-LocalUser в административной оболочке PowerShell 6.

Обновление Windows 10 за октябрь 2018 г. (версия 1809, сборка 10.0.17763) или более поздней версии:

New-LocalUser -Name {SERVICE NAME}

Версия Windows, предшествующая обновлению Windows 10 за октябрь 2018 г. (версия 1809, сборка 10.0.17763):

powershell -Command "New-LocalUser -Name {SERVICE NAME}"

Укажите надежный пароль при появлении соответствующего запроса.

Параметр срока действия учетной записи DateTime можно задать с помощью параметра -AccountExpires, передаваемого в командлет New-LocalUser.

Дополнительные сведения см. в статьях Microsoft.PowerShell.LocalAccounts и Service User Accounts (Учетные записи пользователей служб).

Альтернативный подход к управлению пользователями при работе с Active Directory заключается в применении управляемых учетных записей служб. Дополнительные сведения см. в обзоре групповых управляемых учетных записей службы.

Права на вход в качестве службы

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

1. Откройте редактор локальной политики безопасности, запустив secpol.msc.
2. Разверните узел Локальные политики и выберите Назначение прав пользователя.
3. Откройте политику Вход в качестве службы.
4. Щелкните Добавить пользователя или группу.
5. Укажите имя объекта (учетная запись пользователя), используя любой из следующих подходов:
   1. Укажите учетную запись пользователя ({DOMAIN OR COMPUTER NAME\USER}) в поле для имени объекта и нажмите ОК, чтобы назначить политику пользователю.
   2. Выберите Дополнительно. Нажмите Найти. Выберите учетную запись пользователя из списка. Нажмите ОК. Нажмите ОК еще раз, чтобы назначить политику пользователю.
6. Нажмите ОК или Применить, чтобы сохранить изменения.

Создание службы Windows и управление ею

Создание сервиса

Зарегистрируйте службу с помощью команды PowerShell. В административной оболочке PowerShell 6 выполните следующие команды:

$acl = Get-Acl "{EXE PATH}"
$aclRuleArgs = "{DOMAIN OR COMPUTER NAME\USER}", "Read,Write,ReadAndExecute", "ContainerInherit,ObjectInherit", "None", "Allow"
$accessRule = New-Object System.Security.AccessControl.FileSystemAccessRule($aclRuleArgs)
$acl.SetAccessRule($accessRule)
$acl | Set-Acl "{EXE PATH}"

New-Service -Name {SERVICE NAME} -BinaryPathName "{EXE FILE PATH} --contentRoot {EXE FOLDER PATH}" -Credential "{DOMAIN OR COMPUTER NAME\USER}" -Description "{DESCRIPTION}" -DisplayName "{DISPLAY NAME}" -StartupType Automatic

• {EXE PATH}. Путь к исполняемому файлу приложения на узле (например, d:\myservice). Путь не должен включать имя исполняемого файла приложения. Завершающая косая черта не требуется.
• {DOMAIN OR COMPUTER NAME\USER}: учетная запись пользователя службы (например, Contoso\ServiceUser).
• {SERVICE NAME}: имя службы (например, MyService).
• {EXE FILE PATH}. Полный путь к исполняемому файлу приложения (например, d:\myservice\myservice.exe). Включите имя исполняемого файла с расширением.
• {EXE FOLDER PATH}: полный путь к папке с исполняемым файлом приложения (например, d:\myservice).
• {DESCRIPTION}: описание службы (например, My sample service).
• {DISPLAY NAME}: отображаемое имя службы (например, My Service).

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

Запустите службу с помощью следующей команды PowerShell 6:

Start-Service -Name {SERVICE NAME}

Команде потребуется несколько секунд, чтобы запустить службу.

Определение состояния службы

Чтобы проверить состояние службы, используйте следующую команду PowerShell 6:

Get-Service -Name {SERVICE NAME}

Состояние отображается одним из следующих значений:

• Starting
• Running
• Stopping
• Stopped

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

Остановите службу с помощью следующей команды PowerShell 6:

Stop-Service -Name {SERVICE NAME}

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

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

Remove-Service -Name {SERVICE NAME}

Сценарии использования прокси-сервера и подсистемы балансировки нагрузки

Для служб, которые взаимодействуют с запросами из Интернета или корпоративной сети и размещаются за прокси-сервером или подсистемой балансировки нагрузки, может потребоваться дополнительная настройка. Дополнительные сведения см. в разделе Настройка ASP.NET Core для работы с прокси-серверами и подсистемами балансировки нагрузки.

Настройка конечных точек

По умолчанию платформа ASP.NET Core привязана к http://localhost:5000. Настройте URL-адрес и порт, задав переменную среды ASPNETCORE_URLS.

Дополнительные сведения о подходах к настройке URL-адресов и портов см. в соответствующей статье сервера:

• Настройка конечных точек для веб-сервера Kestrel для ASP.NET Core
• реализация веб-сервера HTTP.sys в ASP.NET Core

В предыдущем руководстве рассматривается поддержка конечных точек HTTPS. Например, настройте приложение для HTTPS, если проверка подлинности используется со службой Windows.

Примечание.

Использование сертификата разработки ASP.NET Core HTTPS для защиты конечной точки службы не поддерживается.

Текущий каталог и корневой каталог содержимого

Текущий рабочий каталог, возвращенный путем вызова GetCurrentDirectory для службы Windows, — это папка C:\WINDOWS\system32. Папка system32 не подходит для хранения файлов службы (например, файлов параметров). Используйте один из следующих методов для сохранения ресурсов и файлов параметров службы и доступа к ним.

Использование ContentRootPath или ContentRootFileProvider

Используйте IHostEnvironment.ContentRootPath или ContentRootFileProvider для поиска ресурсов приложения.

Когда приложение запускается как служба, UseWindowsService задает для свойства ContentRootPath значение AppContext.BaseDirectory.

Файлы стандартных параметров приложения appsettings.jsonи appsettings.{Environment}.json загружаются из корневого каталога содержимого приложения путем вызова CreateDefaultBuilder во время создания узла.

Для других файлов параметров, загруженных с помощью кода разработчика в ConfigureAppConfiguration, не нужно вызывать SetBasePath. В следующем примере custom_settings.json файл существует в корневом каталоге содержимого приложения и загружается без явного задания базового пути:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .UseWindowsService()
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
                config.AddJsonFile("custom_settings.json");
            })
            .ConfigureServices((hostContext, services) =>
            {
                services.AddHostedService<Worker>();
            });
}

Не пытайтесь использовать GetCurrentDirectory, чтобы получить путь к ресурсу, так как приложение службы Windows возвращает папку C:\WINDOWS\system32 в качестве текущего каталога.

Хранение файлов службы в подходящем расположении на диске

Укажите абсолютный путь к папке, содержащей файлы, с помощью SetBasePath при использовании IConfigurationBuilder.

Устранение неполадок

Сведения об устранении неполадок в приложении службы Windows см. в статье Устранение неполадок и отладка проектов ASP.NET Core.

Распространенные ошибки

• Используется старая или предварительная версия PowerShell.
• Зарегистрированная служба не использует опубликованные выходные данные приложения, возвращенные командой dotnet publish. Выходные данные команды dotnet build не поддерживаются для развертывания приложений. Опубликованные ресурсы находятся в любой из следующих папок в зависимости от типа развертывания:
  • bin/Release/{TARGET FRAMEWORK}/publish (зависящее от платформы развертывание);
  • bin/Release/{TARGET FRAMEWORK}/{RUNTIME IDENTIFIER}/publish (автономное развертывание).
• Служба не находится в состоянии выполнения.
• Пути к используемым приложением ресурсам (например, к сертификатам) неверные. Базовый путь к службе Windows — c:\Windows\System32.
• У пользователя отсутствуют права для входа в систему в качестве службы.
• Пароль был указан неверно или его срок действия истек при выполнении команды PowerShell New-Service.
• Для приложения требуется выполнить проверку подлинности в ASP.NET Core, однако оно не настроено для безопасных подключений (HTTPS).
• Порт URL-адреса запроса неправильно указан или настроен в приложении.

Журналы событий системы и приложений

Получите доступ к журналам событий системы и приложений:

1. Откройте меню "Пуск", выполните поиск по фразе Просмотр событий и выберите приложение Просмотр событий.
2. В средстве просмотра событий откройте узел Журналы Windows.
3. Выберите Система, чтобы открыть журнал системных событий. Выберите Приложение, чтобы открыть журнал событий приложения.
4. Проверьте здесь наличие ошибок, связанных с проблемным приложением.

Запуск приложения в командной строке

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

Очистка кэшей пакетов

Приложения-функции могут перестать работать сразу после обновления пакета SDK для .NET Core на компьютере разработки или обновления версии пакетов в самом приложении. В некоторых случаях в результате важного обновления несогласованные версии пакетов могут привести к нарушению работы приложения. Большинство этих проблем можно исправить следующим образом:

1. Удалите папки bin и obj.

2. Очистите кэши пакетов, выполнив команду dotnet nuget locals all --clear из командной оболочки.

   Очистку кэшей пакетов также можно выполнить с помощью средства nuget.exe или команды nuget locals all -clear. NuGet.exe не входит в пакет установки операционной системы Windows для настольных компьютеров и его нужно получить отдельно на веб-сайте NuGet.

3. Восстановите и перестройте проект.

4. Удалите все файлы из папки развертывания на сервере, прежде чем повторно развернуть приложение.

Медленно работающее или неотвечающее приложение

Аварийный дамп — это моментальный снимок системной памяти, который может помочь определить причину аварийного завершения, сбоя запуска или медленной работы приложения.

Аварийное завершение работы приложения или исключение

Получите и проанализируйте дамп из отчетов об ошибках Windows (WER):

1. Создайте папку для хранения файлов аварийного дампа в c:\dumps.

2. Запустите скрипт PowerShell EnableDumps с именем исполняемого файла приложения:

   .\EnableDumps {APPLICATION EXE} c:\dumps
   

3. Запустите приложение в условиях, вызывающих аварийное завершение.

4. После аварийного завершения запустите скрипт PowerShell DisableDumps:

   .\DisableDumps {APPLICATION EXE}
   

Когда приложение аварийно завершит работу и сбор дампов будет выполнен, приложение сможет завершить работу обычным образом. Скрипт PowerShell настраивает отчеты об ошибках Windows для сбора до пяти дампов для приложения.

Предупреждение

Аварийные дампы могут занимать много места на диске (до нескольких гигабайтов каждый).

Приложение не отвечает на запросы, не запускается или работает в обычном режиме

Когда приложение перестает отвечать, но не завершает работу, завершается сбоем во время запуска или выполняется нормально, см . раздел "Файлы дампа в режиме пользователя": выбор оптимального инструмента для выбора соответствующего инструмента для создания дампа.

Анализ дампа

Дамп можно проанализировать несколькими способами. Дополнительные сведения см. в разделе Анализ файла дампа пользовательского режима.

Дополнительные ресурсы

• Просмотреть или скачать образец кода (описание загрузки)
• Конфигурация конечных точек Kestrel (включает конфигурацию HTTPS и поддержку SNI)
• Универсальный узел .NET в ASP.NET Core
• Устранение неполадок и отладка проектов ASP.NET Core