HostBuilder.Build doc: mention lifetime

[yecril71pl]

Mention that the host application lifetime service will be added in addition to the services configured to be run.

[ghost]

Tagging subscribers to this area: @dotnet/area-extensions-hosting
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Mention that the host application lifetime service will be added in addition to the services configured to be run.

Author:	yecril71pl
Assignees:	-
Labels:	area-Extensions-Hosting, community-contribution
Milestone:	-

[eerhardt]

It adds other services as well, for example logging, configuration, etc. Why are the lifetime services special here?

If we want to list the services added here, I think it would be more appropriate to add them to a <remarks> section instead.

[yecril71pl]

Lifetime services are special because they prevent the application from quitting and you must explicitly ask the application to quit from client code, whereas all other services are used as needed and do not affect the main workflow. That is, when you tell the application to run as a background service, nothing tells you that it will run indefinitely and this is not what you, as a whatever-else programmer, would expect (a whatever-else programmer would expect an explicit call to EnterMainEventLoop or whatever). I tell you this as a whatever-else programmer. Surprise factor 90%.

[eerhardt]

The current worker template has the following code in Program.cs:

using WorkerService6;

IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddHostedService<Worker>();
    })
    .Build();

await host.RunAsync();

The equivalent place to EnterMainEventLoop is the last line: await host.RunAsync();. This is the place where your program will run indefinitely until something cancels it.

[yecril71pl]

Yes, and this is unexpected because the code in the Worker provides no indication of an infinite loop and the callback method in Worker is called only once. This is why it looks odd at the first encounter.

[eerhardt]

The template has a loop in it:

namespace WorkerService6
{
    public class Worker : BackgroundService
    {
        private readonly ILogger<Worker> _logger;

        public Worker(ILogger<Worker> logger)
        {
            _logger = logger;
        }

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            while (!stoppingToken.IsCancellationRequested)
            {
                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(1000, stoppingToken);
            }
        }
    }
}

The idea being that this background task loops until it is done with its work.

Check out https://docs.microsoft.com/en-us/dotnet/core/extensions/workers, which describes how all the pieces fit together.

[eerhardt]

I think it would be fine to add a general statement to the <remarks> section that said something like:

Adds basic services to the host such as application lifetime, host environment, and logging.

[yecril71pl]

The template has a loop in it:

I did not use the template because I did not know it exists; the documentation for BackgroundService does not mention it at all. Do you think it should? I just inherited from BackgroundService, implemented a straightforward procedure and was stupefied by the effect.

[eerhardt]

I think it would be reasonable for the documentation for BackgroundService to point to https://docs.microsoft.com/dotnet/core/extensions/workers.

@gewarren @IEvangelist - do we have any examples of the xml docs linking to the conceptual docs? Here's a case where I think it would be helpful.

[IEvangelist]

I'm not actually sure, but I do agree that would be helpful. Ideally, it would exclude the locale as you've done there. Checkout this grep.app search results.

[gewarren]

You can add a <related> tag like this, which adds a link under the See also heading in the docs.

[eerhardt]

This looks great @yecril71pl! Thanks for the contribution, and your patience with my nits.

I just had one small additional comment, and I think this will be ready to merge.

[yecril71pl]

This looks great @yecril71pl! Thanks for the contribution, and your patience with my nits.

I just had one small additional comment, and I think this will be ready to merge.

Thank you for helping me to understand how these things work. It all looks like black magic when you see it for the first time.

[eerhardt]

LGTM. Thanks again!

[gewarren]

This is incorrect, AFAIK. The <related> tag shouldn't have any surrounding text. If you want to have descriptive text like that, I think you need to use a <see href="url">text</see> within the summary or remarks.

[eerhardt]

Suggested change

	/// See <see href="https://docs.microsoft.com/dotnet/core/extensions/workers">Worker Services in .NET</see> for implementation guidelines.
	/// <related type="Article" href="/dotnet/core/extensions/workers">Worker Services in .NET</related>

To follow the example @gewarren linked to:

runtime/src/libraries/System.Private.CoreLib/src/System/Numerics/Vector2.cs

Line 691 in b2ab353

/// <related type="Article" href="/dotnet/standard/base-types/standard-numeric-format-strings">Standard Numeric Format Strings</related>

[yecril71pl]

But that is a bare reference, with no information why it is there. I would prefer to have it in context. Please confirm.

[gewarren]

If you decide to keep the <see> tag, you'll need to put the entire text within the summary or remarks tags.

[eerhardt]

The docs understand this format, and it makes it look like this:

https://docs.microsoft.com/en-us/dotnet/api/system.numerics.vector2.tostring?view=net-6.0#System_Numerics_Vector2_ToString_System_String_

[yecril71pl]

Yes, and that is for non-essential references, like when you can safely assume the reader already knows those things. This is not the case here.