[API Proposal]: Add `IHostedLifecycleService` to support additional callbacks

[steveharter]

Background and motivation

In order to support scenarios that need hook points before and after IHostedService.StartAsync() and StopAsync(), this proposal adds a new interface IHostedLifecycleService with these hooks points. It derives from IHostedService and is not injected separately from IHostedService.

This interface is located in the Microsoft.Extensions.Hosting.Abstractions assembly which will be supported by the default host (in the Microsoft.Extensions.Hosting assembly). Other hosts will need to implement IHostedService in order to support this new interface.

See also:

• [API Proposal]: Decouple ValidateOnStart from Hosting #84347
• DI : add support to eager load a singleton service #43149

API Proposal

These located in the Microsoft.Extensions.Hosting.Abstractions assembly.

namespace Microsoft.Extensions.Hosting
{
+    public interface IHostedLifecycleService : IHostedService
+    {
+        // These are awaited before 'IHostedService.StartAsync()' are run.
+        Task StartingAsync(CancellationToken cancellationToken);

+        // These are awaited after 'IHostedService.StartAsync()' are run.
+        Task StartedAsync(CancellationToken cancellationToken);

+        // These are awaited before 'IHostedService.StopAsync()' are run.
+        Task StoppingAsync(CancellationToken cancellationToken);

+        // These are awaited after 'IHostedService.StopAsync()' is run.
+        Task StoppedAsync(CancellationToken cancellationToken);
+    }
}

These located in the Microsoft.Extensions.Hosting assembly:

namespace Microsoft.Extensions.Hosting
{
    public class HostOptions
    {
        // Similar to ShutdownTimeout used in Host.StopAsync(), this creates a CancellationToken with the timeout.
        // Applies to Host.StartAsync() encompassing IHostedLifecycleService.StartingAsync(), IHostedService.StartAsync()
        // and IHostedLifecycleService.StartedAsync().
        // The timeout is off by default, unlike ShutdownTimeout which is 30 seconds.
        // This avoids a breaking change since existing implementations of IHostedService.StartAsync() are included in the timeout.
+       public TimeSpan StartupTimeout { get; set; } = Timeout.InfiniteTimeSpan;
    }
}

API Usage

