DistributedApplication Methods

CreateBuilderstaticIDistributedApplicationBuilder

Creates a new instance of the IDistributedApplicationBuilder interface.

public class DistributedApplication
{
    public static IDistributedApplicationBuilder CreateBuilder()
    {
        // ...
    }
}

DistributedApplication.cs#L115

Returns

IDistributedApplicationBuilderA new instance of the IDistributedApplicationBuilder interface.

Remarks

This overload of the DistributedApplication.CreateBuilder method should only be used when the AppHost is not intended to be used with a deployment tool. Because no arguments are passed to the DistributedApplication.CreateBuilder method the AppHost has no way to be put into publish mode. Refer to DistributedApplication.CreateBuilder or DistributedApplication.CreateBuilder when more control is needed over the behavior of the distributed application at runtime. The following example is creating a Postgres server resource with a database and referencing that database in a .NET project.

var builder = DistributedApplication.CreateBuilder();
var inventoryDatabase = builder.AddPostgres(
    "mypostgres").AddDatabase("inventory");
builder.AddProject<Projects.InventoryService>()
       .WithReference(inventoryDatabase);

builder.Build().Run();

CreateBuilder(string[])staticIDistributedApplicationBuilder

Creates a new instance of IDistributedApplicationBuilder with the specified command-line arguments.

public class DistributedApplication
{
    public static IDistributedApplicationBuilder CreateBuilder(
        string[] args)
    {
        // ...
    }
}

DistributedApplication.cs#L168-L174

Parameters

argsstring[]The command-line arguments to use when building the distributed application.

Returns

IDistributedApplicationBuilderA new instance of IDistributedApplicationBuilder.

Remarks

The DistributedApplication.CreateBuilder method is the most common way to create an instance of the IDistributedApplicationBuilder interface. Typically this method will be called as a top-level statement in the application's entry-point.

Note that the args parameter is a string and is essential in allowing the application host to work with deployment tools because arguments are used to tell the application host that it is in publish mode. If args is not provided the application will not work with deployment tools. It is also possible to provide arguments using the DistributedApplication.CreateBuilder overload of this method.

The following example shows creating a Postgres server resource with a database and referencing that database in a .NET project.

var builder = DistributedApplication.CreateBuilder(args);
var inventoryDatabase = builder.AddPostgres(
    "mypostgres").AddDatabase("inventory");
builder.AddProject<Projects.InventoryService>()
       .WithReference(inventoryDatabase);

builder.Build().Run();

The following example is equivalent to the previous example except that it does not use top-level statements.

public class Program
{
    public static void Main(string[] args)
    {
        var builder = DistributedApplication.CreateBuilder(args);
        var inventoryDatabase = builder.AddPostgres(
            "mypostgres").AddDatabase("inventory");
        builder.AddProject<Projects.InventoryService>()
               .WithReference(inventoryDatabase);

        builder.Build().Run();
    }
}

CreateBuilder(DistributedApplicationOptions)staticIDistributedApplicationBuilder

Creates a new instance of the IDistributedApplicationBuilder interface with the specified options.

public class DistributedApplication
{
    public static IDistributedApplicationBuilder CreateBuilder(
        DistributedApplicationOptions options)
    {
        // ...
    }
}

DistributedApplication.cs

Parameters

optionsDistributedApplicationOptionsThe DistributedApplicationOptions to use for configuring the builder.

Returns

IDistributedApplicationBuilderA new instance of the IDistributedApplicationBuilder interface.

Remarks

The DistributedApplication.CreateBuilder method provides greater control over the behavior of the distributed application at runtime. For example providing an options argument allows developers to force all container images to be loaded from a specified container registry by using the DistributedApplicationOptions.ContainerRegistryOverride property, or disabling the dashboard by using the DistributedApplicationOptions.DisableDashboard property. Refer to the DistributedApplicationOptions class for more details on each option that may be provided.

When supplying a custom DistributedApplicationOptions it is recommended to populate the DistributedApplicationOptions.Args property to ensure that the AppHost continues to function correctly when used with deployment tools that need to enable publish mode.

Override the container registry used by the distributed application.

var options = new DistributedApplicationOptions
{
    Args = args; // Important for deployment tools
    ContainerRegistryOverride = "registry.example.com"
};
var builder = DistributedApplication.CreateBuilder(options);
var inventoryDatabase = builder.AddPostgres(
    "mypostgres").AddDatabase("inventory");
builder.AddProject<Projects.InventoryService>()
       .WithReference(inventoryDatabase);

builder.Build().Run();

Disposevirtual

Disposes the distributed application by disposing the Hosting.IHost.

public class DistributedApplication
{
    public virtual void Dispose()
    {
        // ...
    }
}

DistributedApplication.cs#L425-L426

Remarks

