[API Implementation]: Expose StopTheHostException (#69404)

* Implement `HostAbortedException` proposal

* Apply suggestions

* Add solution file

Co-authored-by: Eric Erhardt <[email protected]>

Author: deeprobin

src/libraries/Microsoft.Extensions.HostFactoryResolver/Microsoft.Extensions.HostFactoryResolver.sln

@@ -0,0 +1,25 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.2.32516.85
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.Extensions.HostFactoryResolver.Sources", "src\Microsoft.Extensions.HostFactoryResolver.Sources.csproj", "{317C456F-8F26-4441-93F7-9042B0DC7119}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Release|Any CPU = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{317C456F-8F26-4441-93F7-9042B0DC7119}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{317C456F-8F26-4441-93F7-9042B0DC7119}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{317C456F-8F26-4441-93F7-9042B0DC7119}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{317C456F-8F26-4441-93F7-9042B0DC7119}.Release|Any CPU.Build.0 = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(ExtensibilityGlobals) = postSolution
+		SolutionGuid = {80C3C947-5A43-4A55-9E1C-D62738588863}
+	EndGlobalSection
+EndGlobal

src/libraries/Microsoft.Extensions.HostFactoryResolver/src/HostFactoryResolver.cs

@@ -247,7 +247,7 @@ public object CreateHost()
                         // build to throw
                         _hostTcs.TrySetException(new InvalidOperationException("The entry point exited without ever building an IHost."));
                     }
-                    catch (TargetInvocationException tie) when (tie.InnerException is StopTheHostException)
+                    catch (TargetInvocationException tie) when (tie.InnerException is HostAbortedException)
                     {
                         // The host was stopped by our own logic
                     }
@@ -341,15 +341,10 @@ public void OnNext(KeyValuePair<string, object?> value)
                     if (_stopApplication)
                     {
                         // Stop the host from running further
-                        throw new StopTheHostException();
+                        throw new HostAbortedException();
                     }
                 }
             }
-
-            private sealed class StopTheHostException : Exception
-            {
-
-            }
         }
     }
 }

src/libraries/Microsoft.Extensions.Hosting/ref/Microsoft.Extensions.Hosting.cs

@@ -30,6 +30,12 @@ public static partial class Host
         public static Microsoft.Extensions.Hosting.IHostBuilder CreateDefaultBuilder() { throw null; }
         public static Microsoft.Extensions.Hosting.IHostBuilder CreateDefaultBuilder(string[]? args) { throw null; }
     }
