From 66584a0f30a39040ebba13e72d6f17336abc1880 Mon Sep 17 00:00:00 2001 From: Safia Abdalla Date: Wed, 30 Sep 2020 13:42:05 -0700 Subject: [PATCH] Add doc strings for public APIs in src/Hosting (#26443) * Add doc strings for public APIs in src/Hosting * Apply suggestions from code review Co-authored-by: Chris Ross Co-authored-by: Pranav K Co-authored-by: James Newton-King * Address feedback from peer review Co-authored-by: Chris Ross Co-authored-by: Pranav K Co-authored-by: James Newton-King --- .../Abstractions/src/EnvironmentName.cs | 11 ++++ ...ingAbstractionsWebHostBuilderExtensions.cs | 3 + src/Hosting/Abstractions/src/IStartup.cs | 13 +++- .../src/IStartupConfigureContainerFilter.cs | 5 ++ .../src/IStartupConfigureServicesFilter.cs | 5 ++ .../Abstractions/src/IStartupFilter.cs | 11 ++++ ...oft.AspNetCore.Hosting.Abstractions.csproj | 2 +- .../Abstractions/src/WebHostDefaults.cs | 61 +++++++++++++++++++ .../src/Builder/ApplicationBuilderFactory.cs | 12 ++++ .../src/Builder/IApplicationBuilderFactory.cs | 10 ++- .../GenericHostWebHostBuilderExtensions.cs | 3 + .../src/Http/DefaultHttpContextFactory.cs | 15 +++++ .../src/Microsoft.AspNetCore.Hosting.csproj | 2 +- .../Server/Features/ServerAddressesFeature.cs | 5 ++ .../Hosting/src/Startup/DelegateStartup.cs | 12 ++++ .../Hosting/src/Startup/StartupBase.cs | 35 ++++++++++- .../Hosting/src/WebHostBuilderExtensions.cs | 3 + src/Hosting/Hosting/src/WebHostExtensions.cs | 3 + .../src/Features/IServerAddressesFeature.cs | 9 +++ .../src/IHostContextContainer.cs | 3 + ...NetCore.Hosting.Server.Abstractions.csproj | 2 +- .../src/HostBuilderTestServerExtensions.cs | 3 + .../src/Microsoft.AspNetCore.TestHost.csproj | 2 +- src/Hosting/TestHost/src/TestServer.cs | 27 ++++++++ .../TestHost/src/WebHostBuilderExtensions.cs | 36 +++++++++++ .../TestHost/src/WebHostBuilderFactory.cs | 15 +++++ src/Hosting/TestHost/src/WebSocketClient.cs | 14 +++++ ....AspNetCore.Hosting.WindowsServices.csproj | 2 +- .../WindowsServices/src/WebHostService.cs | 2 + 29 files changed, 318 insertions(+), 8 deletions(-) diff --git a/src/Hosting/Abstractions/src/EnvironmentName.cs b/src/Hosting/Abstractions/src/EnvironmentName.cs index df93c4ddf1..c881a52b3c 100644 --- a/src/Hosting/Abstractions/src/EnvironmentName.cs +++ b/src/Hosting/Abstractions/src/EnvironmentName.cs @@ -9,8 +9,19 @@ namespace Microsoft.AspNetCore.Hosting [System.Obsolete("This type is obsolete and will be removed in a future version. The recommended alternative is Microsoft.Extensions.Hosting.Environments.", error: false)] public static class EnvironmentName { + /// + /// A string constant for Development environments. + /// public static readonly string Development = "Development"; + + /// + /// A string constant for Staging environments. + /// public static readonly string Staging = "Staging"; + + /// + /// A string constant for Production environments. + /// public static readonly string Production = "Production"; } } diff --git a/src/Hosting/Abstractions/src/HostingAbstractionsWebHostBuilderExtensions.cs b/src/Hosting/Abstractions/src/HostingAbstractionsWebHostBuilderExtensions.cs index 04f9ca6d65..b89e0d6263 100644 --- a/src/Hosting/Abstractions/src/HostingAbstractionsWebHostBuilderExtensions.cs +++ b/src/Hosting/Abstractions/src/HostingAbstractionsWebHostBuilderExtensions.cs @@ -12,6 +12,9 @@ using Microsoft.Extensions.DependencyInjection; namespace Microsoft.AspNetCore.Hosting { + /// + /// Contains extension methods for configuring the . + /// public static class HostingAbstractionsWebHostBuilderExtensions { /// diff --git a/src/Hosting/Abstractions/src/IStartup.cs b/src/Hosting/Abstractions/src/IStartup.cs index 3a533c8df2..3ccd7e5130 100644 --- a/src/Hosting/Abstractions/src/IStartup.cs +++ b/src/Hosting/Abstractions/src/IStartup.cs @@ -7,10 +7,21 @@ using Microsoft.Extensions.DependencyInjection; namespace Microsoft.AspNetCore.Hosting { + /// + /// Provides an interface for initializing services and middleware used by an application. + /// public interface IStartup { + /// + /// Register services into the . + /// + /// The to add the services to. IServiceProvider ConfigureServices(IServiceCollection services); + /// + /// Configures the application. + /// + /// An for the app to configure. void Configure(IApplicationBuilder app); } -} \ No newline at end of file +} diff --git a/src/Hosting/Abstractions/src/IStartupConfigureContainerFilter.cs b/src/Hosting/Abstractions/src/IStartupConfigureContainerFilter.cs index 48c0dbd80f..6866fc6f36 100644 --- a/src/Hosting/Abstractions/src/IStartupConfigureContainerFilter.cs +++ b/src/Hosting/Abstractions/src/IStartupConfigureContainerFilter.cs @@ -12,6 +12,11 @@ namespace Microsoft.AspNetCore.Hosting [Obsolete] public interface IStartupConfigureContainerFilter { + /// + /// Extends the provided and returns a modified action of the same type. + /// + /// The ConfigureContainer method to extend. + /// A modified . Action ConfigureContainer(Action container); } } diff --git a/src/Hosting/Abstractions/src/IStartupConfigureServicesFilter.cs b/src/Hosting/Abstractions/src/IStartupConfigureServicesFilter.cs index 8594b1c3f1..ee04264cf6 100644 --- a/src/Hosting/Abstractions/src/IStartupConfigureServicesFilter.cs +++ b/src/Hosting/Abstractions/src/IStartupConfigureServicesFilter.cs @@ -13,6 +13,11 @@ namespace Microsoft.AspNetCore.Hosting [Obsolete] public interface IStartupConfigureServicesFilter { + /// + /// Extends the provided and returns a modified action of the same type. + /// + /// The ConfigureServices method to extend. + /// A modified . Action ConfigureServices(Action next); } } diff --git a/src/Hosting/Abstractions/src/IStartupFilter.cs b/src/Hosting/Abstractions/src/IStartupFilter.cs index 2f0a3cf39d..b6f6bf3ac1 100644 --- a/src/Hosting/Abstractions/src/IStartupFilter.cs +++ b/src/Hosting/Abstractions/src/IStartupFilter.cs @@ -6,8 +6,19 @@ using Microsoft.AspNetCore.Builder; namespace Microsoft.AspNetCore.Hosting { + /// + /// Provides an interface for extending the middleware pipeline with new + /// Configure methods. Can be used to add defaults to the beginning or + /// end of the pipeline without having to make the app author explicitly + /// register middleware. + /// public interface IStartupFilter { + /// + /// Extends the provided and returns an of the same type. + /// + /// The Configure method to extend. + /// A modified . Action Configure(Action next); } } diff --git a/src/Hosting/Abstractions/src/Microsoft.AspNetCore.Hosting.Abstractions.csproj b/src/Hosting/Abstractions/src/Microsoft.AspNetCore.Hosting.Abstractions.csproj index 31618baeb0..37e76f93f6 100644 --- a/src/Hosting/Abstractions/src/Microsoft.AspNetCore.Hosting.Abstractions.csproj +++ b/src/Hosting/Abstractions/src/Microsoft.AspNetCore.Hosting.Abstractions.csproj @@ -4,7 +4,7 @@ ASP.NET Core hosting and startup abstractions for web applications. $(DefaultNetCoreTargetFramework) true - $(NoWarn);CS1591 + $(NoWarn.Replace('1591', '')) true aspnetcore;hosting false diff --git a/src/Hosting/Abstractions/src/WebHostDefaults.cs b/src/Hosting/Abstractions/src/WebHostDefaults.cs index b6fdb728a2..3e5fc5d537 100644 --- a/src/Hosting/Abstractions/src/WebHostDefaults.cs +++ b/src/Hosting/Abstractions/src/WebHostDefaults.cs @@ -3,24 +3,85 @@ namespace Microsoft.AspNetCore.Hosting { + /// + /// Contains a set of constants representing configuration keys. + /// public static class WebHostDefaults { + /// + /// The configuration key associated with an application name. + /// public static readonly string ApplicationKey = "applicationName"; + + /// + /// The configuration key associated with the startup assembly. + /// public static readonly string StartupAssemblyKey = "startupAssembly"; + + /// + /// The configuration key associated with "hostingStartupAssemblies" configuration. + /// public static readonly string HostingStartupAssembliesKey = "hostingStartupAssemblies"; + + /// + /// The configuration key associated with the "hostingStartupExcludeAssemblies" configuration. + /// public static readonly string HostingStartupExcludeAssembliesKey = "hostingStartupExcludeAssemblies"; + /// + /// The configuration key associated with the "DetailedErrors" configuration. + /// + public static readonly string DetailedErrorsKey = "detailedErrors"; + + /// + /// The configuration key associated with the application's environment setting. + /// public static readonly string EnvironmentKey = "environment"; + + /// + /// The configuration key associated with the "webRoot" configuration. + /// public static readonly string WebRootKey = "webroot"; + + /// + /// The configuration key associated with the "captureStartupErrors" configuration. + /// public static readonly string CaptureStartupErrorsKey = "captureStartupErrors"; + + /// + /// The configuration key associated with the "urls" configuration. + /// public static readonly string ServerUrlsKey = "urls"; + + /// + /// The configuration key associated with the "ContentRoot" configuration. + /// public static readonly string ContentRootKey = "contentRoot"; + + /// + /// The configuration key associated with the "PreferHostingUrls" configuration. + /// public static readonly string PreferHostingUrlsKey = "preferHostingUrls"; + + /// + /// The configuration key associated with the "PreventHostingStartup" configuration. + /// public static readonly string PreventHostingStartupKey = "preventHostingStartup"; + + /// + /// The configuration key associated with the "SuppressStatusMessages" configuration. + /// public static readonly string SuppressStatusMessagesKey = "suppressStatusMessages"; + /// + /// The configuration key associated with the "ShutdownTimeoutSeconds" configuration. + /// public static readonly string ShutdownTimeoutKey = "shutdownTimeoutSeconds"; + + /// + /// The configuration key associated with the "StaticWebAssets" configuration. + /// public static readonly string StaticWebAssetsKey = "staticWebAssets"; } } diff --git a/src/Hosting/Hosting/src/Builder/ApplicationBuilderFactory.cs b/src/Hosting/Hosting/src/Builder/ApplicationBuilderFactory.cs index 01482dc91b..c801c9efb9 100644 --- a/src/Hosting/Hosting/src/Builder/ApplicationBuilderFactory.cs +++ b/src/Hosting/Hosting/src/Builder/ApplicationBuilderFactory.cs @@ -9,15 +9,27 @@ using Microsoft.AspNetCore.Http.Features; namespace Microsoft.AspNetCore.Hosting.Builder { + /// + /// A factory for creating instances. + /// public class ApplicationBuilderFactory : IApplicationBuilderFactory { private readonly IServiceProvider _serviceProvider; + /// + /// Initialize a new factory instance with an . + /// + /// The used to resolve dependencies and initialize components. public ApplicationBuilderFactory(IServiceProvider serviceProvider) { _serviceProvider = serviceProvider; } + /// + /// Create an builder given a . + /// + /// An of HTTP features. + /// An configured with . public IApplicationBuilder CreateBuilder(IFeatureCollection serverFeatures) { return new ApplicationBuilder(_serviceProvider, serverFeatures); diff --git a/src/Hosting/Hosting/src/Builder/IApplicationBuilderFactory.cs b/src/Hosting/Hosting/src/Builder/IApplicationBuilderFactory.cs index d44398fb69..06f84af29d 100644 --- a/src/Hosting/Hosting/src/Builder/IApplicationBuilderFactory.cs +++ b/src/Hosting/Hosting/src/Builder/IApplicationBuilderFactory.cs @@ -6,8 +6,16 @@ using Microsoft.AspNetCore.Http.Features; namespace Microsoft.AspNetCore.Hosting.Builder { + /// + /// Provides an interface for implementing a factory that produces instances. + /// public interface IApplicationBuilderFactory { + /// + /// Create an builder given a + /// + /// An of HTTP features. + /// An configured with . IApplicationBuilder CreateBuilder(IFeatureCollection serverFeatures); } -} \ No newline at end of file +} diff --git a/src/Hosting/Hosting/src/GenericHostWebHostBuilderExtensions.cs b/src/Hosting/Hosting/src/GenericHostWebHostBuilderExtensions.cs index 4899a8caf2..9c01854ce3 100644 --- a/src/Hosting/Hosting/src/GenericHostWebHostBuilderExtensions.cs +++ b/src/Hosting/Hosting/src/GenericHostWebHostBuilderExtensions.cs @@ -7,6 +7,9 @@ using Microsoft.Extensions.DependencyInjection; namespace Microsoft.Extensions.Hosting { + /// + /// Contains extensions for an . + /// public static class GenericHostWebHostBuilderExtensions { /// diff --git a/src/Hosting/Hosting/src/Http/DefaultHttpContextFactory.cs b/src/Hosting/Hosting/src/Http/DefaultHttpContextFactory.cs index 9686aacb45..6ee37986e8 100644 --- a/src/Hosting/Hosting/src/Http/DefaultHttpContextFactory.cs +++ b/src/Hosting/Hosting/src/Http/DefaultHttpContextFactory.cs @@ -12,6 +12,9 @@ using Microsoft.Extensions.Options; namespace Microsoft.AspNetCore.Http { + /// + /// A factory for creating instances. + /// public class DefaultHttpContextFactory : IHttpContextFactory { private readonly IHttpContextAccessor? _httpContextAccessor; @@ -20,6 +23,10 @@ namespace Microsoft.AspNetCore.Http // This takes the IServiceProvider because it needs to support an ever expanding // set of services that flow down into HttpContext features + /// + /// Creates a factory for creating instances. + /// + /// The to be used when retrieving services. public DefaultHttpContextFactory(IServiceProvider serviceProvider) { // May be null @@ -30,6 +37,11 @@ namespace Microsoft.AspNetCore.Http internal IHttpContextAccessor? HttpContextAccessor => _httpContextAccessor; + /// + /// Create an instance given an . + /// + /// + /// An initialized object. public HttpContext Create(IFeatureCollection featureCollection) { if (featureCollection is null) @@ -67,6 +79,9 @@ namespace Microsoft.AspNetCore.Http return httpContext; } + /// + /// Clears the current . + /// public void Dispose(HttpContext httpContext) { if (_httpContextAccessor != null) diff --git a/src/Hosting/Hosting/src/Microsoft.AspNetCore.Hosting.csproj b/src/Hosting/Hosting/src/Microsoft.AspNetCore.Hosting.csproj index c0e3e77284..1d9dde5666 100644 --- a/src/Hosting/Hosting/src/Microsoft.AspNetCore.Hosting.csproj +++ b/src/Hosting/Hosting/src/Microsoft.AspNetCore.Hosting.csproj @@ -4,7 +4,7 @@ ASP.NET Core hosting infrastructure and startup logic for web applications. $(DefaultNetCoreTargetFramework) true - $(NoWarn);CS1591 + $(NoWarn.Replace('1591', '')) true aspnetcore;hosting false diff --git a/src/Hosting/Hosting/src/Server/Features/ServerAddressesFeature.cs b/src/Hosting/Hosting/src/Server/Features/ServerAddressesFeature.cs index 3b4c161f60..6c87643bc6 100644 --- a/src/Hosting/Hosting/src/Server/Features/ServerAddressesFeature.cs +++ b/src/Hosting/Hosting/src/Server/Features/ServerAddressesFeature.cs @@ -7,10 +7,15 @@ using System.Collections.Generic; namespace Microsoft.AspNetCore.Hosting.Server.Features { + /// + /// Specifies the address used by the server. + /// public class ServerAddressesFeature : IServerAddressesFeature { + /// public ICollection Addresses { get; } = new List(); + /// public bool PreferHostingUrls { get; set; } } } diff --git a/src/Hosting/Hosting/src/Startup/DelegateStartup.cs b/src/Hosting/Hosting/src/Startup/DelegateStartup.cs index 0c1bcb5c04..c71f54c52e 100644 --- a/src/Hosting/Hosting/src/Startup/DelegateStartup.cs +++ b/src/Hosting/Hosting/src/Startup/DelegateStartup.cs @@ -9,15 +9,27 @@ using Microsoft.Extensions.DependencyInjection; namespace Microsoft.AspNetCore.Hosting { + /// + /// Used for initializing services and middlewares used by an application. + /// public class DelegateStartup : StartupBase { private Action _configureApp; + /// + /// Creates a new instance. + /// + /// A factory for creating instances. + /// An for configuring the application. public DelegateStartup(IServiceProviderFactory factory, Action configureApp) : base(factory) { _configureApp = configureApp; } + /// + /// Configures the with the initialized . + /// + /// The . public override void Configure(IApplicationBuilder app) => _configureApp(app); } } diff --git a/src/Hosting/Hosting/src/Startup/StartupBase.cs b/src/Hosting/Hosting/src/Startup/StartupBase.cs index 5a180ba9b4..e44c4f402f 100644 --- a/src/Hosting/Hosting/src/Startup/StartupBase.cs +++ b/src/Hosting/Hosting/src/Startup/StartupBase.cs @@ -7,8 +7,15 @@ using Microsoft.Extensions.DependencyInjection; namespace Microsoft.AspNetCore.Hosting { + /// + /// Base class for initializing services and middlewares used by an application. + /// public abstract class StartupBase : IStartup { + /// + /// Configures the application. + /// + /// An for the app to configure. public abstract void Configure(IApplicationBuilder app); IServiceProvider IStartup.ConfigureServices(IServiceCollection services) @@ -17,25 +24,47 @@ namespace Microsoft.AspNetCore.Hosting return CreateServiceProvider(services); } + /// + /// Register services into the . + /// + /// The to add the services to. public virtual void ConfigureServices(IServiceCollection services) { } + /// + /// Creates an instance for a given . + /// + /// The to add the services to. + /// The . public virtual IServiceProvider CreateServiceProvider(IServiceCollection services) { return services.BuildServiceProvider(); } } + /// + /// Base class for initializing services and middlewares used for configuring a . + /// + /// The type of builder associated with the startup configuration. public abstract class StartupBase : StartupBase { private readonly IServiceProviderFactory _factory; + /// + /// Constructor for StartupBase class. + /// + /// A factory used to generate instances. public StartupBase(IServiceProviderFactory factory) { _factory = factory; } + /// + /// Creates an instance for a given . + /// + /// The to add the services to. + /// The . public override IServiceProvider CreateServiceProvider(IServiceCollection services) { var builder = _factory.CreateBuilder(services); @@ -43,8 +72,12 @@ namespace Microsoft.AspNetCore.Hosting return _factory.CreateServiceProvider(builder); } + /// + /// Sets up the service container. + /// + /// The builder associated with the container to configure. public virtual void ConfigureContainer(TBuilder builder) { } } -} \ No newline at end of file +} diff --git a/src/Hosting/Hosting/src/WebHostBuilderExtensions.cs b/src/Hosting/Hosting/src/WebHostBuilderExtensions.cs index 252d5c5d43..e8cc279ced 100644 --- a/src/Hosting/Hosting/src/WebHostBuilderExtensions.cs +++ b/src/Hosting/Hosting/src/WebHostBuilderExtensions.cs @@ -17,6 +17,9 @@ using Microsoft.Extensions.Logging; namespace Microsoft.AspNetCore.Hosting { + /// + /// Contains extensions for configuring an . + /// public static class WebHostBuilderExtensions { /// diff --git a/src/Hosting/Hosting/src/WebHostExtensions.cs b/src/Hosting/Hosting/src/WebHostExtensions.cs index f3197e15d3..2b2e226434 100644 --- a/src/Hosting/Hosting/src/WebHostExtensions.cs +++ b/src/Hosting/Hosting/src/WebHostExtensions.cs @@ -12,6 +12,9 @@ using Microsoft.Extensions.Hosting; namespace Microsoft.AspNetCore.Hosting { + /// + /// Contains extensions for managing the lifecycle of an . + /// public static class WebHostExtensions { /// diff --git a/src/Hosting/Server.Abstractions/src/Features/IServerAddressesFeature.cs b/src/Hosting/Server.Abstractions/src/Features/IServerAddressesFeature.cs index 24a9a267a5..10f222932d 100644 --- a/src/Hosting/Server.Abstractions/src/Features/IServerAddressesFeature.cs +++ b/src/Hosting/Server.Abstractions/src/Features/IServerAddressesFeature.cs @@ -5,10 +5,19 @@ using System.Collections.Generic; namespace Microsoft.AspNetCore.Hosting.Server.Features { + /// + /// Specifies the address used by the server. + /// public interface IServerAddressesFeature { + /// + /// An of addresses used by the server. + /// ICollection Addresses { get; } + /// + /// to prefer URLs configured by the host rather than the server. + /// bool PreferHostingUrls { get; set; } } } diff --git a/src/Hosting/Server.Abstractions/src/IHostContextContainer.cs b/src/Hosting/Server.Abstractions/src/IHostContextContainer.cs index f413ad451a..aafc5fb701 100644 --- a/src/Hosting/Server.Abstractions/src/IHostContextContainer.cs +++ b/src/Hosting/Server.Abstractions/src/IHostContextContainer.cs @@ -10,6 +10,9 @@ namespace Microsoft.AspNetCore.Hosting.Server.Abstractions /// The Host context public interface IHostContextContainer where TContext : notnull { + /// + /// Represents the of the host. + /// TContext HostContext { get; set; } } } diff --git a/src/Hosting/Server.Abstractions/src/Microsoft.AspNetCore.Hosting.Server.Abstractions.csproj b/src/Hosting/Server.Abstractions/src/Microsoft.AspNetCore.Hosting.Server.Abstractions.csproj index 758bf3bff0..4dba775074 100644 --- a/src/Hosting/Server.Abstractions/src/Microsoft.AspNetCore.Hosting.Server.Abstractions.csproj +++ b/src/Hosting/Server.Abstractions/src/Microsoft.AspNetCore.Hosting.Server.Abstractions.csproj @@ -4,7 +4,7 @@ ASP.NET Core hosting server abstractions for web applications. $(DefaultNetCoreTargetFramework) true - $(NoWarn);CS1591 + $(NoWarn.Replace('1591', '')) true aspnetcore;hosting false diff --git a/src/Hosting/TestHost/src/HostBuilderTestServerExtensions.cs b/src/Hosting/TestHost/src/HostBuilderTestServerExtensions.cs index e52f3d6ab0..718b335501 100644 --- a/src/Hosting/TestHost/src/HostBuilderTestServerExtensions.cs +++ b/src/Hosting/TestHost/src/HostBuilderTestServerExtensions.cs @@ -10,6 +10,9 @@ using Microsoft.Extensions.Hosting; namespace Microsoft.AspNetCore.TestHost { + /// + /// Contains extensions for retrieving properties from . + /// public static class HostBuilderTestServerExtensions { /// diff --git a/src/Hosting/TestHost/src/Microsoft.AspNetCore.TestHost.csproj b/src/Hosting/TestHost/src/Microsoft.AspNetCore.TestHost.csproj index d91a72748d..bcd750fe88 100644 --- a/src/Hosting/TestHost/src/Microsoft.AspNetCore.TestHost.csproj +++ b/src/Hosting/TestHost/src/Microsoft.AspNetCore.TestHost.csproj @@ -3,7 +3,7 @@ ASP.NET Core web server for writing and running tests. $(DefaultNetCoreTargetFramework) - $(NoWarn);CS1591 + $(NoWarn.Replace('1591', '')) true aspnetcore;hosting;testing diff --git a/src/Hosting/TestHost/src/TestServer.cs b/src/Hosting/TestHost/src/TestServer.cs index cb41f75f6e..1ba0471c74 100644 --- a/src/Hosting/TestHost/src/TestServer.cs +++ b/src/Hosting/TestHost/src/TestServer.cs @@ -13,6 +13,9 @@ using Microsoft.Extensions.DependencyInjection; namespace Microsoft.AspNetCore.TestHost { + /// + /// An implementation for executing tests. + /// public class TestServer : IServer { private IWebHost _hostInstance; @@ -69,8 +72,14 @@ namespace Microsoft.AspNetCore.TestHost Services = host.Services; } + /// + /// Gets or sets the base address associated with the HttpClient returned by the test server. Defaults to http://localhost/. + /// public Uri BaseAddress { get; set; } = new Uri("http://localhost/"); + /// + /// Gets the instance associated with the test server. + /// public IWebHost Host { get @@ -80,8 +89,14 @@ namespace Microsoft.AspNetCore.TestHost } } + /// + /// Gets the service provider associated with the test server. + /// public IServiceProvider Services { get; } + /// + /// Gets the collection of server features associated with the test server. + /// public IFeatureCollection Features { get; } /// @@ -99,17 +114,26 @@ namespace Microsoft.AspNetCore.TestHost get => _application ?? throw new InvalidOperationException("The server has not been started or no web application was configured."); } + /// + /// Creates a custom for processing HTTP requests/responses with the test server. + /// public HttpMessageHandler CreateHandler() { var pathBase = BaseAddress == null ? PathString.Empty : PathString.FromUriComponent(BaseAddress); return new ClientHandler(pathBase, Application) { AllowSynchronousIO = AllowSynchronousIO, PreserveExecutionContext = PreserveExecutionContext }; } + /// + /// Creates a for processing HTTP requests/responses with the test server. + /// public HttpClient CreateClient() { return new HttpClient(CreateHandler()) { BaseAddress = BaseAddress }; } + /// + /// Creates a for interacting with the test server. + /// public WebSocketClient CreateWebSocketClient() { var pathBase = BaseAddress == null ? PathString.Empty : PathString.FromUriComponent(BaseAddress); @@ -159,6 +183,9 @@ namespace Microsoft.AspNetCore.TestHost return await builder.SendAsync(cancellationToken).ConfigureAwait(false); } + /// + /// Dispoes the object associated with the test server. + /// public void Dispose() { if (!_disposed) diff --git a/src/Hosting/TestHost/src/WebHostBuilderExtensions.cs b/src/Hosting/TestHost/src/WebHostBuilderExtensions.cs index cd69b38de5..07e47791f8 100644 --- a/src/Hosting/TestHost/src/WebHostBuilderExtensions.cs +++ b/src/Hosting/TestHost/src/WebHostBuilderExtensions.cs @@ -13,8 +13,16 @@ using Microsoft.Extensions.Hosting; namespace Microsoft.AspNetCore.TestHost { + /// + /// Contains extensions for configuring the instance. + /// public static class WebHostBuilderExtensions { + /// + /// Enables the service. + /// + /// The . + /// The . public static IWebHostBuilder UseTestServer(this IWebHostBuilder builder) { return builder.ConfigureServices(services => @@ -44,6 +52,12 @@ namespace Microsoft.AspNetCore.TestHost return host.GetTestServer().CreateClient(); } + /// + /// Configures the instance with the services provided in . + /// + /// The . + /// An that registers services onto the . + /// The . public static IWebHostBuilder ConfigureTestServices(this IWebHostBuilder webHostBuilder, Action servicesConfiguration) { if (webHostBuilder == null) @@ -73,6 +87,13 @@ namespace Microsoft.AspNetCore.TestHost return webHostBuilder; } + /// + /// Configures the instance with the services provided in . + /// + /// The . + /// An that registers services onto the . + /// A collection of service descriptors. + /// public static IWebHostBuilder ConfigureTestContainer(this IWebHostBuilder webHostBuilder, Action servicesConfiguration) { if (webHostBuilder == null) @@ -94,6 +115,13 @@ namespace Microsoft.AspNetCore.TestHost return webHostBuilder; } + /// + /// Sets the content root of relative to the . + /// + /// The . + /// The directory of the solution file. + /// The name of the solution file to make the content root relative to. + /// The . [SuppressMessage("ApiDesign", "RS0026:Do not add multiple public overloads with optional parameters", Justification = "Required to maintain compatibility")] public static IWebHostBuilder UseSolutionRelativeContentRoot( this IWebHostBuilder builder, @@ -103,6 +131,14 @@ namespace Microsoft.AspNetCore.TestHost return builder.UseSolutionRelativeContentRoot(solutionRelativePath, AppContext.BaseDirectory, solutionName); } + /// + /// Sets the content root of relative to the . + /// + /// The . + /// The directory of the solution file. + /// The root of the app's directory. + /// The name of the solution file to make the content root relative to. + /// The . [SuppressMessage("ApiDesign", "RS0026:Do not add multiple public overloads with optional parameters", Justification = "Required to maintain compatibility")] public static IWebHostBuilder UseSolutionRelativeContentRoot( this IWebHostBuilder builder, diff --git a/src/Hosting/TestHost/src/WebHostBuilderFactory.cs b/src/Hosting/TestHost/src/WebHostBuilderFactory.cs index 86930ce8d5..2fcc5fba99 100644 --- a/src/Hosting/TestHost/src/WebHostBuilderFactory.cs +++ b/src/Hosting/TestHost/src/WebHostBuilderFactory.cs @@ -7,14 +7,29 @@ using Microsoft.Extensions.Hosting; namespace Microsoft.AspNetCore.TestHost { + /// + /// A factory for creating instances. + /// public static class WebHostBuilderFactory { + /// + /// Resolves an defined in the entry point of an assembly. + /// + /// The assembly to look for an in. + /// The arguments to use when creating the instance. + /// An instance retrieved from the assembly in . public static IWebHostBuilder CreateFromAssemblyEntryPoint(Assembly assembly, string[] args) { var factory = HostFactoryResolver.ResolveWebHostBuilderFactory(assembly); return factory?.Invoke(args); } + /// + /// Resolves an defined in an assembly where is declared. + /// + /// The arguments to use when creating the instance. + /// Type contained in the target assembly + /// An instance retrieved from the assembly. public static IWebHostBuilder CreateFromTypesAssemblyEntryPoint(string[] args) => CreateFromAssemblyEntryPoint(typeof(T).Assembly, args); } diff --git a/src/Hosting/TestHost/src/WebSocketClient.cs b/src/Hosting/TestHost/src/WebSocketClient.cs index 7743e51630..1d9b5df646 100644 --- a/src/Hosting/TestHost/src/WebSocketClient.cs +++ b/src/Hosting/TestHost/src/WebSocketClient.cs @@ -15,6 +15,9 @@ using Microsoft.Net.Http.Headers; namespace Microsoft.AspNetCore.TestHost { + /// + /// Provides a client for connecting over WebSockets to a test server. + /// public class WebSocketClient { private readonly ApplicationWrapper _application; @@ -34,12 +37,18 @@ namespace Microsoft.AspNetCore.TestHost SubProtocols = new List(); } + /// + /// Gets the list of WebSocket subprotocols that are established in the initial handshake. + /// public IList SubProtocols { get; private set; } + /// + /// Gets or sets the handler used to configure the outgoing request to the WebSocket endpoint. + /// public Action ConfigureRequest { get; @@ -49,6 +58,11 @@ namespace Microsoft.AspNetCore.TestHost internal bool AllowSynchronousIO { get; set; } internal bool PreserveExecutionContext { get; set; } + /// + /// Establishes a WebSocket connection to an endpoint. + /// + /// The of the endpoint. + /// A used to terminate the connection. public async Task ConnectAsync(Uri uri, CancellationToken cancellationToken) { WebSocketFeature webSocketFeature = null; diff --git a/src/Hosting/WindowsServices/src/Microsoft.AspNetCore.Hosting.WindowsServices.csproj b/src/Hosting/WindowsServices/src/Microsoft.AspNetCore.Hosting.WindowsServices.csproj index eabc8caa82..43774cc02f 100644 --- a/src/Hosting/WindowsServices/src/Microsoft.AspNetCore.Hosting.WindowsServices.csproj +++ b/src/Hosting/WindowsServices/src/Microsoft.AspNetCore.Hosting.WindowsServices.csproj @@ -3,7 +3,7 @@ ASP.NET Core hosting infrastructure and startup logic for web applications running within a Windows service. $(DefaultNetCoreTargetFramework) - $(NoWarn);CS1591 + $(NoWarn.Replace('1591', '')) true aspnetcore;hosting diff --git a/src/Hosting/WindowsServices/src/WebHostService.cs b/src/Hosting/WindowsServices/src/WebHostService.cs index ce0a1b5183..450ab0c669 100644 --- a/src/Hosting/WindowsServices/src/WebHostService.cs +++ b/src/Hosting/WindowsServices/src/WebHostService.cs @@ -33,6 +33,7 @@ namespace Microsoft.AspNetCore.Hosting.WindowsServices /// internal void Start() => OnStart(Array.Empty()); + /// protected sealed override void OnStart(string[] args) { OnStarting(args); @@ -57,6 +58,7 @@ namespace Microsoft.AspNetCore.Hosting.WindowsServices }); } + /// protected sealed override void OnStop() { _stopRequestedByWindows = true;