|
| 1 | +### Kestrel: Configuration changes at run time detected by default |
| 2 | + |
| 3 | +Kestrel now reacts to changes made to the `Kestrel` section of the project's `IConfiguration` instance (for example, *appsettings.json*) at run time. To learn more about how to configure Kestrel using *appsettings.json*, see the *appsettings.json* example in [Endpoint configuration](/aspnet/core/fundamentals/servers/kestrel#endpoint-configuration). |
| 4 | + |
| 5 | +Kestrel will bind, unbind, and rebind endpoints as necessary to react to these configuration changes. |
| 6 | + |
| 7 | +For discussion, see issue [dotnet/aspnetcore#22807](https://github.com/dotnet/aspnetcore/issues/22807). |
| 8 | + |
| 9 | +#### Version introduced |
| 10 | + |
| 11 | +5.0 Preview 7 |
| 12 | + |
| 13 | +#### Old behavior |
| 14 | + |
| 15 | +Before ASP.NET Core 5.0 Preview 6, Kestrel didn't support changing configuration at run time. |
| 16 | + |
| 17 | +In ASP.NET Core 5.0 Preview 6, you could opt into the now-default behavior of reacting to configuration changes at run time. Opting in required binding Kestrel's configuration manually: |
| 18 | + |
| 19 | +```csharp |
| 20 | +using Microsoft.AspNetCore.Hosting; |
| 21 | +using Microsoft.Extensions.Hosting; |
| 22 | + |
| 23 | +public class Program |
| 24 | +{ |
| 25 | + public static void Main(string[] args) => |
| 26 | + CreateHostBuilder(args).Build().Run(); |
| 27 | + |
| 28 | + public static IHostBuilder CreateHostBuilder(string[] args) => |
| 29 | + Host.CreateDefaultBuilder(args) |
| 30 | + .ConfigureWebHostDefaults(webBuilder => |
| 31 | + { |
| 32 | + webBuilder.UseKestrel((builderContext, kestrelOptions) => |
| 33 | + { |
| 34 | + kestrelOptions.Configure( |
| 35 | + builderContext.Configuration.GetSection("Kestrel"), reloadOnChange: true); |
| 36 | + }); |
| 37 | + |
| 38 | + webBuilder.UseStartup<Startup>(); |
| 39 | + }); |
| 40 | +} |
| 41 | +``` |
| 42 | + |
| 43 | +#### New behavior |
| 44 | + |
| 45 | +Kestrel reacts to configuration changes at run time by default. To support that change, <xref:Microsoft.Extensions.Hosting.GenericHostBuilderExtensions.ConfigureWebHostDefaults%2A> calls `KestrelServerOptions.Configure(IConfiguration, bool)` with `reloadOnChange: true` by default. |
| 46 | + |
| 47 | +#### Reason for change |
| 48 | + |
| 49 | +The change was made to support endpoint reconfiguration at run time without completely restarting the server. Unlike with a full server restart, unchanged endpoints aren't unbound even temporarily. |
| 50 | + |
| 51 | +#### Recommended action |
| 52 | + |
| 53 | +* For most scenarios in which Kestrel's default configuration section doesn't change at run time, this change has no impact and no action is needed. |
| 54 | +* For scenarios in which Kestrel's default configuration section does change at run time and Kestrel should react to it, this is now the default behavior. |
| 55 | +* For scenarios in which Kestrel's default configuration section changes at run time and Kestrel shouldn't react to it, you can opt out as follows: |
| 56 | + |
| 57 | + ```csharp |
| 58 | + using Microsoft.AspNetCore.Hosting; |
| 59 | + using Microsoft.Extensions.Hosting; |
| 60 | + |
| 61 | + public class Program |
| 62 | + { |
| 63 | + public static void Main(string[] args) => |
| 64 | + CreateHostBuilder(args).Build().Run(); |
| 65 | + |
| 66 | + public static IHostBuilder CreateHostBuilder(string[] args) => |
| 67 | + Host.CreateDefaultBuilder(args) |
| 68 | + .ConfigureWebHostDefaults(webBuilder => |
| 69 | + { |
| 70 | + webBuilder.UseKestrel((builderContext, kestrelOptions) => |
| 71 | + { |
| 72 | + kestrelOptions.Configure( |
| 73 | + builderContext.Configuration.GetSection("Kestrel"), reloadOnChange: false); |
| 74 | + }); |
| 75 | + |
| 76 | + webBuilder.UseStartup<Startup>(); |
| 77 | + }); |
| 78 | + } |
| 79 | + ``` |
| 80 | + |
| 81 | +**Notes:** |
| 82 | + |
| 83 | +This change doesn't modify the behavior of the `KestrelServerOptions.Configure(IConfiguration)` overload, which still defaults to the `reloadOnChange: false` behavior. |
| 84 | + |
| 85 | +It's also important to make sure the configuration source supports reloading. For JSON sources, reloading is configured by calling `AddJsonFile(path, reloadOnChange: true)`. Reloading is already configured by default for *appsettings.json* and *appsettings.{Environment}.json*. |
| 86 | + |
| 87 | +#### Category |
| 88 | + |
| 89 | +ASP.NET Core |
| 90 | + |
| 91 | +#### Affected APIs |
| 92 | + |
| 93 | +<xref:Microsoft.Extensions.Hosting.GenericHostBuilderExtensions.ConfigureWebHostDefaults%2A?displayProperty=nameWithType> |
| 94 | + |
| 95 | +<!-- |
| 96 | + |
| 97 | +#### Affected APIs |
| 98 | + |
| 99 | +`Overload:Microsoft.Extensions.Hosting.GenericHostBuilderExtensions.ConfigureWebHostDefaults` |
| 100 | + |
| 101 | +--> |
0 commit comments