Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/CodeCasterNL/WindowsServiceExtensions
Create resilient Windows Services that get informed about power and session events.
https://github.com/CodeCasterNL/WindowsServiceExtensions
windows-service
Last synced: 5 days ago
JSON representation
Create resilient Windows Services that get informed about power and session events.
- Host: GitHub
- URL: https://github.com/CodeCasterNL/WindowsServiceExtensions
- Owner: CodeCasterNL
- License: mit
- Created: 2021-05-19T09:05:01.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2022-07-03T13:18:20.000Z (over 2 years ago)
- Last Synced: 2024-08-02T16:51:40.443Z (3 months ago)
- Topics: windows-service
- Language: C#
- Homepage: https://codecasternl.github.io/WindowsServiceExtensions/
- Size: 88.9 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: Readme.md
- License: LICENSE
Awesome Lists containing this project
README
# Windows Service Extensions
Building a basic Windows Service that does some long-running background work is trivial, using .NET's [`UseWindowsService()`](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.hosting.windowsservicelifetimehostbuilderextensions.usewindowsservice?view=dotnet-plat-ext-6.0) (from the Platform Extensions package `Microsoft.Extensions.Hosting.WindowsServices`) and [`Microsoft.Extensions.Hosting.BackgroundService`](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.hosting.backgroundservice?view=dotnet-plat-ext-6.0) from `Microsoft.Extensions.Hosting.Abstractions`.Running as a _Windows Service_ and _running BackgroundServices_ are two separate things though, and they are not connected in any way. A non-service console app can run background services, and so can and do web applications. Each of those are different hosting environments, with their own lifetimes.
This project exists of a few classes that make building reliable Windows Services easier, to gap this disconnect.
## Lifetime
The following improvements are included in this library:* `OnStart()` can fail because of invalid service configuration, quit the application when that happens (by [kmcclellan](https://github.com/dotnet/runtime/issues/50019#issuecomment-678658133)).
* On consumer OS Windows 10+, shutting down the computer will actually hibernate the OS. Services won't get another `OnStart()` call when the computer starts again, nor will your background services be notified. Now they will.
* It also can notify your BackgroundServices about user session changes, i.e. logon, logoff and others.
* When an exception occurs during your BackgroundService's lifetime, .NET Platform Extensions < 6 didn't stop the application host. Now it does, but it doesn't report an error to the Service Control Manager. With this extension, it does, as well as setting a process exit code: 13 in both cases ("invalid data").## Installation
Through [NuGet](https://www.nuget.org/packages/CodeCaster.WindowsServiceExtensions/):> Install-Package CodeCaster.WindowsServiceExtensions
## Usage
These methods from this package allow your `IHostedService`s to tell the Windows Service Control Manager about errors, and respond to Windows Service events relating to sessions (user logon/logoff) and power state (shutdown/hibernate/resume):* On your Host Builder, call `UseWindowsServiceExtensions()` instead of `UseWindowsService()`.
* Instead of letting your service inherit `BackgroundService`, inherit from `CodeCaster.WindowsServiceExtensions.WindowsServiceBackgroundService`.
* Implement `protected Task TryExecuteAsync(CancellationToken stoppingToken)` instead of `ExecuteAsync(CancellationToken stoppingToken)`.
* Implement the method `public override bool OnPowerEvent(PowerBroadcastStatus powerStatus) { ... }` and do your thing when it's called with a certain status.
* Implement the method `public override bool OnSessionChange(SessionChangeDescription changeDescription) { ... }` and do your thing when it's called with a certain status.Do note that the statuses received can vary. You get either `ResumeSuspend`, `ResumeAutomatic` or both reported to `OnPowerEvent()`, never neither, after a machine wake, reboot or boot.
## Documentation
For examples and more specific documentation, see https://codecasternl.github.io/WindowsServiceExtensions/.## Upgrading from v2 to v3
If you're one of the souls that use this library (who _are_ you?), you'll want to upgrade to v3.0 after upgrading your projects to .NET 6.Changes:
* The DI extension method `IHostBuilder.UsePowerEventAwareWindowsService()` is now called `UseWindowsServiceExtensions()` because we do more than power events now.
* The long-running hosted service base class `CodeCaster.WindowsServiceExtensions.PowerEventAwareBackgroundService` was renamed to `CodeCaster.WindowsServiceExtensions.Service.WindowsServiceBackgroundService`, because the former didn't have enough "Service" in its name.
* Instead of `BackgroundService.ExecuteAsync()`, which is now sealed, override `WindowsServiceBackgroundService.TryExecuteAsync()` to do your long-running work.Extended upgrading docs: see https://codecasternl.github.io/WindowsServiceExtensions/upgrading-v2-v3.
# Contributing
Please file an issue or PR. Even if you use this and are happy with it.