From 312192b4479a7000ff37df4101fc7eb85e3204bd Mon Sep 17 00:00:00 2001 From: John Luo Date: Fri, 18 Mar 2016 12:21:23 -0700 Subject: [PATCH] WebHostBuilder extensions rename and documentation. #636 #648 --- .../SampleStartups/StartupBlockingOnStart.cs | 2 +- .../StartupConfigureAddresses.cs | 2 +- samples/SampleStartups/StartupHelloWorld.cs | 2 +- .../Internal/WebHostConfiguration.cs | 6 - .../WebHostBuilderExtensions.cs | 218 ++++++++++++------ .../WebHostExtensions.cs | 4 +- .../TestServer.cs | 5 - .../WebHostBuilderTests.cs | 12 +- .../WebHostConfigurationsTests.cs | 4 +- .../TestServerTests.cs | 2 +- 10 files changed, 162 insertions(+), 95 deletions(-) diff --git a/samples/SampleStartups/StartupBlockingOnStart.cs b/samples/SampleStartups/StartupBlockingOnStart.cs index 2f7b3bc6ee..3416207e01 100644 --- a/samples/SampleStartups/StartupBlockingOnStart.cs +++ b/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() .Build(); diff --git a/samples/SampleStartups/StartupConfigureAddresses.cs b/samples/SampleStartups/StartupConfigureAddresses.cs index 418e611691..cc3ee5c67f 100644 --- a/samples/SampleStartups/StartupConfigureAddresses.cs +++ b/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() .UseUrls("http://localhost:5000", "http://localhost:5001") .Build(); diff --git a/samples/SampleStartups/StartupHelloWorld.cs b/samples/SampleStartups/StartupHelloWorld.cs index 0c9d56632b..69970f2722 100644 --- a/samples/SampleStartups/StartupHelloWorld.cs +++ b/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() .Build(); diff --git a/src/Microsoft.AspNetCore.Hosting/Internal/WebHostConfiguration.cs b/src/Microsoft.AspNetCore.Hosting/Internal/WebHostConfiguration.cs index fff5d669e5..72f400f3ea 100644 --- a/src/Microsoft.AspNetCore.Hosting/Internal/WebHostConfiguration.cs +++ b/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 - { - { 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); diff --git a/src/Microsoft.AspNetCore.Hosting/WebHostBuilderExtensions.cs b/src/Microsoft.AspNetCore.Hosting/WebHostBuilderExtensions.cs index bb9c66b774..20e97ff7e3 100644 --- a/src/Microsoft.AspNetCore.Hosting/WebHostBuilderExtensions.cs +++ b/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) + /// + /// Use the default hosting configuration settings on the web host. + /// + /// The to configure. + /// The . + 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) + /// + /// Use the default hosting configuration settings on the web host and allow for override by command line arguments. + /// + /// The to configure. + /// The command line arguments used to override default settings. + /// The . + 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) + /// + /// Use the given configuration settings on the web host. + /// + /// The to configure. + /// The containing settings to be used. + /// The . + 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) + /// + /// 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. + /// + /// The to configure. + /// true to use startup error page; otherwise false. + /// The . + 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"); } + /// + /// Specify the startup type to be used by the web host. + /// + /// The to configure. + /// The type containing the startup methods for the application. + /// The . public static IWebHostBuilder UseStartup(this IWebHostBuilder hostBuilder) where TStartup : class { return hostBuilder.UseStartup(typeof(TStartup)); } - public static IWebHostBuilder UseServer(this IWebHostBuilder hostBuilder, string assemblyName) - { - if (assemblyName == null) - { - throw new ArgumentNullException(nameof(assemblyName)); - } - - 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)); - } - + /// + /// Specify the assembly containing the startup type to be used by the web host. + /// + /// The to configure. + /// The name of the assembly containing the startup type. + /// The . 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); } + /// + /// Specify the assembly containing the server to be used by the web host. + /// + /// The to configure. + /// The name of the assembly containing the server to be used. + /// The . + public static IWebHostBuilder UseServer(this IWebHostBuilder hostBuilder, string assemblyName) + { + if (assemblyName == null) + { + throw new ArgumentNullException(nameof(assemblyName)); + } + + return hostBuilder.UseSetting(WebHostDefaults.ServerKey, assemblyName); + } + + /// + /// Specify the server to be used by the web host. + /// + /// The to configure. + /// The to be used. + /// The . + public static IWebHostBuilder UseServer(this IWebHostBuilder hostBuilder, IServer server) + { + if (server == null) + { + throw new ArgumentNullException(nameof(server)); + } + + return hostBuilder.UseServer(new ServerFactory(server)); + } + + /// + /// Specify the environment to be used by the web host. + /// + /// The to configure. + /// The environment to host the application in. + /// The . + public static IWebHostBuilder UseEnvironment(this IWebHostBuilder hostBuilder, string environment) + { + if (environment == null) + { + throw new ArgumentNullException(nameof(environment)); + } + + return hostBuilder.UseSetting(WebHostDefaults.EnvironmentKey, environment); + } + + /// + /// Specify the content root directory to be used by the web host. + /// + /// The to configure. + /// Path to root directory of the application. + /// The . + public static IWebHostBuilder UseContentRoot(this IWebHostBuilder hostBuilder, string contentRoot) + { + if (contentRoot == null) + { + throw new ArgumentNullException(nameof(contentRoot)); + } + + return hostBuilder.UseSetting(WebHostDefaults.ContentRootKey, contentRoot); + } + + /// + /// Specify the webroot directory to be used by the web host. + /// + /// The to configure. + /// Path to the root directory used by the web server. + /// The . + public static IWebHostBuilder UseWebRoot(this IWebHostBuilder hostBuilder, string webRoot) + { + if (webRoot == null) + { + throw new ArgumentNullException(nameof(webRoot)); + } + + return hostBuilder.UseSetting(WebHostDefaults.WebRootKey, webRoot); + } + + /// + /// Specify the urls the web host will listen on. + /// + /// The to configure. + /// The urls the hosted application will listen on. + /// The . + 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)); + } + + /// + /// Start the web host and listen on the speficied urls. + /// + /// The to start. + /// The urls the hosted application will listen on. + /// The . public static IWebHost Start(this IWebHostBuilder hostBuilder, params string[] urls) { var host = hostBuilder.UseUrls(urls).Build(); @@ -131,4 +209,4 @@ namespace Microsoft.AspNetCore.Hosting public IServer CreateServer(IConfiguration configuration) => _server; } } -} \ No newline at end of file +} diff --git a/src/Microsoft.AspNetCore.Hosting/WebHostExtensions.cs b/src/Microsoft.AspNetCore.Hosting/WebHostExtensions.cs index 380aeb7ac8..d959b8042f 100644 --- a/src/Microsoft.AspNetCore.Hosting/WebHostExtensions.cs +++ b/src/Microsoft.AspNetCore.Hosting/WebHostExtensions.cs @@ -13,7 +13,7 @@ namespace Microsoft.AspNetCore.Hosting /// /// Runs a web application and block the calling thread until host shutdown. /// - /// + /// The to run. public static void Run(this IWebHost host) { using (var cts = new CancellationTokenSource()) @@ -33,7 +33,7 @@ namespace Microsoft.AspNetCore.Hosting /// /// Runs a web application and block the calling thread until token is triggered or shutdown is triggered. /// - /// + /// The to run. /// The token to trigger shutdown. public static void Run(this IWebHost host, CancellationToken token) { diff --git a/src/Microsoft.AspNetCore.TestHost/TestServer.cs b/src/Microsoft.AspNetCore.TestHost/TestServer.cs index 1d5f044333..cdc7faa4c6 100644 --- a/src/Microsoft.AspNetCore.TestHost/TestServer.cs +++ b/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; diff --git a/test/Microsoft.AspNetCore.Hosting.Tests/WebHostBuilderTests.cs b/test/Microsoft.AspNetCore.Hosting.Tests/WebHostBuilderTests.cs index 026fcf9851..f2a9a1fd49 100644 --- a/test/Microsoft.AspNetCore.Hosting.Tests/WebHostBuilderTests.cs +++ b/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(); - // This should not throw - hostBuilder.Build(); + var exception = Assert.Throws(() => 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(); diff --git a/test/Microsoft.AspNetCore.Hosting.Tests/WebHostConfigurationsTests.cs b/test/Microsoft.AspNetCore.Hosting.Tests/WebHostConfigurationsTests.cs index c975395ef9..8cb54a852c 100644 --- a/test/Microsoft.AspNetCore.Hosting.Tests/WebHostConfigurationsTests.cs +++ b/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] diff --git a/test/Microsoft.AspNetCore.TestHost.Tests/TestServerTests.cs b/test/Microsoft.AspNetCore.TestHost.Tests/TestServerTests.cs index 6c5330ffbc..8ee9583b2b 100644 --- a/test/Microsoft.AspNetCore.TestHost.Tests/TestServerTests.cs +++ b/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();