WebHostBuilder extensions rename and documentation. #636 #648

samples/SampleStartups/StartupBlockingOnStart.cs

@@ -29,7 +29,7 @@ namespace SampleStartups
         public static void Main(string[] args)
         {
             var host = new WebHostBuilder()
-                .UseDefaultConfiguration(args)
+                .UseDefaultHostingConfiguration(args)
                 .UseStartup<StartupBlockingOnStart>()
                 .Build();
 

samples/SampleStartups/StartupConfigureAddresses.cs

@@ -28,7 +28,7 @@ namespace SampleStartups
         public static void Main(string[] args)
         {
             var host = new WebHostBuilder()
-                .UseDefaultConfiguration(args)
+                .UseDefaultHostingConfiguration(args)
                 .UseStartup<StartupConfigureAddresses>()
                 .UseUrls("http://localhost:5000", "http://localhost:5001")
                 .Build();

samples/SampleStartups/StartupHelloWorld.cs

@@ -28,7 +28,7 @@ namespace SampleStartups
         public static void Main(string[] args)
         {
             var host = new WebHostBuilder()
-                .UseDefaultConfiguration(args)
+                .UseDefaultHostingConfiguration(args)
                 .UseStartup<StartupHelloWorld>()
                 .Build();
 

src/Microsoft.AspNetCore.Hosting/Internal/WebHostConfiguration.cs

@@ -15,15 +15,9 @@ namespace Microsoft.AspNetCore.Hosting.Internal
 
         public static IConfiguration GetDefault(string[] args)
         {
-            var defaultSettings = new Dictionary<string, string>
-            {
-                { WebHostDefaults.CaptureStartupErrorsKey, "true" }
-            };
-
             // Setup the default locations for finding hosting configuration options
             // hosting.json, ASPNETCORE_ prefixed env variables and command line arguments
             var configBuilder = new ConfigurationBuilder()
-                .AddInMemoryCollection(defaultSettings)
                 .AddJsonFile(WebHostDefaults.HostingJsonFile, optional: true)
                 .AddEnvironmentVariables(prefix: WebHostDefaults.EnvironmentVariablesPrefix);
 

src/Microsoft.AspNetCore.Hosting/WebHostBuilderExtensions.cs

@@ -12,96 +12,72 @@ namespace Microsoft.AspNetCore.Hosting
     {
         private static readonly string ServerUrlsSeparator = ";";
 
-        public static IWebHostBuilder UseDefaultConfiguration(this IWebHostBuilder builder)
+        /// <summary>
+        /// Use the default hosting configuration settings on the web host.
+        /// </summary>
+        /// <param name="hostBuilder">The <see cref="IWebHostBuilder"/> to configure.</param>
+        /// <returns>The <see cref="IWebHostBuilder"/>.</returns>
+        public static IWebHostBuilder UseDefaultHostingConfiguration(this IWebHostBuilder hostBuilder)
         {
-            return builder.UseDefaultConfiguration(args: null);
+            return hostBuilder.UseDefaultHostingConfiguration(args: null);
         }
 
-        public static IWebHostBuilder UseDefaultConfiguration(this IWebHostBuilder builder, string[] args)
+        /// <summary>
+        /// Use the default hosting configuration settings on the web host and allow for override by command line arguments.
+        /// </summary>
+        /// <param name="hostBuilder">The <see cref="IWebHostBuilder"/> to configure.</param>
+        /// <param name="args">The command line arguments used to override default settings.</param>
+        /// <returns>The <see cref="IWebHostBuilder"/>.</returns>
+        public static IWebHostBuilder UseDefaultHostingConfiguration(this IWebHostBuilder hostBuilder, string[] args)
         {
-            return builder.UseConfiguration(WebHostConfiguration.GetDefault(args));
+            return hostBuilder.UseConfiguration(WebHostConfiguration.GetDefault(args));
         }
 
-        public static IWebHostBuilder UseConfiguration(this IWebHostBuilder builder, IConfiguration configuration)
+        /// <summary>
+        /// Use the given configuration settings on the web host.
+        /// </summary>
+        /// <param name="hostBuilder">The <see cref="IWebHostBuilder"/> to configure.</param>
+        /// <param name="configuration">The <see cref="IConfiguration"/> containing settings to be used.</param>
+        /// <returns>The <see cref="IWebHostBuilder"/>.</returns>
+        public static IWebHostBuilder UseConfiguration(this IWebHostBuilder hostBuilder, IConfiguration configuration)
         {
             foreach (var setting in configuration.AsEnumerable())
             {
-                builder.UseSetting(setting.Key, setting.Value);
+                hostBuilder.UseSetting(setting.Key, setting.Value);
             }
 
-            return builder;
+            return hostBuilder;
         }
 
-        public static IWebHostBuilder UseCaptureStartupErrors(this IWebHostBuilder hostBuilder, bool captureStartupError)
+        /// <summary>
+        /// Set whether startup errors should be captured in the configuration settings of the web host.
+        /// When enabled, startup exceptions will be caught and an error page will be returned. If disabled, startup exceptions will be propagated.
+        /// </summary>
+        /// <param name="hostBuilder">The <see cref="IWebHostBuilder"/> to configure.</param>
+        /// <param name="captureStartupErrors"><c>true</c> to use startup error page; otherwise <c>false</c>.</param>
+        /// <returns>The <see cref="IWebHostBuilder"/>.</returns>
+        public static IWebHostBuilder CaptureStartupErrors(this IWebHostBuilder hostBuilder, bool captureStartupErrors)
         {
-            return hostBuilder.UseSetting(WebHostDefaults.CaptureStartupErrorsKey, captureStartupError ? "true" : "false");
+            return hostBuilder.UseSetting(WebHostDefaults.CaptureStartupErrorsKey, captureStartupErrors ? "true" : "false");
         }
 
+        /// <summary>
+        /// Specify the startup type to be used by the web host.
+        /// </summary>
+        /// <param name="hostBuilder">The <see cref="IWebHostBuilder"/> to configure.</param>
+        /// <typeparam name ="TStartup">The type containing the startup methods for the application.</typeparam>
+        /// <returns>The <see cref="IWebHostBuilder"/>.</returns>
         public static IWebHostBuilder UseStartup<TStartup>(this IWebHostBuilder hostBuilder) where TStartup : class
         {
             return hostBuilder.UseStartup(typeof(TStartup));
         }
 
-        public static IWebHostBuilder UseServer(this IWebHostBuilder hostBuilder, string assemblyName)
+        /// <summary>
-        {
+        /// Specify the assembly containing the startup type to be used by the web host.
-            if (assemblyName == null)
+        /// </summary>
-            {
+        /// <param name="hostBuilder">The <see cref="IWebHostBuilder"/> to configure.</param>
-                throw new ArgumentNullException(nameof(assemblyName));
+        /// <param name="startupAssemblyName">The name of the assembly containing the startup type.</param>
-            }
+        /// <returns>The <see cref="IWebHostBuilder"/>.</returns>
-
-            return hostBuilder.UseSetting(WebHostDefaults.ServerKey, assemblyName);
-        }
-
-        public static IWebHostBuilder UseServer(this IWebHostBuilder hostBuilder, IServer server)
-        {
-            if (server == null)
-            {
-                throw new ArgumentNullException(nameof(server));
-            }
-
-            return hostBuilder.UseServer(new ServerFactory(server));
-        }
-
-        public static IWebHostBuilder UseContentRoot(this IWebHostBuilder hostBuilder, string contentRootPath)
-        {
-            if (contentRootPath == null)
-            {
-                throw new ArgumentNullException(nameof(contentRootPath));
-            }
-
-            return hostBuilder.UseSetting(WebHostDefaults.ContentRootKey, contentRootPath);
-        }
-
-        public static IWebHostBuilder UseEnvironment(this IWebHostBuilder hostBuilder, string environment)
-        {
-            if (environment == null)
-            {
-                throw new ArgumentNullException(nameof(environment));
-            }
-
-            return hostBuilder.UseSetting(WebHostDefaults.EnvironmentKey, environment);
-        }
-
-        public static IWebHostBuilder UseWebRoot(this IWebHostBuilder hostBuilder, string webRoot)
-        {
-            if (webRoot == null)
-            {
-                throw new ArgumentNullException(nameof(webRoot));
-            }
-
-            return hostBuilder.UseSetting(WebHostDefaults.WebRootKey, webRoot);
-        }
-
-        public static IWebHostBuilder UseUrls(this IWebHostBuilder hostBuilder, params string[] urls)
-        {
-            if (urls == null)
-            {
-                throw new ArgumentNullException(nameof(urls));
-            }
-
-            return hostBuilder.UseSetting(WebHostDefaults.ServerUrlsKey, string.Join(ServerUrlsSeparator, urls));
-        }
-
         public static IWebHostBuilder UseStartup(this IWebHostBuilder hostBuilder, string startupAssemblyName)
         {
             if (startupAssemblyName == null)
@@ -112,6 +88,108 @@ namespace Microsoft.AspNetCore.Hosting
             return hostBuilder.UseSetting(WebHostDefaults.ApplicationKey, startupAssemblyName);
         }
 
+        /// <summary>
+        /// Specify the assembly containing the server to be used by the web host.
+        /// </summary>
+        /// <param name="hostBuilder">The <see cref="IWebHostBuilder"/> to configure.</param>
+        /// <param name="assemblyName">The name of the assembly containing the server to be used.</param>
+        /// <returns>The <see cref="IWebHostBuilder"/>.</returns>
+        public static IWebHostBuilder UseServer(this IWebHostBuilder hostBuilder, string assemblyName)
+        {
+            if (assemblyName == null)
+            {
+                throw new ArgumentNullException(nameof(assemblyName));
+            }
+
+            return hostBuilder.UseSetting(WebHostDefaults.ServerKey, assemblyName);
+        }
+
+        /// <summary>
+        /// Specify the server to be used by the web host.
+        /// </summary>
+        /// <param name="hostBuilder">The <see cref="IWebHostBuilder"/> to configure.</param>
+        /// <param name="server">The <see cref="IServer"/> to be used.</param>
+        /// <returns>The <see cref="IWebHostBuilder"/>.</returns>
+        public static IWebHostBuilder UseServer(this IWebHostBuilder hostBuilder, IServer server)
+        {
+            if (server == null)
+            {
+                throw new ArgumentNullException(nameof(server));
+            }
+
+            return hostBuilder.UseServer(new ServerFactory(server));
+        }
+
+        /// <summary>
+        /// Specify the environment to be used by the web host.
+        /// </summary>
+        /// <param name="hostBuilder">The <see cref="IWebHostBuilder"/> to configure.</param>
+        /// <param name="environment">The environment to host the application in.</param>
+        /// <returns>The <see cref="IWebHostBuilder"/>.</returns>
+        public static IWebHostBuilder UseEnvironment(this IWebHostBuilder hostBuilder, string environment)
+        {
+            if (environment == null)
+            {
+                throw new ArgumentNullException(nameof(environment));
+            }
+
+            return hostBuilder.UseSetting(WebHostDefaults.EnvironmentKey, environment);
+        }
+
+        /// <summary>
+        /// Specify the content root directory to be used by the web host.
+        /// </summary>
+        /// <param name="hostBuilder">The <see cref="IWebHostBuilder"/> to configure.</param>
+        /// <param name="contentRoot">Path to root directory of the application.</param>
+        /// <returns>The <see cref="IWebHostBuilder"/>.</returns>
+        public static IWebHostBuilder UseContentRoot(this IWebHostBuilder hostBuilder, string contentRoot)
+        {
+            if (contentRoot == null)
+            {
+                throw new ArgumentNullException(nameof(contentRoot));
+            }
+
+            return hostBuilder.UseSetting(WebHostDefaults.ContentRootKey, contentRoot);
+        }
+
+        /// <summary>
+        /// Specify the webroot directory to be used by the web host.
+        /// </summary>
+        /// <param name="hostBuilder">The <see cref="IWebHostBuilder"/> to configure.</param>
+        /// <param name="webRoot">Path to the root directory used by the web server.</param>
+        /// <returns>The <see cref="IWebHostBuilder"/>.</returns>
+        public static IWebHostBuilder UseWebRoot(this IWebHostBuilder hostBuilder, string webRoot)
+        {
+            if (webRoot == null)
+            {
+                throw new ArgumentNullException(nameof(webRoot));
+            }
+
+            return hostBuilder.UseSetting(WebHostDefaults.WebRootKey, webRoot);
+        }
+
+        /// <summary>
+        /// Specify the urls the web host will listen on.
+        /// </summary>
+        /// <param name="hostBuilder">The <see cref="IWebHostBuilder"/> to configure.</param>
+        /// <param name="urls">The urls the hosted application will listen on.</param>
+        /// <returns>The <see cref="IWebHostBuilder"/>.</returns>
+        public static IWebHostBuilder UseUrls(this IWebHostBuilder hostBuilder, params string[] urls)
+        {
+            if (urls == null)
+            {
+                throw new ArgumentNullException(nameof(urls));
+            }
+
+            return hostBuilder.UseSetting(WebHostDefaults.ServerUrlsKey, string.Join(ServerUrlsSeparator, urls));
+        }
+
+        /// <summary>
+        /// Start the web host and listen on the speficied urls.
+        /// </summary>
+        /// <param name="hostBuilder">The <see cref="IWebHostBuilder"/> to start.</param>
+        /// <param name="urls">The urls the hosted application will listen on.</param>
+        /// <returns>The <see cref="IWebHostBuilder"/>.</returns>
         public static IWebHost Start(this IWebHostBuilder hostBuilder, params string[] urls)
         {
             var host = hostBuilder.UseUrls(urls).Build();

src/Microsoft.AspNetCore.Hosting/WebHostExtensions.cs

@@ -13,7 +13,7 @@ namespace Microsoft.AspNetCore.Hosting
         /// <summary>
         /// Runs a web application and block the calling thread until host shutdown.
         /// </summary>
-        /// <param name="host"></param>
+        /// <param name="host">The <see cref="IWebHost"/> to run.</param>
         public static void Run(this IWebHost host)
         {
             using (var cts = new CancellationTokenSource())
@@ -33,7 +33,7 @@ namespace Microsoft.AspNetCore.Hosting
         /// <summary>
         /// Runs a web application and block the calling thread until token is triggered or shutdown is triggered.
         /// </summary>
-        /// <param name="host"></param>
+        /// <param name="host">The <see cref="IWebHost"/> to run.</param>
         /// <param name="token">The token to trigger shutdown.</param>
         public static void Run(this IWebHost host, CancellationToken token)
         {

src/Microsoft.AspNetCore.TestHost/TestServer.cs

@@ -22,11 +22,6 @@ namespace Microsoft.AspNetCore.TestHost
 
         public TestServer(IWebHostBuilder builder)
         {
-            if (string.IsNullOrEmpty(builder.GetSetting(WebHostDefaults.CaptureStartupErrorsKey)))
-            {
-                builder.UseCaptureStartupErrors(false);
-            }
-
             var host = builder.UseServer(this).Build();
             host.Start();
             _hostInstance = host;

test/Microsoft.AspNetCore.Hosting.Tests/WebHostBuilderTests.cs

@@ -125,22 +125,22 @@ namespace Microsoft.AspNetCore.Hosting
         }
 
         [Fact]
-        public void DefaultConfigurationCapturesStartupErrors()
+        public void DefaultHostingConfigurationDoesNotCaptureStartupErrors()
         {
             var hostBuilder = new WebHostBuilder()
-                .UseDefaultConfiguration()
+                .UseDefaultHostingConfiguration()
                 .UseServer(new TestServer())
                 .UseStartup<StartupBoom>();
 
-            // This should not throw
+            var exception = Assert.Throws<InvalidOperationException>(() => hostBuilder.Build());
-            hostBuilder.Build();
+            Assert.Equal("A public method named 'ConfigureProduction' or 'Configure' could not be found in the 'Microsoft.AspNetCore.Hosting.Fakes.StartupBoom' type.", exception.Message);
         }
 
         [Fact]
-        public void UseCaptureStartupErrorsHonored()
+        public void CaptureStartupErrorsHonored()
         {
             var hostBuilder = new WebHostBuilder()
-                .UseCaptureStartupErrors(false)
+                .CaptureStartupErrors(false)
                 .UseServer(new TestServer())
                 .UseStartup<StartupBoom>();
 

test/Microsoft.AspNetCore.Hosting.Tests/WebHostConfigurationsTests.cs

@@ -11,11 +11,11 @@ namespace Microsoft.AspNetCore.Hosting.Tests
     public class WebHostConfigurationTests
     {
         [Fact]
-        public void DefaultCapturesStartupErrors()
+        public void DefaultDoesNotCaptureStartupErrors()
         {
             var config = new WebHostOptions(WebHostConfiguration.GetDefault());
 
-            Assert.True(config.CaptureStartupErrors);
+            Assert.False(config.CaptureStartupErrors);
         }
 
         [Fact]

test/Microsoft.AspNetCore.TestHost.Tests/TestServerTests.cs

@@ -48,7 +48,7 @@ namespace Microsoft.AspNetCore.TestHost
         public void CaptureStartupErrorsSettingPreserved()
         {
             var builder = new WebHostBuilder()
-                .UseCaptureStartupErrors(true)
+                .CaptureStartupErrors(true)
                 .Configure(app =>
                 {
                     throw new InvalidOperationException();