IHostBuilder hostBuilder = new HostBuilder();
hostBuilder.ConfigureServices(services =>
{
    services.AddHostedService<MyService>();
}

using (IHost host = hostBuilder.Build())
{
    await host.StartAsync();
}

public class MyService : IHostedLifecycleService
{
    public Task StartingAsync(CancellationToken cancellationToken) => /* add logic here */ Task.CompletedTask;
    public Task StartAsync(CancellationToken cancellationToken) => /* add logic here */ Task.CompletedTask;
    public Task StartedAsync(CancellationToken cancellationToken) => /* add logic here */ Task.CompletedTask;
    public Task StopAsync(CancellationToken cancellationToken) => /* add logic here */ Task.CompletedTask;
    public Task StoppedAsync(CancellationToken cancellationToken) => /* add logic here */ Task.CompletedTask;
    public Task StoppingAsync(CancellationToken cancellationToken) => /* add logic here */ Task.CompletedTask;
}

Design notes

• The intent is that the new callbacks are cooperative amongst users and only used for services such as validation and warm-up scenarios that need to occur before\after the existing IHostedService.StartAsync() and IHostedService.StopAsync().

Ordering

The existing IHostApplicationLifetime which can be used for essentially the same hook points for "Started", "Stopping" and "Stopped" (but not "Starting") although those run serially and do not support an async, Task-based model. The new hook points contain more local semantics and thus are run before the corresponding IHostApplicationLifetime ones which are more "global" and may want to post-process any changes made. The IHostLifetime callbacks always come first\last.

The full lifecycle:

• IHostLifetime.WaitForStartAsync
• IHostedLifecycleService.StartingAsync
• IHostedService.Start
• IHostedLifecycleService.StartedAsync
• IHostApplicationLifetime.ApplicationStarted
• IHostedLifecycleService.StoppingAsync
• IHostApplicationLifetime.ApplicationStopping
• IHostedService.Stop
• IHostedLifecycleService.StoppedAsync
• IHostApplicationLifetime.ApplicationStopped
• IHostLifetime.StopAsync

Exceptions and guarantees

Exception semantics are basically the same: exceptions from callbacks are caught, and when all callbacks are called, the exception(s) are logged and re-thrown.

All callbacks are guaranteed to be called (minus special cases in shutdown). For backwards compat, this means that for the default host at least, once start is called, all handlers for starting, start and stopped will be called even if an exception occurs in one of the earlier phases. The same applies for stop.

The above semantics do not hold for exception thrown from IHostApplicationLifetime callbacks which log but do not re-throw.

Threading

The newer options HostOptions.ServicesStartConcurrently and HostOptions.ServicesStopConcurrently added in V8 support an opt-in for a concurrent mode which runs both the StartAsync and StopAsync callbacks concurrently plus the new callbacks. When the newer concurrent mode is not enabled, the callbacks run serially.

When the concurrent mode is enabled:

• A given hook point, such as a IHostedLifecycleService.StartingAsync(), runs serially with other IHostedLifecycleService.StartingAsync() implementations in the order of registration until an await occurs, if any (or in general, an uncompleted Task is returned). At that point, all such async callbacks are run concurrently. This is to optimize performance since many hook point will return Task.CompletedTask if the implementation is a noop. This also allows the author more control over the ordering and semantics of additional async calls.
• The StartAsync and\or StopAsync will change to the same optimized serial+concurrent model as explained above for the new callbacks**. Currently StartAsync\StopAsync do not have the "serial" portion and thus run concurrently even for synchronous methods. Changing this is feasible because the main reason for this new V8 feature was to avoid timeouts during a long shutdown, such as when the host needs to drain requests, and that logic should be async already.

Timeouts

• The new timeout will be off by default to avoid a breaking change for existing uses of StartAsync() especially in cases where StartAsync() is the actual long-running service logic.
  • The timeout is intended to help diagnose startup issues.
• The existing timeout for stop is 30 seconds in the default host and 5 seconds with ASP.NET although that is expected to change to 30 for consistency.

Alternative Designs

An optional feature for ease-of-use for adding a simple callback via func\delegate (instead of overriding all 6 methods when only 1 is needed) was prototyped but no longer considered for v8 because it would have inconsistent and potentially confusing concurrency, exception and ordering semantics that are different from implementing IHostedLifecycleService directly.

The implementation would likely use a single instance of IHostedLifecycleService with a chained delegate for each callback type (starting, started, stopping, stopped and potentially start+stop) with the semantics differing from using an implementation of IHostedLifecycleService:

• Async but running in series (instead of concurrent for callbacks that aren't all sync)
• The first exception will prevent subsequent delegates from being called (instead of guaranteeing each callback is called for a given method)
• Ordering is relative to other implementations of IHostedLifecycleService by the first call to add any delegate and not the individual order (a "builder" pattern would be useful to communicate that).

To get consistent semantics with direct IHostedLifecycleService implementations requires new public APIs so the host can know about this pattern -- the prototype simply used the abstractions assembly, and the hosting assembly was unaware of this.

E.g.

// For consistency with other IServiceCollection extensions, use the DependencyInjection namspace
namespace Microsoft.Extensions.DependencyInjection
{
    public static class ServiceCollectionHostedServiceExtensions
    {
        // Helper callbacks specifying a delegate for ease-of-use:

+       public static IServiceCollection AddServiceStarting(
+           this IServiceCollection services,
+           System.Func<IServiceProvider, CancellationToken, Task> startingFunc);

+       public static IServiceCollection AddServiceStart(
+           this IServiceCollection services,
+           System.Func<IServiceProvider, CancellationToken, Task> startingFunc);

+       public static IServiceCollection AddServiceStarted(
+           this IServiceCollection services,
+           System.Func<IServiceProvider, CancellationToken, Task> startedFunc);

+       public static IServiceCollection AddServiceStopping(
+           this IServiceCollection services,
+           System.Func<IServiceProvider, CancellationToken, Task> stoppingFunc);

+       public static IServiceCollection AddServiceStop(
+           this IServiceCollection services,
+           System.Func<IServiceProvider, CancellationToken, Task> startingFunc);

+       public static IServiceCollection AddServiceStopped(
+           this IServiceCollection services,
+           System.Func<IServiceProvider, CancellationToken, Task> stoppedFunc);
    }
}

Risks

No response

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

Issue Details

---

Background and motivation

In order to support scenarios that need a hook point when starting a Host, this is cumbersome today and only supports the hosting model. This proposal:

• Adds a new interface IServiceStartup with a single StartupAsync() method.
  • This is located in the Microsoft.Extensions.DependencyInjection.Abstractions assembly to allow it to be used outside of hosting.
• This interface will be implemented in the default host and called before other services that implement IHostedService.StartAsync(). Other hosts or layering on top of DI would also do this in order to support it.
• Since there is no "EndAsync" method this is more performant than using IHostedService which has both StartAsync and StopAsync.

See also:

• [API Proposal]: Decouple ValidateOnStart from Hosting #84347
• DI : add support to eager load a singleton service #43149
• R9's StartupHostedService

A prototype is located here where the unit tests verify a similar R9 callback approach and also verify that the validation effort done in V6 could be implemented with this.

API Proposal

namespace Microsoft.Extensions.DependencyInjection;

public partial interface IServiceStartup
{
    System.Threading.Tasks.Task StartupAsync(System.Threading.CancellationToken cancellationToken);
}

API Usage

See the referenced prototype above.

Alternative Designs

No response

Risks

No response

Author:	steveharter
Assignees:	steveharter
Labels:	api-suggestion, area-Extensions-DependencyInjection
Milestone:	8.0.0

[ericstj]

cc @tekian @geeknoid @davidfowl @eerhardt @rafal-mz

[rafal-mz]

I think it would be useful to have some top-level built in timeout. Somebody could implement this interface as something that does not return, and then the server would stuck without any diagnostic about the reason.

[steveharter]

I think it would be useful to have some top-level built in timeout. Somebody could implement this interface as something that does not return, and then the server would stuck without any diagnostic about the reason.

An implementation of StartupAsync() that wraps a list of callbacks could of course add their own timeout around the whole thing. For example, if we add "builder" APIs for this where we have just one instance of IStartupAsync, that makes it possible to add several callbacks to that instance which then could have its own timeout across all of them.

It looks like the existing host implementation has the same issue with the implementation not returning (i.e. no timeout). If so, then I don't think we would want to add one just the new startup services. Perhaps for both IServiceStartup.StartupAsync and IHostedService.StartAsync(), however?

[davidfowl]

This shouldn't be part of DI if isn't used in the DI container

[ericstj]

Microsoft.Extensions.Hosting.Abstractions seems a better fit. It looks like this is low enough in the stack. It's not used by Options at the moment, but it seems like it could be without upsetting any existing layering. That's consistent with the existing ServiceCollectionHostedServiceExtensions

Below is the runtime layering:

graph TD;    
    Logging-->DependencyInjection;
    Logging-->Logging.Abstractions;
    Logging-->DependencyInjection.Abstractions;
    Logging-->Options;
    Hosting-->Logging;
    Hosting-->Logging.EventLog;
    Hosting-->Logging.Debug;
    Hosting-->FileProviders.Physical;
    Hosting-->Logging.Configuration;
    Hosting-->Configuration;
    Hosting-->DependencyInjection;
    Hosting-->Configuration.Json;
    Hosting-->Configuration.Binder;
    Hosting-->Configuration.EnvironmentVariables;
    Hosting-->Logging.EventSource;
    Hosting-->Configuration.FileExtensions;
    Hosting-->Logging.Abstractions;
    Hosting-->Hosting.Abstractions;
    Hosting-->Configuration.Abstractions;
    Hosting-->DependencyInjection.Abstractions;
    Hosting-->FileProviders.Abstractions;
    Hosting-->Options;
    Hosting-->Logging.Console;
    Hosting-->Configuration.UserSecrets;
    Hosting-->Configuration.CommandLine;
    Logging.EventLog-->Logging;
    Logging.EventLog-->Logging.Abstractions;
    Logging.EventLog-->DependencyInjection.Abstractions;
    Logging.EventLog-->Options;
    Logging.Debug-->Logging;
    Logging.Debug-->Logging.Abstractions;
    Logging.Debug-->DependencyInjection.Abstractions;
    Configuration.Ini-->Configuration;
    Configuration.Ini-->Configuration.FileExtensions;
    Configuration.Ini-->Configuration.Abstractions;
    Configuration.Ini-->FileProviders.Abstractions;
    Logging.TraceSource-->Logging;
    Logging.TraceSource-->Logging.Abstractions;
    Logging.TraceSource-->DependencyInjection.Abstractions;
    FileProviders.Physical-->FileSystemGlobbing;
    FileProviders.Physical-->Primitives;
    FileProviders.Physical-->FileProviders.Abstractions;
    Configuration.Xml-->Configuration;
    Configuration.Xml-->Configuration.FileExtensions;
    Configuration.Xml-->Configuration.Abstractions;
    Configuration.Xml-->FileProviders.Abstractions;
    Logging.Configuration-->Logging;
    Logging.Configuration-->Configuration;
    Logging.Configuration-->Configuration.Binder;
    Logging.Configuration-->Options.ConfigurationExtensions;
    Logging.Configuration-->Logging.Abstractions;
    Logging.Configuration-->Configuration.Abstractions;
    Logging.Configuration-->DependencyInjection.Abstractions;
    Logging.Configuration-->Options;
    Configuration-->Primitives;
    Configuration-->Configuration.Abstractions;
    DependencyInjection-->DependencyInjection.Abstractions;
    Configuration.Json-->Configuration;
    Configuration.Json-->Configuration.FileExtensions;
    Configuration.Json-->Configuration.Abstractions;
    Configuration.Json-->FileProviders.Abstractions;
    Http-->Logging;
    Http-->Logging.Abstractions;
    Http-->DependencyInjection.Abstractions;
    Http-->Options;
    Configuration.Binder-->Configuration.Abstractions;
    Configuration.EnvironmentVariables-->Configuration;
    Configuration.EnvironmentVariables-->Configuration.Abstractions;
    Logging.EventSource-->Logging;
    Logging.EventSource-->Primitives;
    Logging.EventSource-->Logging.Abstractions;
    Logging.EventSource-->DependencyInjection.Abstractions;
    Logging.EventSource-->Options;
    Configuration.FileExtensions-->FileProviders.Physical;
    Configuration.FileExtensions-->Configuration;
    Configuration.FileExtensions-->Primitives;
    Configuration.FileExtensions-->Configuration.Abstractions;
    Configuration.FileExtensions-->FileProviders.Abstractions;
    Options.ConfigurationExtensions-->Configuration.Binder;
    Options.ConfigurationExtensions-->Primitives;
    Options.ConfigurationExtensions-->Configuration.Abstractions;
    Options.ConfigurationExtensions-->DependencyInjection.Abstractions;
    Options.ConfigurationExtensions-->Options;
    Options.DataAnnotations-->DependencyInjection.Abstractions;
    Options.DataAnnotations-->Options;
    Caching.Abstractions-->Primitives;
    Hosting.Abstractions:::classHA-->Configuration.Abstractions;
    Hosting.Abstractions-->DependencyInjection.Abstractions;
    Hosting.Abstractions-->FileProviders.Abstractions;
    Configuration.Abstractions-->Primitives;
    FileProviders.Abstractions-->Primitives;
    Options:::classO-->Primitives;
    Options-->DependencyInjection.Abstractions;
    Logging.Console-->Logging;
    Logging.Console-->Logging.Configuration;
    Logging.Console-->Options.ConfigurationExtensions;
    Logging.Console-->Logging.Abstractions;
    Logging.Console-->Configuration.Abstractions;
    Logging.Console-->DependencyInjection.Abstractions;
    Logging.Console-->Options;
    Configuration.UserSecrets-->FileProviders.Physical;
    Configuration.UserSecrets-->Configuration.Json;
    Configuration.UserSecrets-->Configuration.Abstractions;
    Caching.Memory-->Primitives;
    Caching.Memory-->Logging.Abstractions;
    Caching.Memory-->Caching.Abstractions;
    Caching.Memory-->DependencyInjection.Abstractions;
    Caching.Memory-->Options;
    Configuration.CommandLine-->Configuration;
    Configuration.CommandLine-->Configuration.Abstractions;
    classDef classHA fill:#f96
    classDef classO fill:#9f3

Loading

This would mean that Options would add Microsoft.Extensions.Hosting.Abstractions, Microsoft.Extensions.Configuration.Abstractions, and Microsoft.Extensions.FileProviders.Abstractions to it's closure when implementing #84347. All pretty small. The only other option (pun not intended) would be Microsoft.Extensions.Primitives which would not add anything to Options' closure, but that seems wrong.

We'd also need to think about #43149. This would need to go in Microsoft.Extensions.Hosting.Abstractions or higher as well. That seems reasonable since it's about describing an interaction of DI with startup (hosting concept).

@davidfowl / @DamianEdwards, what do you think about timeout? Is it OK to add a timeout that corresponds to both this and IHostedService startup?

[DamianEdwards]

what do you think about timeout? Is it OK to add a timeout that corresponds to both this and IHostedService startup?

This could only be a cooperative timeout right? So if we did have one, I would assume it would be encapsulated in the CancellationToken passed in. But generally speaking I don't think we need one for the startup case as the point is to be able to add logic that runs as part of startup in a logically blocking way. If you want to timebox a startup task, just put that logic in the startup task. Shutdown of course is different as the process can just end after the timeout has expired.

[steveharter]

This shouldn't be part of DI if isn't used in the DI container

Microsoft.Extensions.Hosting.Abstractions seems a better fit.

Moving to Microsoft.Extensions.Hosting.Abstractions makes sense provided that addresses the concerns based on this comment from @tekian where "hosting" may not used, for example, by Azure Functions SDK. I'm assuming now that the "hosting" comment means the super-high-level Microsoft.Extensions.Hosting assembly and not the lower-level Microsoft.Extensions.Hosting.Abstractions.

[steveharter]

This could only be a cooperative timeout right? So if we did have one, I would assume it would be encapsulated in the CancellationToken passed in.

It should work the same way as today's ShutdownTimeout + Host.StopAsync() which uses the cancellation token.

Also, the startup timeout would need to be off by default, to prevent a breaking change for long-running IHostedService.StartAsync() implementations. However, if we only include the new IServiceStartup.StartupAsync() in the timeout (and not IHostedService.StartAsync()) then we could have a default of say, 30 seconds, which is the default for ShutdownTimeout.

[DamianEdwards]

Are we saying it will stop "blocking" startup after the timeout is reached?