Merge branch 'develop' into main

Author: CodeCasterNL

CodeCaster.WindowsServiceExtensions.sln

@@ -16,6 +16,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "GitHub Workflows", "GitHub
 		.github\workflows\Publish-Package.yml = .github\workflows\Publish-Package.yml
 	EndProjectSection
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "TestServiceThatThrows", "test\TestServiceThatThrows\TestServiceThatThrows.csproj", "{A426812E-CB26-47F2-B914-17D87312C51F}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -26,6 +28,10 @@ Global
 		{CC230E5D-8600-4048-8F10-E84A80F77DDC}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{CC230E5D-8600-4048-8F10-E84A80F77DDC}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{CC230E5D-8600-4048-8F10-E84A80F77DDC}.Release|Any CPU.Build.0 = Release|Any CPU
+		{A426812E-CB26-47F2-B914-17D87312C51F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{A426812E-CB26-47F2-B914-17D87312C51F}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{A426812E-CB26-47F2-B914-17D87312C51F}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{A426812E-CB26-47F2-B914-17D87312C51F}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

src/CodeCaster.WindowsServiceExtensions/CodeCaster.WindowsServiceExtensions.csproj

@@ -14,6 +14,7 @@
     <Company />
     <Copyright>CodeCaster</Copyright>
     <Description>Makes your .NET 5 BackgroundServices power-event-aware.</Description>
+    <Version>2.0.0</Version>
   </PropertyGroup>
 
   <ItemGroup>

src/CodeCaster.WindowsServiceExtensions/IPowerEventAwareHostedService.cs

@@ -3,8 +3,14 @@
 
 namespace CodeCaster.WindowsServiceExtensions
 {
+    /// <summary>
+    /// An <see cref="IHostedService"/> that runs as a Windows Service that can react to power state changes.
+    /// </summary>
     public interface IPowerEventAwareHostedService : IHostedService
     {
-        bool OnPowerEvent(PowerBroadcastStatus powerStatus);
+        /// <summary>
+        /// Called when a power event is sent by the OS.
+        /// </summary>
+        void OnPowerEvent(PowerBroadcastStatus powerStatus);
     }
 }

src/CodeCaster.WindowsServiceExtensions/PowerEventAwareBackgroundService.cs

@@ -3,15 +3,16 @@
 
 namespace CodeCaster.WindowsServiceExtensions
 {
+    /// <summary>
+    /// Base class for implementing a long running <see cref="IHostedService"/> as a Windows Service that can react to power state changes.
+    /// </summary>
     public abstract class PowerEventAwareBackgroundService : BackgroundService, IPowerEventAwareHostedService
     {
         /// <summary>
         /// Override this method to react to power state changes.
         /// </summary>
-        /// <returns>Return false to deny the power change status request.</returns>
-        public virtual bool OnPowerEvent(PowerBroadcastStatus powerStatus)
+        public virtual void OnPowerEvent(PowerBroadcastStatus powerStatus)
         {
-            return true;
         }
     }
 }

src/CodeCaster.WindowsServiceExtensions/PowerEventAwareWindowsServiceLifetime.cs

@@ -12,6 +12,9 @@
 
 namespace CodeCaster.WindowsServiceExtensions
 {
+    /// <summary>
+    /// Basically the same as <see cref="WindowsServiceLifetime"/>, but states it can handle power events, and forwards those to the IHostedServices that claim to be capable of the same.
+    /// </summary>
     public class PowerEventAwareWindowsServiceLifetime : WindowsServiceLifetime, IHostLifetime
     {
         private readonly CancellationTokenSource _starting = new();
@@ -64,6 +67,7 @@ public PowerEventAwareWindowsServiceLifetime(IServiceProvider serviceProvider, I
             }
         }
 
+        /// <inheritdoc />
         protected override bool OnPowerEvent(PowerBroadcastStatus powerStatus)
         {
             _logger.LogInformation($"Windows Service power event: {powerStatus}");
@@ -74,18 +78,14 @@ protected override bool OnPowerEvent(PowerBroadcastStatus powerStatus)
                 return true;
             }
 
-            var acceptEvent = true;
-
+            // Forward the event to all registered I(PowerEventAware)HostedServices.
             foreach (var service in _hostedServices)
             {
-                if (!service.OnPowerEvent(powerStatus))
-                {
-                    // If any of the hosted services returns false, we deny the power status change request by returning false from this method (does that even work?)
-                    acceptEvent = false;
-                }
+                service.OnPowerEvent(powerStatus);
             }
 
-            return acceptEvent;
+            // Ignored anyway.
+            return true;
         }
 
         protected override void OnStart(string[] args)
@@ -101,6 +101,7 @@ protected override void OnStart(string[] args)
             if (!_applicationLifetime.ApplicationStarted.IsCancellationRequested)
             {
                 // Usually very early in the startup process, so this may not be logged nor reported at all.
+                // But it's here to prevent the service from happily reporting successful startup, while the .NET Core ApplicationHost isn't started at all.
                 const string errorString = "Windows Service failed to start";
                 _logger.LogError(errorString);
                 throw new Exception(errorString);

src/CodeCaster.WindowsServiceExtensions/WindowsServiceLifetimeHostBuilderExtensionsAdapter.cs

@@ -6,19 +6,40 @@
 
 namespace CodeCaster.WindowsServiceExtensions
 {
+    /// <summary>
+    /// Extension method for setting up <see cref="PowerEventAwareWindowsServiceLifetime"/>.
+    /// </summary>
     public static class WindowsServiceLifetimeHostBuilderExtensionsAdapter
     {
-        public static IHostBuilder UsePowerEventAwareWindowsService(this IHostBuilder builder)
+        /// <summary>
+        /// Sets the host lifetime to <see cref="PowerEventAwareWindowsServiceLifetime"/> and does whatever <see cref="WindowsServiceLifetimeHostBuilderExtensions.UseWindowsService(IHostBuilder)"/> does.
+        /// </summary>
+        /// <param name="hostBuilder">The Microsoft.Extensions.Hosting.IHostBuilder to operate on.</param>
+        /// <returns>The same instance of the Microsoft.Extensions.Hosting.IHostBuilder for chaining.</returns>
+        /// <remarks>This is context aware and will only activate if it detects the process is running as a Windows Service.</remarks>
+        public static IHostBuilder UsePowerEventAwareWindowsService(this IHostBuilder hostBuilder)
+        {
+            return UsePowerEventAwareWindowsService(hostBuilder, _ => { });
+        }
+
+        /// <summary>
+        /// Sets the host lifetime to <see cref="PowerEventAwareWindowsServiceLifetime"/> and does whatever <see cref="WindowsServiceLifetimeHostBuilderExtensions.UseWindowsService(IHostBuilder)"/> does.
+        /// </summary>
+        /// <param name="hostBuilder">The Microsoft.Extensions.Hosting.IHostBuilder to operate on.</param>
+        /// <param name="configure">An action to configure the lifetime's options.</param>
+        /// <returns>The same instance of the Microsoft.Extensions.Hosting.IHostBuilder for chaining.</returns>
+        /// <remarks>This is context aware and will only activate if it detects the process is running as a Windows Service.</remarks>
+        public static IHostBuilder UsePowerEventAwareWindowsService(this IHostBuilder hostBuilder, Action<WindowsServiceLifetimeOptions> configure)
         {
             if (!WindowsServiceHelpers.IsWindowsService())
             {
-                return builder;
+                return hostBuilder;
             }
 
             // Call MS's one
-            builder.UseWindowsService();
+            hostBuilder.UseWindowsService(configure);
 
-            return builder.ConfigureServices(services =>
+            return hostBuilder.ConfigureServices(services =>
             {
                 // Replace UseWindowsService()'s IHostLifetime lifetime with our own
                 var lifetime = services.FirstOrDefault(s => s.ImplementationType == typeof(WindowsServiceLifetime));

test/TestServiceThatThrows/Program.cs

@@ -0,0 +1,55 @@
+using System;
+using System.Diagnostics;
+using System.Threading;
+using System.Threading.Tasks;
+using CodeCaster.WindowsServiceExtensions;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+
+namespace TestServiceThatThrows
+{
+    public class MyFaultyService : IHostedService
+    {
+        public Task StartAsync(CancellationToken cancellationToken)
+        {
+            throw new InvalidOperationException("This service is not supposed to start.");
+        }
+
+        public Task StopAsync(CancellationToken cancellationToken)
+        {
+            return Task.CompletedTask;
+        }
+    }
+
+    public class MyFaultyBackgroundService : BackgroundService
+    {
+        protected override Task ExecuteAsync(CancellationToken stoppingToken)
+        {
+            // This works: gets logged in the event log, and prevents service startup.
+            throw new InvalidOperationException("This service is not supposed to start.");
+        }
+    }
+
+    public static class Program
+    {
+        public static async Task Main(string[] args)
+        {
+            Thread.Sleep(5000);
+            Debugger.Break();
+
+            await new HostBuilder()
+                .ConfigureLogging(l => l.AddConsole())
+                .ConfigureServices((s) =>
+                {
+                    //throw new InvalidOperationException("Heh");
+                    //s.AddHostedService<MyFaultyService>();
+                    s.AddHostedService<MyFaultyBackgroundService>();
+                })
+                .UseWindowsService()
+                //.UsePowerEventAwareWindowsService()
+                .Build()
+                .RunAsync();
+        }
+    }
+}

test/TestServiceThatThrows/TestServiceThatThrows.csproj

@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net5.0</TargetFramework>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\CodeCaster.WindowsServiceExtensions\CodeCaster.WindowsServiceExtensions.csproj" />
+  </ItemGroup>
+
+</Project>