More docs, .NET 5 compatibility(.NET 6 stops the host on exception)

Author: CodeCasterNL

.github/workflows/Publish-Package.yml

@@ -23,10 +23,10 @@ jobs:
         dotnet-version: 5.0.x
 
     - name: Restore dependencies
-      run: dotnet restore
+      run: dotnet restore CodeCaster.WindowsServiceExtensions.sln
 
     - name: Build
-      run: dotnet build --no-restore --configuration=Release -p:Version=${{ steps.git_version.outputs.version-without-v }}
+      run: dotnet build CodeCaster.WindowsServiceExtensions.sln --no-restore --configuration=Release -p:Version=${{ steps.git_version.outputs.version-without-v }}
 
     - name: Release to GitHub
       uses: softprops/action-gh-release@v1

docs/index.md

@@ -41,7 +41,7 @@ public class MyCoolBackgroundService : BackgroundService
 }
 ```
 
-As long as your `ExecuteAsync()` runs, you have a _.NET_ (not Widows!) background service (`IHostedService`) running. When a hosted service throws an exception, that will stop the .NET Host that runs your application, and an event will be logged (as long as it exists and/or permisions are adequate).
+As long as your `ExecuteAsync()` runs, you have a _.NET_ (not Widows!) background service (`IHostedService`) running. When service start immediately throws an exception, that will stop the .NET Host that runs your application, and an event will be logged (as long as it exists and/or permisions are adequate).
 
 ## Lifetime
 So far, so good, but...
@@ -67,14 +67,39 @@ var hostBuilder = new HostBuilder()
     .UseWindowsServiceExtensions();
 ```
 
+## TryExecuteAsync
+This library seals `Microsoft.Extensions.Hosting.BackgroundService.ExecuteAsync()`, to stop the host when an exception occurs in a background service. To apply this to your code, inherit from `CodeCaster.WindowsServiceExtensions.HostTerminatingBackgroundService` instead of [`Microsoft.Extensions.Hosting.BackgroundService`](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.hosting.backgroundservice?view=dotnet-plat-ext-5.0).
+
+```csharp
+public class MyCoolBackgroundService : BackgroundService
+{
+    private readonly ILogger<MyCoolBackgroundService> _logger;
+
+    public MyCoolBackgroundService(ILogger<MyCoolBackgroundService> logger, IHostApplicationLifetime applicationLifetime)
+        : base(logger, applicationLifetime)
+    {
+        _logger = logger;
+    }
+
+    protected override async Task TryExecuteAsync(CancellationToken stoppingToken)
+    {
+        // Fake doing at least some work...
+        await Task.Delay(1000, stoppingToken);
+
+        // This will now stop the host application.
+        throw new InvalidOperationException("This service is not supposed to start");
+    }
+}
+```
+
 ## Power events