Typically developers do not need to worry about calling the Dispose method on the DistributedApplication instance because it is typically used in the entry point of the application and all resources used by the application are destroyed when the application exists.

If you are using the DistributedApplication and IDistributedApplicationBuilder inside unit test code then you should correctly dispose of the DistributedApplication instance. This is because the IDistributedApplicationBuilder instance initializes configuration providers which make use of file watchers which are a finite resource.

Without disposing of the DistributedApplication correctly projects with a large number of functional/integration tests may see a "The configured user limit (128) on the number of inotify instances has been reached, or the per-process limit on the number of open file descriptors has been reached." error.

Refer to the Aspire testing page for more information on how to use Aspire APIs for functional an integrating testing.

DisposeAsyncvirtualValueTask

Asynchronously disposes the distributed application by disposing the Hosting.IHost.

public class DistributedApplication
{
    public virtual ValueTask DisposeAsync()
    {
        // ...
    }
}

DistributedApplication.cs#L457

Returns

ValueTaskA Tasks.ValueTask representing the asynchronous operation.

Remarks

Typically developers do not need to worry about calling the Dispose method on the DistributedApplication instance because it is typically used in the entry point of the application and all resources used by the application are destroyed when the application exists.

If you are using the DistributedApplication and IDistributedApplicationBuilder inside unit test code then you should correctly dispose of the DistributedApplication instance. This is because the IDistributedApplicationBuilder instance initializes configuration providers which make use of file watchers which are a finite resource.

Without disposing of the DistributedApplication correctly projects with a large number of functional/integration tests may see a "The configured user limit (128) on the number of inotify instances has been reached, or the per-process limit on the number of open file descriptors has been reached." error.

Refer to the Aspire testing page for more information on how to use Aspire APIs for functional an integrating testing.

Run

Runs an application and blocks the calling thread until host shutdown is triggered and all Hosting.IHostedService instances are stopped.

public class DistributedApplication
{
    public void Run()
    {
        // ...
    }
}

DistributedApplication.cs#L603-L604

Remarks

When the Aspire AppHost is launched via DistributedApplication.RunAsync there are two possible modes that it is running in:

Run mode; in run mode the AppHost runs until a shutdown of the app is triggered either by the users pressing Ctrl-C, the debugger detaching, or the browser associated with the dashboard being closed.
Publish mode; in publish mode the AppHost runs just long enough to generate a manifest file that is used by deployment tool.

Developers extending the Aspire application model should consider the lifetime of Hosting.IHostedService instances which are added to the dependency injection container. For more information on determining the mode that the AppHost is running in refer to DistributedApplicationExecutionContext.

RunAsync(CancellationToken)virtualTask

Runs an application and returns a Task that only completes when the token is triggered or shutdown is triggered and all Hosting.IHostedService instances are stopped.

public class DistributedApplication
{
    public virtual Task RunAsync(
        CancellationToken cancellationToken = default(CancellationToken))
    {
        // ...
    }
}

DistributedApplication.cs#L535-L573

Parameters

cancellationTokenCancellationTokenoptionalThe token to trigger shutdown.

Returns

TaskThe Tasks.Task that represents the asynchronous operation.

Remarks

When the Aspire AppHost is launched via DistributedApplication.RunAsync there are two possible modes that it is running in:

Run mode; in run mode the AppHost runs until a shutdown of the app is triggered either by the users pressing Ctrl-C, the debugger detaching, or the browser associated with the dashboard being closed.
Publish mode; in publish mode the AppHost runs just long enough to generate a manifest file that is used by deployment tool.

Developers extending the Aspire application model should consider the lifetime of Hosting.IHostedService instances which are added to the dependency injection container. For more information on determining the mode that the AppHost is running in refer to DistributedApplicationExecutionContext.

StartAsync(CancellationToken)virtualTask

Starts the Hosting.IHostedService objects configured for the program. The application will run until interrupted or until IHostApplicationLifetime.StopApplication is called.

public class DistributedApplication
{
    public virtual Task StartAsync(
        CancellationToken cancellationToken = default(CancellationToken))
    {
        // ...
    }
}

DistributedApplication.cs#L464-L492

Parameters

cancellationTokenCancellationTokenoptionalUsed to abort program start.

Returns

TaskA Tasks.Task that will be completed when the Hosting.IHost starts.

StopAsync(CancellationToken)virtualTask

Attempts to gracefully stop the program.

public class DistributedApplication
{
    public virtual Task StopAsync(
        CancellationToken cancellationToken = default(CancellationToken))
    {
        // ...
    }
}

DistributedApplication.cs#L497-L504

Parameters

cancellationTokenCancellationTokenoptionalUsed to indicate when stop should no longer be graceful.

Returns

TaskA Tasks.Task that will be completed when the Hosting.IHost stops.