+    public sealed partial class HostAbortedException : System.Exception
+    {
+        public HostAbortedException() { }
+        public HostAbortedException(string? message) { }
+        public HostAbortedException(string? message, System.Exception? innerException) { }
+    }
     public sealed partial class HostApplicationBuilder
     {
         public HostApplicationBuilder() { }

src/libraries/Microsoft.Extensions.Hosting/src/HostAbortedException.cs

@@ -0,0 +1,54 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+using System;
+using System.Runtime.Serialization;
+
+namespace Microsoft.Extensions.Hosting
+{
+    /// <summary>
+    /// The exception that is thrown upon <see cref="IHost"/> abortion.
+    /// </summary>
+    [Serializable]
+    public sealed class HostAbortedException : Exception
+    {
+        private HostAbortedException(SerializationInfo info, StreamingContext context) : base(info, context) { }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="HostAbortedException"/> class
+        /// with a system-supplied error message.
+        /// </summary>
+        public HostAbortedException() : base(SR.HostAbortedExceptionMessage) { }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="HostAbortedException"/> class
+        /// with a specified error message.
+        /// </summary>
+        /// <param name="message">
+        /// The error message that explains the reason for the exception.
+        /// </param>
+        /// <remarks>
+        /// The content of <paramref name="message"/> is intended to be understood by humans.
+        /// The caller of this constructor is required to ensure that this string has been localized for the
+        /// current system culture.
+        /// </remarks>
+        public HostAbortedException(string? message) : base(message) { }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="HostAbortedException"/> class
+        /// with a specified error message and a reference to the inner exception that
+        /// is the cause of this exception.
+        /// </summary>
+        /// <param name="message">
+        /// The error message that explains the reason for the exception.
+        /// </param>
+        /// <param name="innerException">
+        /// The exception that is the cause of the current exception.
+        /// </param>
+        /// <remarks>
+        /// The content of <paramref name="message"/> is intended to be understood by humans.
+        /// The caller of this constructor is required to ensure that this string has been localized for the
+        /// current system culture.
+        /// </remarks>
+        public HostAbortedException(string? message, Exception? innerException) : base(message, innerException) { }
+    }
+}

src/libraries/Microsoft.Extensions.Hosting/src/Resources/Strings.resx

@@ -135,6 +135,9 @@
   <data name="EnvironmentNameChangeNotSupoprted" xml:space="preserve">
     <value>The environment name changed from "{0}" to "{1}". Changing host configuration is not supported.</value>
   </data>
+  <data name="HostAbortedExceptionMessage" xml:space="preserve">
+    <value>The host was aborted.</value>
+  </data>
   <data name="IHostApplicationLifetimeReplacementNotSupported" xml:space="preserve">
     <value>Replacing IHostApplicationLifetime is not supported.</value>
   </data>

src/libraries/Microsoft.Extensions.Hosting/tests/UnitTests/HostAbortedExceptionTests.cs

@@ -0,0 +1,73 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.IO;
+using System.Runtime.Serialization.Formatters.Binary;
+using Xunit;
+
+namespace Microsoft.Extensions.Hosting.Unit.Tests
+{
+    public sealed class HostAbortedExceptionTests
+    {
+        [Fact]
+        public void TestEmptyException()
+        {
+            var exception = new HostAbortedException();
+            Assert.Null(exception.InnerException);
+            Assert.Throws<HostAbortedException>(new Action(() => throw exception));
+        }
+
+        [Theory]
+        [InlineData("The host was aborted.", false)]
+        [InlineData("The host was aborted.", true)]
+        public void TestException(string? message, bool innerException)
+        {
+            HostAbortedException exception = innerException
+                ? new HostAbortedException(message, new Exception())
+                : new HostAbortedException(message);
+
+            Assert.Equal(message, exception.Message);
+            if (innerException)
+            {
+                Assert.NotNull(exception.InnerException);
+            } 
+            
+            HostAbortedException thrownException = Assert.Throws<HostAbortedException>(new Action(() => throw exception));
+            Assert.Equal(message, thrownException.Message);
+        }
+
+        [Theory]
+        [InlineData("Test Message")]
+        [InlineData(null)]
+        public void TestSerialization(string? message)
+        {
+            var exception = new HostAbortedException(message);
+            using var serializationStream = new MemoryStream();
+
+            var formatter = new BinaryFormatter();
+            formatter.Serialize(serializationStream, exception);
+
+            using var deserializationStream = new MemoryStream(serializationStream.ToArray());
+            HostAbortedException deserializedException = (HostAbortedException) formatter.Deserialize(deserializationStream);
+
+            Assert.Equal(exception.Message, deserializedException.Message);
+            Assert.Null(deserializedException.InnerException);
+        }
+
+        [Fact]
+        public void TestSerializationDefaultConstructor() {
+            var exception = new HostAbortedException();
+            using var serializationStream = new MemoryStream();
+
+            var formatter = new BinaryFormatter();
+            formatter.Serialize(serializationStream, exception);
+
+            using var deserializationStream = new MemoryStream(serializationStream.ToArray());
+            HostAbortedException deserializedException = (HostAbortedException)formatter.Deserialize(deserializationStream);
+
+            Assert.Equal(exception.Message, deserializedException.Message);
+            Assert.Null(deserializedException.InnerException);            
+        }
+    }
+}