-If you let your service inherit `PowerEventAwareBackgroundService` instead of [`Microsoft.Extensions.Hosting.BackgroundService`](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.hosting.backgroundservice?view=dotnet-plat-ext-5.0) (the former inherits the latter), you get a new method:
+If you let your service inherit `CodeCaster.WindowsServiceExtensions.PowerEventAwareBackgroundService` instead of [`Microsoft.Extensions.Hosting.BackgroundService`](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.hosting.backgroundservice?view=dotnet-plat-ext-5.0) (the former indirectly inherits the latter, see above), you get a new method:
 
 ```C#
 public class MyCoolBackgroundService : PowerEventAwareBackgroundService
 {
     // This still runs your long-running background job
-    protected override Task ExecuteAsync(CancellationToken stoppingToken)
+    protected override Task TryExecuteAsync(CancellationToken stoppingToken)
     {
         // Do your continuous or periodic background work.
         await SomeLongRunningTaskAsync();

src/CodeCaster.WindowsServiceExtensions/CodeCaster.WindowsServiceExtensions.csproj

@@ -25,10 +25,10 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.0.0" PrivateAssets="All" />
+    <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.1.1" PrivateAssets="All" />
 
-    <PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" Version="5.0.0" />
-    <PackageReference Include="Microsoft.Extensions.Hosting.WindowsServices" Version="5.0.1" />
+    <PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" Version="6.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Hosting.WindowsServices" Version="6.0.0" />
   </ItemGroup>
 
 </Project>

src/CodeCaster.WindowsServiceExtensions/HostTerminatingBackgroundService.cs

@@ -0,0 +1,52 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+
+namespace CodeCaster.WindowsServiceExtensions
+{
+    /// <summary>
+    /// Terminates the host application when an exception occurs in <see cref="ExecuteAsync"/>.
+    /// </summary>
+    public abstract class HostTerminatingBackgroundService : BackgroundService
+    {
+        private readonly ILogger<HostTerminatingBackgroundService> _logger;
+        private readonly IHostApplicationLifetime _applicationLifetime;
+
+        /// <inheritdoc/>
+        protected HostTerminatingBackgroundService(ILogger<HostTerminatingBackgroundService> logger, IHostApplicationLifetime applicationLifetime)
+        {
+            _logger = logger;
+            _applicationLifetime = applicationLifetime;
+        }
+
+        /// <inheritdoc />
+        protected sealed override async Task ExecuteAsync(CancellationToken stoppingToken)
+        {
+            try
+            {
+                await TryExecuteAsync(stoppingToken);
+            }
+            catch (Exception e)
+            {
+                var errorString = $"Unhandled exception in {GetType().FullName}.ExecuteAsync()";
+
+                _logger.LogError(e, errorString);
+
+                // .NET 6+ terminates the host on exception, 5 doesn't. Do it ourselves.
+                // https://docs.microsoft.com/en-us/dotnet/core/compatibility/core-libraries/6.0/hosting-exception-handling
+                Environment.ExitCode = -1;
+
+                _applicationLifetime.StopApplication();
+
+                throw new InvalidOperationException(errorString, e);
+            }
+        }
+
+        /// <summary>
+        /// Calls <see cref="BackgroundService.ExecuteAsync"/> in a try-catch block, stopping the host application when it throws.
+        /// </summary>
+        protected abstract Task TryExecuteAsync(CancellationToken stoppingToken);
+    }
+}

src/CodeCaster.WindowsServiceExtensions/PowerEventAwareBackgroundService.cs

@@ -1,13 +1,20 @@
 using System.ServiceProcess;
 using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
 
 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
+    public abstract class PowerEventAwareBackgroundService : HostTerminatingBackgroundService, IPowerEventAwareHostedService
     {
+        /// <inheritdoc />
+        protected PowerEventAwareBackgroundService(ILogger<HostTerminatingBackgroundService> logger, IHostApplicationLifetime applicationLifetime)
+            : base(logger, applicationLifetime)
+        {
+        }
+
         /// <summary>
         /// Override this method to react to power state changes.
         /// </summary>

test/TestServiceThatThrows/Program.cs

@@ -68,6 +68,46 @@ protected override async Task ExecuteAsync(CancellationToken stoppingToken)
             throw new InvalidOperationException("This service is not supposed to start");
         }
     }
+    
+    public class MyHostTerminatingBackgroundService : HostTerminatingBackgroundService
+    {
+        private readonly ILogger<MyHostTerminatingBackgroundService> _logger;
+
+        public MyHostTerminatingBackgroundService(ILogger<MyHostTerminatingBackgroundService> logger, IHostApplicationLifetime applicationLifetime)
+            : base(logger, applicationLifetime)
+        {
+            _logger = logger;
+        }
+
+        protected override async Task TryExecuteAsync(CancellationToken stoppingToken)
+        {
+            // Fake doing at least some work...
+            await Task.Delay(1000, stoppingToken);
+
+            // This will now stop the host application.
+            throw new InvalidOperationException("This service is not supposed to start");
+        }
+    }
+
+    public class MyHostTerminatingPowerEventAwareBackgroundService : HostTerminatingBackgroundService
+    {
+        private readonly ILogger<MyHostTerminatingPowerEventAwareBackgroundService> _logger;
+
+        public MyHostTerminatingPowerEventAwareBackgroundService(ILogger<MyHostTerminatingPowerEventAwareBackgroundService> logger, IHostApplicationLifetime applicationLifetime)
+            : base(logger, applicationLifetime)
+        {
+            _logger = logger;
+        }
+
+        protected override async Task TryExecuteAsync(CancellationToken stoppingToken)
+        {
+            // Fake doing at least some work...
+            await Task.Delay(1000, stoppingToken);
+
+            // This will now stop the host application.
+            throw new InvalidOperationException("This service is not supposed to start");
+        }
+    }
 
     public class MyHappyBackgroundService : BackgroundService
     {
@@ -109,7 +149,7 @@ protected override Task ExecuteAsync(CancellationToken stoppingToken)
 
     public static class Program
     {
-        public static async Task Main(string[] args)
+        public static async Task Main()
         {
             if (!Debugger.IsAttached)
             {
@@ -126,9 +166,16 @@ public static async Task Main(string[] args)
                     s.AddHostedService<MyHappyBackgroundService>();
                     s.AddHostedService<QuicklyQuittingBackgroundService>();
 
+                    // This one breaks in OnStart().
                     //s.AddHostedService<MyFaultyService>();
-                    s.AddHostedService<MyFaultyBackgroundService>();
 
+                    // This one throws after 500ms but doesn't take down the host.
+                    //s.AddHostedService<MyFaultyBackgroundService>();
+
+                    // This one should stop the application.
+                    //s.AddHostedService<MyHostTerminatingBackgroundService>();
+                    s.AddHostedService<MyHostTerminatingPowerEventAwareBackgroundService>();
+                    
                     //throw new InvalidOperationException("Heh");
                 })
                 //.UseWindowsService()