From 3bc2ed612ff4bafd7ee8a7a504b83a9d0c0326b5 Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Sat, 27 Oct 2018 10:31:34 -0500 Subject: [PATCH] Update BuildWebHost to CreateWebHostBuilder (MD topics) Updates Updates Update Tab update Repair versioning --- aspnetcore/fundamentals/host/web-host.md | 109 ++++++-- aspnetcore/fundamentals/servers/kestrel.md | 239 +++++++++++++++++- aspnetcore/host-and-deploy/iis/index.md | 6 +- .../getting-started-with-swashbuckle.md | 56 +++- 4 files changed, 370 insertions(+), 40 deletions(-) diff --git a/aspnetcore/fundamentals/host/web-host.md b/aspnetcore/fundamentals/host/web-host.md index 0150f6397730..6aa466b2a926 100644 --- a/aspnetcore/fundamentals/host/web-host.md +++ b/aspnetcore/fundamentals/host/web-host.md @@ -4,7 +4,7 @@ author: guardrex description: Learn about the web host in ASP.NET Core, which is responsible for app startup and lifetime management. ms.author: riande ms.custom: mvc -ms.date: 10/18/2018 +ms.date: 10/27/2018 uid: fundamentals/host/web-host --- # ASP.NET Core Web Host @@ -15,7 +15,7 @@ ASP.NET Core apps configure and launch a *host*. The host is responsible for app ## Set up a host -::: moniker range=">= aspnetcore-2.0" +::: moniker range=">= aspnetcore-2.1" Create a host using an instance of [IWebHostBuilder](/dotnet/api/microsoft.aspnetcore.hosting.iwebhostbuilder). This is typically performed in the app's entry point, the `Main` method. In the project templates, `Main` is located in *Program.cs*. A typical *Program.cs* calls [CreateDefaultBuilder](/dotnet/api/microsoft.aspnetcore.webhost.createdefaultbuilder) to start setting up a host: @@ -33,6 +33,31 @@ public class Program } ``` +::: moniker-end + +::: moniker range="= aspnetcore-2.0" + +Create a host using an instance of [IWebHost](/dotnet/api/microsoft.aspnetcore.hosting.iwebhost). This is typically performed in the app's entry point, the `Main` method. In the project templates, `Main` is located in *Program.cs*. A typical *Program.cs* calls [CreateDefaultBuilder](/dotnet/api/microsoft.aspnetcore.webhost.createdefaultbuilder) to start setting up a host: + +```csharp +public class Program +{ + public static void Main(string[] args) + { + BuildWebHost(args).Run(); + } + + public static IWebHost BuildWebHost(string[] args) => + WebHost.CreateDefaultBuilder(args) + .UseStartup() + .Build(); +} +``` + +::: moniker-end + +::: moniker range=">= aspnetcore-2.0" + `CreateDefaultBuilder` performs the following tasks: * Configures [Kestrel](xref:fundamentals/servers/kestrel) as the web server and configures the server using the app's hosting configuration providers. For the Kestrel default options, see . @@ -86,12 +111,11 @@ The configuration defined by `CreateDefaultBuilder` can be overridden and augmen { options.Limits.MaxRequestBodySize = 20000000; }); - ... ``` ::: moniker-end -::: moniker range="= aspnetcore-2.0 || aspnetcore-2.1" +::: moniker range="= aspnetcore-2.1" * The following call to [UseKestrel](/dotnet/api/microsoft.aspnetcore.hosting.webhostbuilderkestrelextensions.usekestrel) overrides the default [Limits.MaxRequestBodySize](/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelserverlimits.maxrequestbodysize) of 30,000,000 bytes established when Kestrel was configured by `CreateDefaultBuilder`: @@ -101,7 +125,21 @@ The configuration defined by `CreateDefaultBuilder` can be overridden and augmen { options.Limits.MaxRequestBodySize = 20000000; }); - ... + ``` + +::: moniker-end + +::: moniker range="= aspnetcore-2.0" + +* The following call to [UseKestrel](/dotnet/api/microsoft.aspnetcore.hosting.webhostbuilderkestrelextensions.usekestrel) overrides the default [Limits.MaxRequestBodySize](/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelserverlimits.maxrequestbodysize) of 30,000,000 bytes established when Kestrel was configured by `CreateDefaultBuilder`: + + ```csharp + WebHost.CreateDefaultBuilder(args) + .UseKestrel(options => + { + options.Limits.MaxRequestBodySize = 20000000; + }) + .Build(); ``` ::: moniker-end @@ -119,22 +157,7 @@ For more information on app configuration, see - WebHost.CreateDefaultBuilder(args) - .UseStartup() - .Build(); -} -``` +Create a host using an instance of [WebHostBuilder](/dotnet/api/microsoft.aspnetcore.hosting.webhostbuilder). Creating a host is typically performed in the app's entry point, the `Main` method. `WebHostBuilder` requires a [server that implements IServer](xref:fundamentals/servers/index). The built-in servers are [Kestrel](xref:fundamentals/servers/kestrel) and [HTTP.sys](xref:fundamentals/servers/httpsys) (prior to the release of ASP.NET Core 2.0, HTTP.sys was called [WebListener](xref:fundamentals/servers/weblistener)). In this example, the [UseKestrel extension method](/dotnet/api/microsoft.aspnetcore.hosting.webhostbuilderkestrelextensions.usekestrel?view=aspnetcore-1.1) specifies the Kestrel server. @@ -545,7 +568,7 @@ var host = new WebHostBuilder() Use [Configuration](xref:fundamentals/configuration/index) to configure the web host. In the following example, host configuration is optionally specified in a *hostsettings.json* file. Any configuration loaded from the *hostsettings.json* file may be overridden by command-line arguments. The built configuration (in `config`) is used to configure the host with [UseConfiguration](/dotnet/api/microsoft.aspnetcore.hosting.hostingabstractionswebhostbuilderextensions.useconfiguration). `IWebHostBuilder` configuration is added to the app's configuration, but the converse isn't true—`ConfigureAppConfiguration` doesn't affect the `IWebHostBuilder` configuration. -::: moniker range=">= aspnetcore-2.0" +::: moniker range=">= aspnetcore-2.1" Overriding the configuration provided by `UseUrls` with *hostsettings.json* config first, command-line argument config second: @@ -558,6 +581,48 @@ public class Program } public static IWebHostBuilder CreateWebHostBuilder(string[] args) + { + var config = new ConfigurationBuilder() + .SetBasePath(Directory.GetCurrentDirectory()) + .AddJsonFile("hostsettings.json", optional: true) + .AddCommandLine(args) + .Build(); + + return WebHost.CreateDefaultBuilder(args) + .UseUrls("http://*:5000") + .UseConfiguration(config) + .Configure(app => + { + app.Run(context => + context.Response.WriteAsync("Hello, World!")); + }); + } +} +``` + +*hostsettings.json*: + +```json +{ + urls: "http://*:5005" +} +``` + +::: moniker-end + +::: moniker range="= aspnetcore-2.0" + +Overriding the configuration provided by `UseUrls` with *hostsettings.json* config first, command-line argument config second: + +```csharp +public class Program +{ + public static void Main(string[] args) + { + BuildWebHost(args).Run(); + } + + public static IWebHost BuildWebHost(string[] args) { var config = new ConfigurationBuilder() .SetBasePath(Directory.GetCurrentDirectory()) diff --git a/aspnetcore/fundamentals/servers/kestrel.md b/aspnetcore/fundamentals/servers/kestrel.md index aa27c43808ff..b4f95eff3ef0 100644 --- a/aspnetcore/fundamentals/servers/kestrel.md +++ b/aspnetcore/fundamentals/servers/kestrel.md @@ -4,7 +4,7 @@ author: rick-anderson description: Learn about Kestrel, the cross-platform web server for ASP.NET Core. ms.author: tdykstra ms.custom: mvc -ms.date: 09/13/2018 +ms.date: 10/27/2018 uid: fundamentals/servers/kestrel --- # Kestrel web server implementation in ASP.NET Core @@ -127,7 +127,23 @@ public static IWebHostBuilder CreateWebHostBuilder(string[] args) => ::: moniker-end -::: moniker range="= aspnetcore-2.0 || aspnetcore-2.1" +::: moniker range="= aspnetcore-2.1" + +To provide additional configuration after calling `CreateDefaultBuilder`, call [UseKestrel](/dotnet/api/microsoft.aspnetcore.hosting.webhostbuilderkestrelextensions.usekestrel): + +```csharp +public static IWebHostBuilder CreateWebHostBuilder(string[] args) => + WebHost.CreateDefaultBuilder(args) + .UseStartup() + .UseKestrel(options => + { + // Set properties and call methods on options + }); +``` + +::: moniker-end + +::: moniker range="= aspnetcore-2.0" To provide additional configuration after calling `CreateDefaultBuilder`, call [UseKestrel](/dotnet/api/microsoft.aspnetcore.hosting.webhostbuilderkestrelextensions.usekestrel): @@ -181,7 +197,7 @@ The maximum number of concurrent open TCP connections can be set for the entire ::: moniker-end -::: moniker range="= aspnetcore-2.0 || aspnetcore-2.1" +::: moniker range="= aspnetcore-2.1" ```csharp public static IWebHostBuilder CreateWebHostBuilder(string[] args) => @@ -195,6 +211,21 @@ public static IWebHostBuilder CreateWebHostBuilder(string[] args) => ::: moniker-end +::: moniker range="= aspnetcore-2.0" + +```csharp +public static IWebHost BuildWebHost(string[] args) => + WebHost.CreateDefaultBuilder(args) + .UseStartup() + .UseKestrel(options => + { + options.Limits.MaxConcurrentConnections = 100; + }) + .Build(); +``` + +::: moniker-end + There's a separate limit for connections that have been upgraded from HTTP or HTTPS to another protocol (for example, on a WebSockets request). After a connection is upgraded, it isn't counted against the `MaxConcurrentConnections` limit. ::: moniker range=">= aspnetcore-2.2" @@ -203,7 +234,7 @@ There's a separate limit for connections that have been upgraded from HTTP or HT ::: moniker-end -::: moniker range="= aspnetcore-2.0 || aspnetcore-2.1" +::: moniker range="= aspnetcore-2.1" ```csharp public static IWebHostBuilder CreateWebHostBuilder(string[] args) => @@ -217,6 +248,21 @@ public static IWebHostBuilder CreateWebHostBuilder(string[] args) => ::: moniker-end +::: moniker range="= aspnetcore-2.0" + +```csharp +public static IWebHost BuildWebHost(string[] args) => + WebHost.CreateDefaultBuilder(args) + .UseStartup() + .UseKestrel(options => + { + options.Limits.MaxConcurrentUpgradedConnections = 100; + }) + .Build(); +``` + +::: moniker-end + ::: moniker range=">= aspnetcore-2.0" The maximum number of connections is unlimited (null) by default. @@ -244,7 +290,7 @@ Here's an example that shows how to configure the constraint for the app on ever ::: moniker-end -::: moniker range="= aspnetcore-2.0 || aspnetcore-2.1" +::: moniker range="= aspnetcore-2.1" ```csharp public static IWebHostBuilder CreateWebHostBuilder(string[] args) => @@ -262,6 +308,25 @@ You can override the setting on a specific request in middleware: ::: moniker-end +::: moniker range="= aspnetcore-2.0" + +```csharp +public static IWebHost BuildWebHost(string[] args) => + WebHost.CreateDefaultBuilder(args) + .UseStartup() + .UseKestrel(options => + { + options.Limits.MaxRequestBodySize = 10 * 1024; + }) + .Build(); +``` + +You can override the setting on a specific request in middleware: + +[!code-csharp[](kestrel/samples/2.x/KestrelSample/Startup.cs?name=snippet_Limits&highlight=3-4)] + +::: moniker-end + ::: moniker range=">= aspnetcore-2.0" An exception is thrown if you attempt to configure the limit on a request after the app has started to read the request. There's an `IsReadOnly` property that indicates if the `MaxRequestBodySize` property is in read-only state, meaning it's too late to configure the limit. @@ -287,7 +352,7 @@ Here's an example that shows how to configure the minimum data rates in *Program ::: moniker-end -::: moniker range="= aspnetcore-2.0 || aspnetcore-2.1" +::: moniker range="= aspnetcore-2.1" ```csharp public static IWebHostBuilder CreateWebHostBuilder(string[] args) => @@ -302,6 +367,24 @@ public static IWebHostBuilder CreateWebHostBuilder(string[] args) => }); ``` +::: moniker-end + +::: moniker range="= aspnetcore-2.0" + +```csharp +public static IWebHost BuildWebHost(string[] args) => + WebHost.CreateDefaultBuilder(args) + .UseStartup() + .UseKestrel(options => + { + options.Limits.MinRequestBodyDataRate = + new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10)); + options.Limits.MinResponseDataRate = + new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10)); + }) + .Build(); +``` + You can configure the rates per request in middleware: [!code-csharp[](kestrel/samples/2.x/KestrelSample/Startup.cs?name=snippet_Limits&highlight=5-8)] @@ -653,7 +736,51 @@ public static IWebHostBuilder CreateWebHostBuilder(string[] args) => ::: moniker-end -::: moniker range="= aspnetcore-2.0 || aspnetcore-2.1" +::: moniker range="= aspnetcore-2.1" + +```csharp +public static IWebHostBuilder CreateWebHostBuilder(string[] args) => + WebHost.CreateDefaultBuilder(args) + .UseStartup() + .UseKestrel((context, options) => + { + options.ListenAnyIP(5005, listenOptions => + { + listenOptions.UseHttps(httpsOptions => + { + var localhostCert = CertificateLoader.LoadFromStoreCert( + "localhost", "My", StoreLocation.CurrentUser, + allowInvalid: true); + var exampleCert = CertificateLoader.LoadFromStoreCert( + "example.com", "My", StoreLocation.CurrentUser, + allowInvalid: true); + var subExampleCert = CertificateLoader.LoadFromStoreCert( + "sub.example.com", "My", StoreLocation.CurrentUser, + allowInvalid: true); + var certs = new Dictionary( + StringComparer.OrdinalIgnoreCase); + certs["localhost"] = localhostCert; + certs["example.com"] = exampleCert; + certs["sub.example.com"] = subExampleCert; + + httpsOptions.ServerCertificateSelector = (connectionContext, name) => + { + if (name != null && certs.TryGetValue(name, out var cert)) + { + return cert; + } + + return exampleCert; + }; + }); + }); + }) + .Build(); +``` + +::: moniker-end + +::: moniker range="= aspnetcore-2.0" ```csharp public static IWebHost BuildWebHost(string[] args) => @@ -707,7 +834,7 @@ The [Listen](/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelservero ::: moniker-end -::: moniker range="= aspnetcore-2.0 || aspnetcore-2.1" +::: moniker range="= aspnetcore-2.1" ```csharp public static void Main(string[] args) @@ -730,6 +857,77 @@ public static IWebHostBuilder CreateWebHostBuilder(string[] args) => ::: moniker-end +::: moniker range="= aspnetcore-2.0" + +```csharp +public static void Main(string[] args) +{ + BuildWebHost(args).Run(); +} + +public static IWebHost BuildWebHost(string[] args) => + WebHost.CreateDefaultBuilder(args) + .UseStartup() + .UseKestrel(options => + { + options.Listen(IPAddress.Loopback, 5000); + options.Listen(IPAddress.Loopback, 5001, listenOptions => + { + listenOptions.UseHttps("testCert.pfx", "testPassword"); + }); + }) + .Build(); +``` + +::: moniker-end + +::: moniker range="= aspnetcore-2.1" + +```csharp +public static void Main(string[] args) +{ + CreateWebHostBuilder(args).Build().Run(); +} + +public static IWebHostBuilder CreateWebHostBuilder(string[] args) => + WebHost.CreateDefaultBuilder(args) + .UseStartup() + .UseKestrel(options => + { + options.Listen(IPAddress.Loopback, 5000); + options.Listen(IPAddress.Loopback, 5001, listenOptions => + { + listenOptions.UseHttps("testCert.pfx", "testPassword"); + }); + }); +``` + +::: moniker-end + +::: moniker range="= aspnetcore-2.0" + +```csharp +public static void Main(string[] args) +{ + BuildWebHost(args).Run(); +} + +public static IWebHost BuildWebHost(string[] args) => + WebHost.CreateDefaultBuilder(args) + .UseStartup() + .UseKestrel(options => + { + options.Listen(IPAddress.Loopback, 5000); + options.Listen(IPAddress.Loopback, 5001, listenOptions => + { + listenOptions.UseHttps("testCert.pfx", "testPassword"); + }); + }) + .Build(); +``` + +::: moniker-end + ::: moniker range=">= aspnetcore-2.0" The example configures SSL for an endpoint with [ListenOptions](/dotnet/api/microsoft.aspnetcore.server.kestrel.core.listenoptions). Use the same API to configure other Kestrel settings for specific endpoints. @@ -748,7 +946,7 @@ Listen on a Unix socket with [ListenUnixSocket](/dotnet/api/microsoft.aspnetcore ::: moniker-end -::: moniker range="= aspnetcore-2.0 || aspnetcore-2.1" +::: moniker range="= aspnetcore-2.1" ```csharp public static IWebHostBuilder CreateWebHostBuilder(string[] args) => @@ -766,6 +964,25 @@ public static IWebHostBuilder CreateWebHostBuilder(string[] args) => ::: moniker-end +::: moniker range="= aspnetcore-2.0" + +```csharp +public static IWebHost BuildWebHost(string[] args) => + WebHost.CreateDefaultBuilder(args) + .UseStartup() + .UseKestrel(options => + { + options.ListenUnixSocket("/tmp/kestrel-test.sock"); + options.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions => + { + listenOptions.UseHttps("testCert.pfx", "testpassword"); + }); + }) + .Build(); +``` + +::: moniker-end + ::: moniker range=">= aspnetcore-2.0" ### Port 0 @@ -856,7 +1073,7 @@ public static IWebHostBuilder CreateWebHostBuilder(string[] args) => listenOptions.Protocols = HttpProtocols.Http1AndHttp2; listenOptions.UseHttps("testCert.pfx", "testPassword"); }); - } + }); ``` Optionally create an `IConnectionAdapter` implementation to filter TLS handshakes on a per-connection basis for specific ciphers: @@ -873,7 +1090,7 @@ public static IWebHostBuilder CreateWebHostBuilder(string[] args) => listenOptions.UseHttps("testCert.pfx", "testPassword"); listenOptions.ConnectionAdapters.Add(new TlsFilterAdapter()); }); - } + }); ``` ```csharp diff --git a/aspnetcore/host-and-deploy/iis/index.md b/aspnetcore/host-and-deploy/iis/index.md index 138a74bf8b0a..ebe5c58290f8 100644 --- a/aspnetcore/host-and-deploy/iis/index.md +++ b/aspnetcore/host-and-deploy/iis/index.md @@ -4,7 +4,7 @@ author: guardrex description: Learn how to host ASP.NET Core apps on Windows Server Internet Information Services (IIS). ms.author: riande ms.custom: mvc -ms.date: 09/21/2018 +ms.date: 10/27/2018 uid: host-and-deploy/iis/index --- # Host ASP.NET Core on Windows with IIS @@ -76,7 +76,7 @@ A typical *Program.cs* calls to begin setting up a host. For out-of-process hosting with IIS, `CreateDefaultBuilder` configures [Kestrel](xref:fundamentals/servers/kestrel) as the web server and enables IIS integration by configuring the base path and port for the [ASP.NET Core Module](xref:fundamentals/servers/aspnet-core-module): ```csharp -public static IWebHost BuildWebHost(string[] args) => +public static IWebHostBuilder CreateWebHostBuilder(string[] args) => WebHost.CreateDefaultBuilder(args) ... ``` @@ -98,7 +98,7 @@ For more information on the in-process and out-of-process hosting models, see th A typical *Program.cs* calls to begin setting up a host. `CreateDefaultBuilder` configures [Kestrel](xref:fundamentals/servers/kestrel) as the web server and enables IIS integration by configuring the base path and port for the [ASP.NET Core Module](xref:fundamentals/servers/aspnet-core-module): ```csharp -public static IWebHost BuildWebHost(string[] args) => +public static IWebHostBuilder CreateWebHostBuilder(string[] args) => WebHost.CreateDefaultBuilder(args) ... ``` diff --git a/aspnetcore/tutorials/getting-started-with-swashbuckle.md b/aspnetcore/tutorials/getting-started-with-swashbuckle.md index a6a5f77cec89..c67d26ee88f5 100644 --- a/aspnetcore/tutorials/getting-started-with-swashbuckle.md +++ b/aspnetcore/tutorials/getting-started-with-swashbuckle.md @@ -4,7 +4,7 @@ author: zuckerthoben description: Learn how to add Swashbuckle to your ASP.NET Core web API project to integrate the Swagger UI. ms.author: scaddie ms.custom: mvc -ms.date: 08/20/2018 +ms.date: 10/27/2018 uid: tutorials/get-started-with-swashbuckle --- # Get started with Swashbuckle and ASP.NET Core @@ -120,7 +120,7 @@ The Swagger UI displays the version's information: XML comments can be enabled with the following approaches: -# [Visual Studio](#tab/visual-studio-xml/) +# [Visual Studio](#tab/visual-studio) ::: moniker range=">= aspnetcore-2.0" @@ -138,7 +138,7 @@ XML comments can be enabled with the following approaches: ::: moniker-end -# [Visual Studio for Mac](#tab/visual-studio-mac-xml/) +# [Visual Studio for Mac](#tab/visual-studio-mac) ::: moniker range=">= aspnetcore-2.0" @@ -156,7 +156,7 @@ XML comments can be enabled with the following approaches: ::: moniker-end -# [Visual Studio Code](#tab/visual-studio-code-xml/) +# [Visual Studio Code](#tab/visual-studio-code) Manually add the highlighted lines to the *.csproj* file: @@ -196,6 +196,29 @@ To suppress warnings project-wide, define a semicolon-delimited list of warning To suppress warnings only for specific members, enclose the code in [#pragma warning](/dotnet/csharp/language-reference/preprocessor-directives/preprocessor-pragma-warning) preprocessor directives. This approach is useful for code that shouldn't be exposed via the API docs. In the following example, warning code CS1591 is ignored for the entire `Program` class. Enforcement of the warning code is restored at the close of the class definition. Specify multiple warning codes with a comma-delimited list. +::: moniker range=">= aspnetcore-2.1" + +```csharp +namespace TodoApi +{ +#pragma warning disable CS1591 + public class Program + { + public static void Main(string[] args) => + CreateWebHostBuilder(args).Build().Run(); + + public static IWebHostBuilder CreateWebHostBuilder(string[] args) => + WebHost.CreateDefaultBuilder(args) + .UseStartup(); + } +#pragma warning restore CS1591 +} +``` + +::: moniker-end + +::: moniker range="= aspnetcore-2.0" + ```csharp namespace TodoApi { @@ -214,6 +237,31 @@ namespace TodoApi } ``` +::: moniker-end + +::: moniker range="< aspnetcore-2.0" + +```csharp +namespace TodoApi +{ +#pragma warning disable CS1591 + public class Program + { + public static void Main(string[] args) + { + var host = new WebHostBuilder() + .UseKestrel() + .Build(); + + host.Run(); + } + } +#pragma warning restore CS1591 +} +``` + +::: moniker-end + Configure Swagger to use the generated XML file. For Linux or non-Windows operating systems, file names and paths can be case-sensitive. For example, a *TodoApi.XML* file is valid on Windows but not CentOS. ::: moniker range=">= aspnetcore-2.1"