DistributedApplication Methods

Docs / Reference / Search C# APIs / Aspire.Hosting / DistributedApplication / Methods

Methods

Docs Reference Search C# APIs Aspire.Hosting DistributedApplication Methods

Class Methods 9 members

Represents a distributed application that implements the Hosting.IHost and IAsyncDisposable interfaces.

CreateBuilder static IDistributedApplicationBuilder

Creates a new instance of the IDistributedApplicationBuilder interface.

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

DistributedApplication.cs#L93

Returns

IDistributedApplicationBuilder A new instance of the IDistributedApplicationBuilder interface.

Remarks

This overload of the DistributedApplication.CreateBuilder method should only be used when the app host is not intended to be used with a deployment tool. Because no arguments are passed to the DistributedApplication.CreateBuilder method the app host 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[]) static IDistributedApplicationBuilder

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

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

DistributedApplication.cs#L145-L150

Parameters

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

Returns

IDistributedApplicationBuilder A 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) static IDistributedApplicationBuilder

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

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

DistributedApplication.cs#L192-L197

Parameters

options DistributedApplicationOptions The DistributedApplicationOptions to use for configuring the builder.

Returns

IDistributedApplicationBuilder A 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 app host 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();

Dispose virtual

Disposes the distributed application by disposing the Hosting.IHost.

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

DistributedApplication.cs#L338-L339

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 .NET Aspire testing page for more information on how to use .NET Aspire APIs for functional an integrating testing.

DisposeAsync virtual ValueTask

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

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

DistributedApplication.cs#L370

Returns

ValueTask A 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 .NET Aspire testing page for more information on how to use .NET 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#L471-L472

Remarks

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

Developers extending the .NET 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 app host is running in refer to DistributedApplicationExecutionContext.

RunAsync(CancellationToken) virtual Task

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#L437-L444

Parameters

cancellationToken CancellationToken optional The token to trigger shutdown.

Returns

Task The Tasks.Task that represents the asynchronous operation.

Remarks

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

Developers extending the .NET 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 app host is running in refer to DistributedApplicationExecutionContext.

StartAsync(CancellationToken) virtual Task

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

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

DistributedApplication.cs#L377-L392

Parameters

cancellationToken CancellationToken optional Used to abort program start.

Returns

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

StopAsync(CancellationToken) virtual Task

Attempts to gracefully stop the program.

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

DistributedApplication.cs#L397-L404

Parameters

cancellationToken CancellationToken optional Used to indicate when stop should no longer be graceful.

Returns

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