hostBuilder.UseWindowsService

原创于 2025-07-29 14:39:57 发布 · 264 阅读

1 ·

CC 4.0 BY-SA版权

文章标签：

#.netcore

hostBuilder.UseWindowsService(); 是 .NET 中用于将控制台应用程序转换为 Windows 服务的关键配置方法。这个方法简化了服务开发流程，让你可以用相同的代码同时支持控制台和服务两种运行模式。

核心功能

无缝转换为服务
- 无需继承 ServiceBase 类，直接将 IHost 注册为 Windows 服务。
- 自动处理服务生命周期（启动、停止、暂停、恢复）。
双模式支持
- 代码可通过控制台直接运行（便于调试），也可作为服务安装运行。
服务元数据配置
- 通过 WindowsServiceLifetimeOptions 自定义服务名称、描述和启动类型。

应用场景

后台服务开发：长时间运行的进程（如文件监控、定时任务）。
微服务架构：将 .NET 应用部署为系统服务。
遗留服务迁移：从 .NET Framework 迁移到 .NET 6+ 的服务。

使用方法

1. 安装 NuGet 包

dotnet add package Microsoft.Extensions.Hosting.WindowsServices

2. 配置 HostBuilder

在 Program.cs 中添加 UseWindowsService()：

using Microsoft.Extensions.Hosting;

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

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureServices((hostContext, services) =>
        {
            // 注册服务逻辑
            services.AddHostedService<MyBackgroundService>();
        })
        // 启用 Windows 服务支持
        .UseWindowsService();

3. 实现后台服务逻辑

创建一个继承自 BackgroundService 的类：

public class MyBackgroundService : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            // 执行周期性任务
            Console.WriteLine("服务运行中...");
            await Task.Delay(1000, stoppingToken);
        }
    }
}

服务安装与管理

1. 手动安装服务

使用 sc.exe 命令：

sc create MyService binPath= "C:\Path\To\YourApp.exe"
sc start MyService

2. 使用工具自动安装

推荐使用 dotnet-win32-service 工具：

# 安装工具
dotnet tool install -g dotnet-win32-service

# 安装服务
dotnet-win32-service install --name "MyService" --exe "C:\Path\To\YourApp.exe"

高级配置

自定义服务元数据：

Host.CreateDefaultBuilder(args)
    .UseWindowsService(options =>
    {
        options.ServiceName = "MyCustomService";
        options.StartMode = ServiceStartMode.AutomaticDelayedStart;
    })
    .ConfigureServices(...)

注意事项

双模式检测
- 服务模式下无法直接访问控制台输出，需使用日志记录（如 ILogger）。
- 可通过 Environment.UserInteractive 判断运行模式：
  csharp
```
if (Environment.UserInteractive)
{
    // 控制台模式逻辑
}
else
{
    // 服务模式逻辑
}
```
权限要求
- 安装 / 卸载服务需要管理员权限。
- 服务默认以 LocalSystem 账户运行，可能需要调整权限。
跨平台限制
- UseWindowsService() 仅在 Windows 上有效。若需跨平台，可使用 UseSystemd()（Linux）或 UseLifetime<YourCustomLifetime>()。

服务生命周期事件

通过重写 BackgroundService 方法响应服务事件：

public class MyBackgroundService : BackgroundService
{
    public override Task StartAsync(CancellationToken cancellationToken)
    {
        // 服务启动时执行
        return base.StartAsync(cancellationToken);
    }

    public override Task StopAsync(CancellationToken cancellationToken)
    {
        // 服务停止时执行
        return base.StopAsync(cancellationToken);
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // 服务主逻辑
    }
}