New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Host updates (Generic Host topic) #6428
Conversation
Add sample Updates Updates Updates Updates Updates Generic Host topic + Host TOC area updates Drop gitignore Drop gitignore
75ad359
to
0e1157c
Compare
|
||
.NET apps configure and launch a *host*. The host is responsible for app startup and lifetime management. This topic covers the ASP.NET Core Generic Host ([HostBuilder](/dotnet/api/microsoft.extensions.hosting.hostbuilder)), which is useful for hosting apps that don't process HTTP requests. For coverage of the Web Host ([WebHostBuilder](/dotnet/api/microsoft.aspnetcore.hosting.webhostbuilder)), see the [Web Host](xref:fundamentals/host/web-host) topic. | ||
|
||
The goal of the Generic Host is to decouple the HTTP pipeline from the Web Host API to enable a wider array of host scenarios for ASP.NET Core. Messaging, background tasks, and other non-HTTP workloads based on the Generic Host benefit from cross-cutting ASP.NET Core capabilities, such as configuration, dependency injection, and logging. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
to enable a wider array of host scenarios
for ASP.NET Core.
benefit from cross-cutting
ASP.NET Corecapabilities
[!code-csharp[](generic-host/samples-snapshot/2.x/GenericHostSample/Program.cs?name=snippet_ConfigureHostConfiguration)] | ||
|
||
> [!NOTE] | ||
> The [AddConfiguration](/dotnet/api/microsoft.extensions.configuration.chainedbuilderextensions.addconfiguration) extension method isn't currently capable of parsing a configuration section returned by [GetSection](/dotnet/api/microsoft.extensions.configuration.iconfiguration.getsection) (for example, `.AddConfiguration(Configuration.GetSection("section"))`. The `GetSection` method filters the configuration keys to the section requested but leaves the section name on the keys (for example, `section:environment`). The `AddConfiguration` method expects the keys to match the `HostBuilder` keys (for example, `environment`). The presence of the section name on the keys prevents the section's values from configuring the host. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's a curiously specific note for something you're not showing in the sample. Is there at least an issue link you can include?
|
||
## ConfigureAppConfiguration | ||
|
||
App builder configuration is created by calling [ConfigureAppConfiguration(Action<IConfigurationBuilder>)](/dotnet/api/microsoft.extensions.hosting.ihostbuilder.configureappconfiguration) on the [IHostBuilder](/dotnet/api/microsoft.extensions.hosting.ihostbuilder) implementation. `ConfigureAppConfiguration` uses an [IConfigurationBuilder](/dotnet/api/microsoft.extensions.configuration.iconfigurationbuilder) to create an [IConfiguration](/dotnet/api/microsoft.extensions.configuration.iconfiguration) for the app. `ConfigureAppConfiguration` can be called multiple times with additive results. The app uses whichever option sets a value last. The configuration created by `ConfigureAppConfiguration` is available at [Configuration](/dotnet/api/microsoft.extensions.hosting.hostbuildercontext.configuration) for subsequent operations and in [Services](/dotnet/api/microsoft.extensions.hosting.ihost.services). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Show ConfigureAppConfiguration(Action<HostBuilderContext, IConfigurationBuilder> configureDelegate);
instead, or both?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
is available at [HostBuilderContext.Configuration]
|
||
App builder configuration is created by calling [ConfigureAppConfiguration(Action<IConfigurationBuilder>)](/dotnet/api/microsoft.extensions.hosting.ihostbuilder.configureappconfiguration) on the [IHostBuilder](/dotnet/api/microsoft.extensions.hosting.ihostbuilder) implementation. `ConfigureAppConfiguration` uses an [IConfigurationBuilder](/dotnet/api/microsoft.extensions.configuration.iconfigurationbuilder) to create an [IConfiguration](/dotnet/api/microsoft.extensions.configuration.iconfiguration) for the app. `ConfigureAppConfiguration` can be called multiple times with additive results. The app uses whichever option sets a value last. The configuration created by `ConfigureAppConfiguration` is available at [Configuration](/dotnet/api/microsoft.extensions.hosting.hostbuildercontext.configuration) for subsequent operations and in [Services](/dotnet/api/microsoft.extensions.hosting.ihost.services). | ||
|
||
*appsettings.json*: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Move the json samples after the C# sample, they're ancillary.
[!code-csharp[](generic-host/samples-snapshot/2.x/GenericHostSample/Program.cs?name=snippet_ConfigureAppConfiguration)] | ||
|
||
> [!NOTE] | ||
> The [AddConfiguration](/dotnet/api/microsoft.extensions.configuration.chainedbuilderextensions.addconfiguration) extension method isn't currently capable of parsing a configuration section returned by [GetSection](/dotnet/api/microsoft.extensions.configuration.iconfiguration.getsection) (for example, `.AddConfiguration(Configuration.GetSection("section"))`. The `GetSection` method filters the configuration keys to the section requested but leaves the section name on the keys (for example, `section:Logging:LogLevel:Default`). The `AddConfiguration` method expects an exact match to configuration keys (for example, `Logging:LogLevel:Default`). The presence of the section name on the keys prevents the section's values from configuring the app. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, not sure why this note is here when you don't show the AddConfiguration or GetSection APIs.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I used to show it in the sample ... until you killed it. 😄 lol
IIRC it was originally added to the hosting topic because devs were getting into trouble. Apparently, it's somewhat common to want to nest these config settings in the file and parse the sections out. I'll add back the link to the issue.
This issue will be addressed in an upcoming release. For more information and workarounds, see [Passing configuration section into WebHostBuilder.UseConfiguration uses full keys](aspnet/Hosting#839).
Do you want to remove it (here only, or in both spots)?
|
||
### Start and StopAsync | ||
|
||
[Start(IHost)](/dotnet/api/microsoft.extensions.hosting.hostingabstractionshostextensions.start) starts the host synchronously. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Start()
StopAsync(TimeSpan)
|
||
### WaitForShutdownAsync | ||
|
||
[WaitForShutdownAsync(IHost, CancellationToken)](/dotnet/api/microsoft.extensions.hosting.hostingabstractionshostextensions.waitforshutdownasync) returns a `Task` that completes when shutdown is triggered via the given token. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
and calls StopAsync
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
WaitForShutdownAsync(CancellationToken = default)
You don't show optional tokens in the other APIs like StartAsync and StopAsync. Pick one and be consistent.
|
||
### WaitForShutdown | ||
|
||
[WaitForShutdown(IHost)](/dotnet/api/microsoft.extensions.hosting.hostingabstractionshostextensions.waitforshutdown) blocks the calling thread until a shutdown is triggered (`Ctrl+C`/SIGINT or SIGTERM is issued): |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
triggered via the IHostLifetime such as ConsoleLifetime which listens for CTL+C etc.. Calls StopAsync.
|
||
### WaitForShutdown | ||
|
||
[WaitForShutdown(IHost)](/dotnet/api/microsoft.extensions.hosting.hostingabstractionshostextensions.waitforshutdown) blocks the calling thread until a shutdown is triggered (`Ctrl+C`/SIGINT or SIGTERM is issued): |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
WaitForShutdown()
public async Task StopAsync() | ||
{ | ||
await _host.StopAsync(TimeSpan.FromSeconds(5)); | ||
_host.Dispose(); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
using (_host)
{
await _host.StopAsync(TimeSpan.FromSeconds(5));
}
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@Tratcher Ok ... see how that looks. I didn't remove the |
|
||
[StopAsync(IHost, TimeSpan)](/dotnet/api/microsoft.extensions.hosting.hostingabstractionshostextensions.stopasync) attempts to stop the host within the provided timeout. | ||
[StopAsync](/dotnet/api/microsoft.extensions.hosting.hostingabstractionshostextensions.stopasync) attempts to stop the host within the provided timeout. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This one is ambiguous now, there are two StopAsyncs with different params.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is it better to use StopAsync(TimeSpan)
or HostingAbstractionsHostExtensions.StopAsync
?
Is it better to use IHost.StopAsync
in the spots where the extension for IHost
is referenced?
|
FYI: No need to rebase for ...
... it's on |
description: Learn about the Generic Host in .NET, which is responsible for app startup and lifetime management. | ||
manager: wpickett | ||
ms.author: riande | ||
ms.date: 05/14/2018 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please add the following metadata:
ms.custom: mvc
Also, is this doc only applicable to ASP.NET Core 2.1+? If so, add the metadata for that too.
|
||
## Container configuration | ||
|
||
To support plugging in other containers, the host can accept an [IServiceProviderFactory](/dotnet/api/microsoft.extensions.dependencyinjection.iserviceproviderfactory-1). Providing a factory isn't part of the DI container registration but is instead a host intrinsic used to create the concrete DI container. [UseServiceProviderFactory(IServiceProviderFactory<TContainerBuilder>)](/dotnet/api/microsoft.extensions.hosting.hostbuilder.useserviceproviderfactory) overrides the default factory used to create the app's service provider. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Don't assume the reader knows what DI represents. Spell it out on the first use: Dependency Injection (DI).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll do it on first mention ... Line 21.
<configuration> | ||
<packageSources> | ||
<clear /> | ||
<add key="dotnet-core" value="https://dotnet.myget.org/F/dotnet-core/api/v3/index.json" /> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Create an issue, if you haven't already, to remove the MyGet package source once the associated packages are published to NuGet.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Already done 👍 It's listed in the sample tracking issue for 2.1 updates. #5495
description: Learn about the ASP.NET Core Web Host and .NET Generic Host, which are responsible for app startup and lifetime management. | ||
manager: wpickett | ||
ms.author: riande | ||
ms.date: 05/14/2018 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Add the following metadata:
ms.custom: mvc
|
||
.NET apps configure and launch a *host*. The host is responsible for app startup and lifetime management. Two host APIs are available for use: | ||
|
||
* [Web Host](xref:fundamentals/host/web-host) – Suitable for hosting web apps. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Per the style guide, don't use spaces on either side of an en dash.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
See comment at the bottom 👇.
.NET apps configure and launch a *host*. The host is responsible for app startup and lifetime management. Two host APIs are available for use: | ||
|
||
* [Web Host](xref:fundamentals/host/web-host) – Suitable for hosting web apps. | ||
* [Generic Host](xref:fundamentals/host/generic-host) (ASP.NET Core 2.1 or later) – Suitable for hosting non-web apps (for example, apps that run background tasks). In a future release, the Generic Host will be suitable for hosting any kind of app, including web apps. The Generic Host will eventually replace the Web Host. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Per the style guide, don't use spaces on either side of an en dash.
author: guardrex | ||
description: Learn about the web host in ASP.NET Core, which is responsible for app startup and lifetime management. | ||
manager: wpickett | ||
ms.author: riande | ||
ms.date: 09/21/2017 | ||
ms.date: 05/14/2018 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Add the following metadata:
ms.custom: mvc
|
||
By [Luke Latham](https://github.com/guardrex) | ||
|
||
ASP.NET Core apps configure and launch a *host*. The host is responsible for app startup and lifetime management. At a minimum, the host configures a server and a request processing pipeline. | ||
ASP.NET Core apps configure and launch a *host*. The host is responsible for app startup and lifetime management. At a minimum, the host configures a server and a request processing pipeline. This topic covers the ASP.NET Core Web Host ([WebHostBuilder](/dotnet/api/microsoft.aspnetcore.hosting.webhostbuilder)), which is useful for hosting web apps. For coverage of the .NET Generic Host ([HostBuilder](/dotnet/api/microsoft.extensions.hosting.hostbuilder)), see the [Generic Host](xref:fundamentals/host/generic-host) topic. | ||
|
||
## Setting up a host |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Setting --> Set
@@ -79,7 +79,7 @@ There are also [Http.Sys registry settings](https://support.microsoft.com/kb/820 | |||
|
|||
* Configure URLs and ports to listen on | |||
|
|||
By default ASP.NET Core binds to `http://localhost:5000`. To configure URL prefixes and ports, you can use the `UseURLs` extension method, the `urls` command-line argument or the ASP.NET Core configuration system. For more information, see [Hosting](../../fundamentals/hosting.md). | |||
By default ASP.NET Core binds to `http://localhost:5000`. To configure URL prefixes and ports, you can use the `UseURLs` extension method, the `urls` command-line argument or the ASP.NET Core configuration system. For more information, see [Host in ASP.NET Core(xref:fundamentals/host/index). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Add a comma after "By default".
ty @scottaddie This one went fairly well. 😄 We just need to resolve what we're going to do about definition dashes. The style manual doesn't explicitly address their use in definition lines.
My recommendation is for en dash with spaces (Example 1) ... looks much nicer imo. If you decide to go without spaces or use some other format for definitions ...
|
@guardrex Personally, I think the en dash with spaces looks nicer. Let's roll with that, and we can always address this later. I'd hate for something as minor as that to hold up publishing. |
Yeah ... I think they just didn't consider it. Their blanket rule seems to indicate that they were thinking 100% inline usages. |
Fixes #5798
Internal Review Topic (Host landing)
Internal Review Topic (Web Host)
Internal Review Topic (Generic Host)
Should be enough here to get me 🔫, 🔪, and 🥊 ... in that order. The 🚑 is standing by.
Notes:
invalid cross reference(s) "fundamentals/metapackage-app"
warning ... that topic will be landing shortly in the repo.-rtm-
packages until RTM. I've added this sample to the 2.1 sample update tracking issue (Sample Update Tracking Issue - complete list #5495) to make sure the work is done.IHost
StopAsync
versus the same method onHostingAbstractionsHostExtensions
. The Manage the host section deserves careful scrutiny on API references and the examples used.