DistributedApplication.CreateBuilder Method

Definition

Namespace:

Aspire.Hosting

Assembly:

Aspire.Hosting.dll

Package:

Aspire.Hosting v8.2.0

Overloads

CreateBuilder()	Creates a new instance of the IDistributedApplicationBuilder interface.
CreateBuilder(DistributedApplicationOptions)	Creates a new instance of the IDistributedApplicationBuilder interface with the specified options.
CreateBuilder(String[])	Creates a new instance of IDistributedApplicationBuilder with the specified command-line arguments.

CreateBuilder()

Source:

DistributedApplication.cs

Creates a new instance of the IDistributedApplicationBuilder interface.

public static Aspire.Hosting.IDistributedApplicationBuilder CreateBuilder ();

static member CreateBuilder : unit -> Aspire.Hosting.IDistributedApplicationBuilder

Public Shared Function CreateBuilder () As IDistributedApplicationBuilder

Returns

IDistributedApplicationBuilder

A new instance of the IDistributedApplicationBuilder interface.

Examples

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();

Remarks

This overload of the 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 CreateBuilder() method the app host has no way to be put into publish mode. Refer to CreateBuilder(String[]) or CreateBuilder(DistributedApplicationOptions) when more control is needed over the behavior of the distributed application at runtime.

CreateBuilder(DistributedApplicationOptions)

Source:

DistributedApplication.cs

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

public static Aspire.Hosting.IDistributedApplicationBuilder CreateBuilder (Aspire.Hosting.DistributedApplicationOptions options);

static member CreateBuilder : Aspire.Hosting.DistributedApplicationOptions -> Aspire.Hosting.IDistributedApplicationBuilder

Public Shared Function CreateBuilder (options As DistributedApplicationOptions) As IDistributedApplicationBuilder

Parameters

options

DistributedApplicationOptions

The DistributedApplicationOptions to use for configuring the builder.

Returns

IDistributedApplicationBuilder

A new instance of the IDistributedApplicationBuilder interface.

Examples

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();

Remarks

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

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

CreateBuilder(String[])

Source:

DistributedApplication.cs

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

public static Aspire.Hosting.IDistributedApplicationBuilder CreateBuilder (string[] args);

static member CreateBuilder : string[] -> Aspire.Hosting.IDistributedApplicationBuilder

Public Shared Function CreateBuilder (args As String()) As IDistributedApplicationBuilder

Parameters

args

String[]

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

Returns

IDistributedApplicationBuilder

A new instance of IDistributedApplicationBuilder.

Remarks

The CreateBuilder(String[]) 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 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 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.

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