Shut down Orleans silos

Orleans is an IHostedService inside the .NET Generic Host. When the host stops, it calls Orleans’ StopAsync method. Orleans then leaves the cluster, closes gateways and networking, deactivates grains, and stops providers in reverse lifecycle order.

Graceful silo shutdown

Build the host with CreateApplicationBuilder and run it with RunAsync or Run. Both Host.CreateApplicationBuilder and the older Host.CreateDefaultBuilder register IHostLifetime with the console lifetime by default, so no additional call is needed to observe termination requests:

public static async Task RunSilo(string[] args)
{
    var builder = Host.CreateApplicationBuilder(args);

    builder.UseOrleans(siloBuilder =>
    {
        // Configure Orleans.
    });

    await builder.Build().RunAsync();
}

The configured .NET host lifetime handles the relevant termination events and initiates the Generic Host shutdown sequence, so applications shouldn’t add a separate process-exit handler. For details, see .NET Generic Host shutdown.

In tests or embedded hosts, call StopAsync and dispose the host:

public static async Task StopHost(
    IHost host,
    CancellationToken cancellationToken)
{
    await host.StopAsync(cancellationToken);
    host.Dispose();
}

Don’t call Exit, kill the process from application code, or dispose Orleans services independently of the host.

Configure a shutdown budget

The host passes a cancellation token to every hosted service during shutdown, including Orleans. ShutdownTimeout cancels that token after the configured budget. Configure it for the expected workload:

public static void ConfigureShutdownTimeout(
    IHostApplicationBuilder builder)
{
    builder.Services.Configure<HostOptions>(options =>
    {
        options.ShutdownTimeout = TimeSpan.FromSeconds(45);
    });
}

Set the orchestrator’s termination grace period longer than the host shutdown timeout. Include time for:

• Load balancers and readiness probes to stop sending new traffic.
• Gateway and membership changes to propagate.
• Grain deactivation callbacks and state writes.
• Stream, reminder, storage, and telemetry providers to flush and stop.

If the external grace period expires first, the process is killed and graceful shutdown can’t complete.

Make application code shutdown-safe

• Honor cancellation tokens in hosted services, startup tasks, lifecycle participants, and provider calls.
• Keep OnDeactivateAsync bounded; persist important state during normal operation rather than relying only on shutdown.
• Stop accepting new application work before the termination deadline.
• Make recovery safe after abrupt termination, because crashes and node loss remain possible.
• Avoid synchronous blocking and unbounded retries in shutdown callbacks.

Grains can move or reactivate elsewhere after a silo leaves. Don’t use graceful shutdown as an application-wide drain barrier unless the application separately coordinates that behavior.

Containers and orchestrators

Remove the instance from application traffic before requesting host shutdown. Then send the platform’s normal termination request, allow the host shutdown budget to elapse, and reserve forceful termination for hung processes. A forced termination, power loss, or process crash can bypass the host entirely, so correctness must not depend on graceful shutdown.

See also

For ordered Orleans callbacks, see Orleans silo lifecycle.