Skip to content
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

Merged
merged 6 commits into from May 16, 2018
Merged

Host updates (Generic Host topic) #6428

merged 6 commits into from May 16, 2018

Conversation

guardrex
Copy link
Collaborator

@guardrex guardrex commented May 15, 2018

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:

  • Disregard the invalid cross reference(s) "fundamentals/metapackage-app" warning ... that topic will be landing shortly in the repo.
  • Generic Host sample is on -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.
  • I recommend and use "Web Host" and "Generic Host" as proper nouns throughout.
  • I (mostly) match the topic outline sections to the sample extension method calls in order of appearance. I think this layout composes well.
  • I'm a tad concerned on IHost StopAsync versus the same method on HostingAbstractionsHostExtensions. The Manage the host section deserves careful scrutiny on API references and the examples used.
  • I'm not entirely happy with the way the original Hosting topic (now Web Host) handles the "external control" example. I'm not sweating reorganizing the content on it in the Web Host topic here; however, I am trying to fix it in the new Generic Host topic to take us forward: I prefer to split that out into its own subsection, so that's what I do here. Let's see if it works.
  • This PR moves the background tasks topic (hosted-services.md) to this new host node. We'll update that topic and add a Generic Host sample (which I already have in-hand) on Update hosted service topic #3352 immediately after we merge this.
  • Finally, I need to add a note WRT running the sample in an external console or internal terminal. Trying to run the sample in VSC in the internal console leads to a 💥 😢. I'll do that on an upcoming commit.

Add sample

Updates

Updates

Updates

Updates

Updates

Generic Host topic + Host TOC area updates

Drop gitignore

Drop gitignore

.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.
Copy link
Member

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 Core capabilities

[!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.
Copy link
Member

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).
Copy link
Member

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?

Copy link
Member

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&lt;IConfigurationBuilder&gt;)](/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*:
Copy link
Member

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.
Copy link
Member

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.

Copy link
Collaborator Author

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. :trollface: 😄 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.
Copy link
Member

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and calls StopAsync

Copy link
Member

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):
Copy link
Member

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):
Copy link
Member

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();
Copy link
Member

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));
}

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@guardrex
Copy link
Collaborator Author

@Tratcher Ok ... see how that looks.

I didn't remove the AddConfiguration bits; however, I did add back the GH issue link and note as we have over the Web Host topic. I think if that's a scenario that's tripping up a lot of devs that it should remain. Your call.


[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.
Copy link
Member

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.

Copy link
Collaborator Author

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?

@Tratcher
Copy link
Member

StopAsync(TimeSpan) looks best. No need to distinguish between first class and extension methods here.

@guardrex guardrex requested a review from scottaddie May 16, 2018 16:11
@guardrex
Copy link
Collaborator Author

FYI: No need to rebase for ...

Line : [Warning] 1 invalid cross reference(s) "fundamentals/metapackage-app". 

... it's on master now ... https://github.com/aspnet/Docs/blob/master/aspnetcore/fundamentals/metapackage-app.md

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
Copy link
Member

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&lt;TContainerBuilder&gt;)](/dotnet/api/microsoft.extensions.hosting.hostbuilder.useserviceproviderfactory) overrides the default factory used to create the app's service provider.
Copy link
Member

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).

Copy link
Collaborator Author

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" />
Copy link
Member

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.

Copy link
Collaborator Author

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
Copy link
Member

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) &ndash; Suitable for hosting web apps.
Copy link
Member

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.

Copy link
Collaborator Author

@guardrex guardrex May 16, 2018

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) &ndash; Suitable for hosting web apps.
* [Generic Host](xref:fundamentals/host/generic-host) (ASP.NET Core 2.1 or later) &ndash; 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.
Copy link
Member

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
Copy link
Member

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
Copy link
Member

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).
Copy link
Member

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".

@guardrex
Copy link
Collaborator Author

guardrex commented May 16, 2018

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.

  1. Web Host – Suitable for hosting web apps.
  2. Web Host–Suitable for hosting web apps.
  3. Web Host Suitable for hosting web apps.
  4. Web Host: Suitable for hosting web apps.

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 ...

  • We have about two dozen other spots to fix up. I'll put in a quick PR to patch them up with whatever you cats decide.
  • We should inform @mairaw on her repo's use of spaces with dashes (hundreds of times) in case she wants to match whatever decision is made over here.

cc/ @Rick-Anderson @rachelappel

@scottaddie
Copy link
Member

@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.

@guardrex
Copy link
Collaborator Author

Yeah ... I think they just didn't consider it. Their blanket rule seems to indicate that they were thinking 100% inline usages.

@guardrex guardrex merged commit 7c30c9b into master May 16, 2018
@guardrex guardrex deleted the guardrex/hosting-updates branch May 16, 2018 21:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Hosting non-server apps with Generic Host
3 participants