Skip to content

Commit

Permalink
Update hosting shutdown doc (dotnet#56176)
Browse files Browse the repository at this point in the history
  • Loading branch information
eerhardt authored Jul 22, 2021
1 parent 77d23f0 commit c205295
Showing 1 changed file with 11 additions and 4 deletions.
15 changes: 11 additions & 4 deletions src/libraries/Microsoft.Extensions.Hosting/docs/HostShutdown.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,12 @@ This would allow for the clean up code in the application to run - for example,
`Host.Run` in the Main method.

This caused other issues because SIGTERM wasn't the only way `ProcessExit` was raised. It is also raised by code
in the application calling `Environment.Exit`. `Environment.Exit` isn't a graceful way of shutting down a process.
It raises the `ProcessExit` event and then exits the process. The end of the Main method doesn't get executed. However,
since ConsoleLifetime blocked `ProcessExit` waiting for the Host to shutdown, this behavior also lead to [deadlocks][deadlocks]
due to `Environment.Exit` also blocking waiting for `ProcessExit` to return. Additionally, since SIGTERM handling was attempting
in the application calling `Environment.Exit`. `Environment.Exit` isn't a graceful way of shutting down a process
in the `Microsoft.Extensions.Hosting` app model. It raises the `ProcessExit` event and then exits the process. The end of the
Main method doesn't get executed. Background and foreground threads are terminated. `finally` blocks are not executed.

Since ConsoleLifetime blocked `ProcessExit` waiting for the Host to shutdown, this behavior lead to [deadlocks][deadlocks]
due to `Environment.Exit` also blocking waiting for `ProcessExit` to return. Additionally, since the SIGTERM handling was attempting
to gracefully shut down the process, ConsoleLifetime would set the ExitCode to `0`, which [clobbered][clobbered] the user's
exit code passed to `Environment.Exit`.

Expand All @@ -42,6 +44,11 @@ has logic to handle scenario (5) above. Apps that call `Environment.Exit`, and n

[POSIX signals]: https://github.com/dotnet/runtime/issues/50527

If your application uses Hosting, and you want to gracefully stop the host, you can call
[`IHostApplicationLifetime.StopApplication()`][StopApplication] instead of `Environment.Exit`.

[StopApplication]: https://docs.microsoft.com/dotnet/api/microsoft.extensions.hosting.ihostapplicationlifetime.stopapplication

### Hosting Shutdown Process

The following sequence model shows how the signals in (4) above are handled internally in the Hosting code. It isn't necessary
Expand Down

0 comments on commit c205295

Please sign in to comment.