# DistributedApplication Methods

- Package: [Aspire.Hosting](/reference/api/csharp/aspire.hosting.md)
- Type: [DistributedApplication](/reference/api/csharp/aspire.hosting/distributedapplication.md)
- Kind: `Methods`
- Members: `9`

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

## CreateBuilder

- Name: `CreateBuilder`
- Modifiers: `static`
- Returns: [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/DistributedApplication.cs#L105)

Creates a new instance of the [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md) interface.

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

## Returns

[IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md) -- A new instance of the [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md) interface.

## Remarks

This overload of the [DistributedApplication.CreateBuilder](/reference/api/csharp/aspire.hosting/distributedapplication/methods.md#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](/reference/api/csharp/aspire.hosting/distributedapplication/methods.md#createbuilder) method the app host has no way to be put into publish mode. Refer to [DistributedApplication.CreateBuilder](/reference/api/csharp/aspire.hosting/distributedapplication/methods.md#createbuilder) or [DistributedApplication.CreateBuilder(DistributedApplicationOptions)](/reference/api/csharp/aspire.hosting/distributedapplication/methods.md#createbuilder-distributedapplicationoptions) 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.

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

builder.Build().Run();
```

## CreateBuilder(string[])

- Name: `CreateBuilder(string[])`
- Modifiers: `static`
- Returns: [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/DistributedApplication.cs#L158-L163)

Creates a new instance of [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md) with the specified command-line arguments.

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

## Parameters

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

## Returns

[IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md) -- A new instance of [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md).

## Remarks

The [DistributedApplication.CreateBuilder](/reference/api/csharp/aspire.hosting/distributedapplication/methods.md#createbuilder) method is the most common way to create an instance of the [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md) 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(DistributedApplicationOptions)](/reference/api/csharp/aspire.hosting/distributedapplication/methods.md#createbuilder-distributedapplicationoptions) overload of this method.

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

```csharp
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.

```csharp
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();
    }
}
```

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the internal createBuilder dispatcher export.

## CreateBuilder(DistributedApplicationOptions)

- Name: `CreateBuilder(DistributedApplicationOptions)`
- Modifiers: `static`
- Returns: [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/DistributedApplication.cs)

Creates a new instance of the [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md) interface with the specified `options`.

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

## Parameters

- `options` ([DistributedApplicationOptions](/reference/api/csharp/aspire.hosting/distributedapplicationoptions.md))
  The [DistributedApplicationOptions](/reference/api/csharp/aspire.hosting/distributedapplicationoptions.md) to use for configuring the builder.

## Returns

[IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md) -- A new instance of the [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md) interface.

## Remarks

The [DistributedApplication.CreateBuilder(DistributedApplicationOptions)](/reference/api/csharp/aspire.hosting/distributedapplication/methods.md#createbuilder-distributedapplicationoptions) 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](/reference/api/csharp/aspire.hosting/distributedapplicationoptions/properties.md#containerregistryoverride) property, or disabling the dashboard by using the [DistributedApplicationOptions.DisableDashboard](/reference/api/csharp/aspire.hosting/distributedapplicationoptions/properties.md#disabledashboard) property. Refer to the [DistributedApplicationOptions](/reference/api/csharp/aspire.hosting/distributedapplicationoptions.md) class for more details on each option that may be provided.

When supplying a custom [DistributedApplicationOptions](/reference/api/csharp/aspire.hosting/distributedapplicationoptions.md) it is recommended to populate the [DistributedApplicationOptions.Args](/reference/api/csharp/aspire.hosting/distributedapplicationoptions/properties.md#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.

```csharp
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

- Name: `Dispose`
- Modifiers: `virtual`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/DistributedApplication.cs#L402-L403)

Disposes the distributed application by disposing the `Hosting.IHost`.

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

## Remarks

Typically developers do not need to worry about calling the Dispose method on the [DistributedApplication](/reference/api/csharp/aspire.hosting/distributedapplication.md) 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](/reference/api/csharp/aspire.hosting/distributedapplication.md) and [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md) inside unit test code then you should correctly dispose of the [DistributedApplication](/reference/api/csharp/aspire.hosting/distributedapplication.md) instance. This is because the [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md) instance initializes configuration providers which make use of file watchers which are a finite resource.

Without disposing of the [DistributedApplication](/reference/api/csharp/aspire.hosting/distributedapplication.md) 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](https://aka.ms/aspire/testing) for more information on how to use Aspire APIs for functional an integrating testing.

## DisposeAsync

- Name: `DisposeAsync`
- Modifiers: `virtual`
- Returns: `ValueTask`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/DistributedApplication.cs#L434)

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

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

## 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](/reference/api/csharp/aspire.hosting/distributedapplication.md) 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](/reference/api/csharp/aspire.hosting/distributedapplication.md) and [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md) inside unit test code then you should correctly dispose of the [DistributedApplication](/reference/api/csharp/aspire.hosting/distributedapplication.md) instance. This is because the [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md) instance initializes configuration providers which make use of file watchers which are a finite resource.

Without disposing of the [DistributedApplication](/reference/api/csharp/aspire.hosting/distributedapplication.md) 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](https://aka.ms/aspire/testing) for more information on how to use Aspire APIs for functional an integrating testing.

## Run

- Name: `Run`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/DistributedApplication.cs#L544-L545)

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

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

## Remarks

When the Aspire app host is launched via [DistributedApplication.RunAsync(CancellationToken)](/reference/api/csharp/aspire.hosting/distributedapplication/methods.md#runasync-cancellationtoken) there are two possible modes that it is running in:

1. Run mode; in run mode the app host 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.
2. Publish mode; in publish mode the app host 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 app host is running in refer to [DistributedApplicationExecutionContext](/reference/api/csharp/aspire.hosting/distributedapplicationexecutioncontext.md).

## RunAsync(CancellationToken)

- Name: `RunAsync(CancellationToken)`
- Modifiers: `virtual`
- Returns: `Task`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/DistributedApplication.cs#L502-L517)

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.

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

## Parameters

- `cancellationToken` (`CancellationToken`) `optional`
  The token to trigger shutdown.

## Returns

`Task` -- The `Tasks.Task` that represents the asynchronous operation.

## Remarks

When the Aspire app host is launched via [DistributedApplication.RunAsync(CancellationToken)](/reference/api/csharp/aspire.hosting/distributedapplication/methods.md#runasync-cancellationtoken) there are two possible modes that it is running in:

1. Run mode; in run mode the app host 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.
2. Publish mode; in publish mode the app host 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 app host is running in refer to [DistributedApplicationExecutionContext](/reference/api/csharp/aspire.hosting/distributedapplicationexecutioncontext.md).

## ATS metadata

### ATS export

- Capability ID: `Aspire.Hosting/run`

## StartAsync(CancellationToken)

- Name: `StartAsync(CancellationToken)`
- Modifiers: `virtual`
- Returns: `Task`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/DistributedApplication.cs#L441-L456)

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

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

## 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)

- Name: `StopAsync(CancellationToken)`
- Modifiers: `virtual`
- Returns: `Task`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/DistributedApplication.cs#L461-L468)

Attempts to gracefully stop the program.

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

## 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.