Handle service error by setting positive error code and stopping the service

Author: CodeCasterNL

Docs.projitems

@@ -12,7 +12,6 @@
     <Content Include="$(MSBuildThisFileDirectory)docs\downloads.md" />
     <Content Include="$(MSBuildThisFileDirectory)docs\upgrading-v2-v3.md" />
     <Content Include="$(MSBuildThisFileDirectory)docs\_layouts\cayman-with-menu.html" />
-    <Content Include="$(MSBuildThisFileDirectory)docs\demo.md" />
     <Content Include="$(MSBuildThisFileDirectory)docs\_config.yml" />
     <Content Include="$(MSBuildThisFileDirectory)docs\index.md" />
   </ItemGroup>

Readme.md

@@ -1,9 +1,17 @@
-# WindowsServiceExtensions
-This project exists of a few classes that make building reliable Windows Services easier. 
+# 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`. 
 
-Make a .NET Core Windows Service that runs as `IHostedService` aware of the computer shutting down and starting up. 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.
+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.
 
-The Lifetime classes also include [kmcclellan's fixes](https://github.com/dotnet/runtime/issues/50019#issuecomment-678658133) that make the service throw when something fails on .NET Host startup, instead of reprorting it started successfully, and code to react to user session changes.
+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.
+* This library makes an `IHostedService` running inside a .NET Windows Service that aware of the user logging in and out, and the computer shutting down and starting up.
+* 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/):
@@ -27,9 +35,13 @@ Extended upgrading docs: see https://codecasternl.github.io/WindowsServiceExtens
 ## Usage
 These methods from this package allow your `IHostedService`s to 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()`](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.hosting.windowsservicelifetimehostbuilderextensions.usewindowsservice?view=dotnet-plat-ext-3.1).
-* Instead of letting your service inherit [`Microsoft.Extensions.Hosting.BackgroundService`](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.hosting.backgroundservice?view=dotnet-plat-ext-5.0), inherit from `CodeCaster.WindowsServiceExtensions.WindowsServiceBackgroundService`.
+* On your Host Builder, call `UseWindowsServiceExtensions()` instead of `UseWindowsService()`.
+* Instead of letting your service inherit `BackgroundService`, inherit from `CodeCaster.WindowsServiceExtensions.WindowsServiceBackgroundService`.
 * 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.
+
+# Contributing
+Please file an issue or PR. Even if you use this and are happy with it.
+

docs/demo.md

@@ -31,6 +31,10 @@ public ExtendedWindowsServiceLifetime(IServiceProvider serviceProvider, IHostEnv
                 throw new PlatformNotSupportedException($"Windows Service needs to run on Windows. Remove the call to {methodName}()");
             }
 
+            // Explicitly stop the service instead of just exiting the process.
+            // But this this will kill the application quickly, do other BackgroundServices get the time to exit nicely?
+            applicationLifetime.ApplicationStopping.Register(Stop);
+
             CanHandlePowerEvent = true;
             CanHandleSessionChangeEvent = true;
         }

src/CodeCaster.WindowsServiceExtensions/Lifetime/ExtendedWindowsServiceLifetime.cs

@@ -51,6 +51,7 @@ public HostApplicationStartupLifetime(IServiceProvider serviceProvider, IHostEnv
         public new async Task WaitForStartAsync(CancellationToken cancellationToken)
         {
             Logger.LogInformation("Windows Service start requested");
+
             ApplicationLifetime.ApplicationStarted.Register(() => _started.Set());
 
             try
@@ -91,11 +92,11 @@ protected override void OnStart(string[] args)
             _started.Wait(ApplicationLifetime.ApplicationStopping);
 
             // This can happen very early in the startup process (even before ApplicationStopping is cancelled), so this may not be logged nor reported at all,
-            // because the DI isn't complete and the logger (file, event log, ...) not available while we're being disposed.
+            // because the DI isn't complete and the logger (file, event log, ...) not available while we're being disposed. Probably corrupt config file?
             if (!ApplicationLifetime.ApplicationStarted.IsCancellationRequested)
             {
                 const string errorString = "Windows Service failed to start: some part reported it started, the other didn't";
-                
+
                 Logger.LogError(errorString);
 
                 // Prevent the service from happily reporting successful startup, while the .NET Core ApplicationHost isn't started at all.

src/CodeCaster.WindowsServiceExtensions/Lifetime/HostApplicationStartupLifetime.cs

@@ -14,6 +14,11 @@ namespace CodeCaster.WindowsServiceExtensions.Service
     /// </summary>
     public abstract class WindowsServiceBackgroundService : BackgroundService, IWindowsServiceAwareHostedService
     {
+        /// <summary>
+        /// Used for error reporting.
+        /// </summary>
+        private const int ErrorInvalidData = 13;
+
         /// <summary>
         /// Logs.
         /// </summary>
@@ -58,39 +63,32 @@ public virtual void OnSessionChange(SessionChangeDescription changeDescription)
         /// <summary>
         /// Overridden and sealed from <see cref="BackgroundService.ExecuteAsync "/> to set the exit code on exception.
         /// </summary>
-        protected sealed override Task ExecuteAsync(CancellationToken stoppingToken)
+        protected sealed override async Task ExecuteAsync(CancellationToken stoppingToken)
         {
             try
             {
-                Logger.LogDebug("{serviceType}.{execute}() called, calling {tryExecute}()", GetType().FullName, nameof(ExecuteAsync), nameof(TryExecuteAsync));
+                Logger.LogInformation("{serviceType}.{execute}() called, calling {tryExecute}()", GetType().FullName, nameof(ExecuteAsync), nameof(TryExecuteAsync));
 
-                return TryExecuteAsync(stoppingToken);
+                await TryExecuteAsync(stoppingToken);
             }
             catch (Exception)
             {
-                // The host will shut down with code 0 if we don't do this.
-                const int exitCode = -1;
+                Logger.LogDebug("Setting process exit code to {exitCode}", ErrorInvalidData);
 
-                Logger.LogInformation("Setting process exit code to {exitCode}", exitCode);
-
-                // Doesn't work, overwritten by ConsoleLifetime?
-                Environment.ExitCode = exitCode;
+                // The host will shut down with code 0 if we don't do this.
+                Environment.ExitCode = ErrorInvalidData;
 
 #pragma warning disable CA1416 // Validate platform compatibility - we are a Windows Service.
                 if (ServiceLifetime != null)
                 {
-                    Logger.LogWarning("Setting service exit code to {exitCode}", exitCode);
+                    Logger.LogDebug("Setting service exit code to {exitCode}", ErrorInvalidData);
 
-                    ServiceLifetime.ExitCode = exitCode;
-
-                    // This will probably yank the .NET Host from under us, not executing any more (or just a little) code.
-                    ServiceLifetime.Stop();
+                    // To report to the Service Control Manager on failure, is uint so > 0.
+                    ServiceLifetime.ExitCode = ErrorInvalidData;
                 }
 #pragma warning restore CA1416 // Validate platform compatibility
 
-                ApplicationLifetime.StopApplication();
-
-                // Let the WindowsServiceLifetime handle the exception.
+                // Let the BackgroundService handle the exception.
                 throw;
             }
         }

src/CodeCaster.WindowsServiceExtensions/Service/WindowsServiceBackgroundService.cs

@@ -14,9 +14,10 @@ public static class Program
     {
         public static async Task Main()
         {
+            // Hint: Reattach to Process (Shift+Alt+P)
             if (!Debugger.IsAttached)
             {
-                Console.WriteLine("Waiting 5s for debugger to be attached...");
+                Console.WriteLine("Waiting 5s for debugger to be attached and pretending the service starts up slowly...");
                 Thread.Sleep(5000);
                 Debugger.Break();
             }
@@ -28,9 +29,9 @@ public static async Task Main()
                     // Services to run are defined below.
 
                     // These three run successfully.
-                    s.AddHostedService<MyHappyService>();
-                    s.AddHostedService<MyHappyBackgroundService>();
-                    s.AddHostedService<QuicklyQuittingBackgroundService>();
+                    //s.AddHostedService<MyHappyService>();
+                    //s.AddHostedService<MyHappyBackgroundService>();
+                    //s.AddHostedService<QuicklyQuittingBackgroundService>();
 
                     // This one breaks in OnStart() (should give startup error).
                     //s.AddHostedService<MyFaultyService>();
@@ -44,11 +45,12 @@ public static async Task Main()
                     // Should give startup error.
                     //throw new InvalidOperationException("Heh");
                 })
-                //.UseWindowsService()
-                .UseWindowsServiceExtensions(o =>
-                {
-                    //o.ServiceName = ...
-                })
+                .UseWindowsService()
+                .UseWindowsServiceExtensions()
+                //.UseWindowsServiceExtensions(o => 
+                //{
+                //    //o.ServiceName = ...
+                //})
                 .Build()
                 .RunAsync();
         }

test/TestServiceThatThrows/Program.cs

@@ -8,7 +8,7 @@
     "EventLog": {
       "LogLevel": {
         "Default": "Warning",
-        "Microsoft.Hosting.Lifetime": "Warning"
+        "Microsoft.Hosting.Lifetime": "Information"
       }
     }
   }