# IDistributedApplicationBuilder Methods

- Package: [Aspire.Hosting](/reference/api/csharp/aspire.hosting.md)
- Type: [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md)
- Kind: `Methods`
- Members: `3`

A builder for creating instances of [DistributedApplication](/reference/api/csharp/aspire.hosting/distributedapplication.md).

## AddResource(T)

- Name: `AddResource(T)`
- Modifiers: `abstract`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)

Adds a resource of type `T` to the distributed application.

```csharp
public interface IDistributedApplicationBuilder
{
    public abstract IResourceBuilder<T> AddResource<T>(
        T resource)
    {
        // ...
    }
}
```

## Parameters

- `resource` (`T`)
  The resource to add.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- A builder for configuring the added resource.

## Exceptions

- [DistributedApplicationException](/reference/api/csharp/aspire.hosting/distributedapplicationexception.md) -- Thrown when a resource with the same name already exists.

## Remarks

The [IDistributedApplicationBuilder.AddResource(T)](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder/methods.md#addresource-t) method is not typically used directly by developers building Aspire-based applications. It is typically used by developers building extensions to Aspire and is called from within an extension method to add a custom resource to the application model.

This example shows the implementation of the [ContainerResourceBuilderExtensions.AddContainer(IDistributedApplicationBuilder, string, string)](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods.md#addcontainer-idistributedapplicationbuilder-string-string) method which makes use of the [IDistributedApplicationBuilder.AddResource(T)](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder/methods.md#addresource-t) method to add a container resource to the application. In Aspire the pattern for defining new resources is to include a method that extends [IDistributedApplicationBuilder](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder.md) and and then constructs a resource derived from [IResource](/reference/api/csharp/aspire.hosting/iresource.md) and adds it to the application model using the [IDistributedApplicationBuilder.AddResource(T)](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder/methods.md#addresource-t) method. Other extension methods (such as [ContainerResourceBuilderExtensions.WithImage(IResourceBuilder<T>, string, string?)](/reference/api/csharp/aspire.hosting/containerresourcebuilderextensions/methods.md#withimage-iresourcebuilder-t-string-string) in this case) can be chained to configure the resource as desired.

```csharp
public static IResourceBuilder<ContainerResource> AddContainer(this IDistributedApplicationBuilder builder, [ResourceName] string name, string image, string tag)
{
    var container = new ContainerResource(name);
    return builder.AddResource(container)
                  .WithImage(image, tag);
}
```

## Build

- Name: `Build`
- Modifiers: `abstract`
- Returns: [DistributedApplication](/reference/api/csharp/aspire.hosting/distributedapplication.md)

Builds and returns a new [DistributedApplication](/reference/api/csharp/aspire.hosting/distributedapplication.md) instance. This can only be called once.

```csharp
public interface IDistributedApplicationBuilder
{
    public abstract DistributedApplication Build()
    {
        // ...
    }
}
```

## Returns

[DistributedApplication](/reference/api/csharp/aspire.hosting/distributedapplication.md) -- A new [DistributedApplication](/reference/api/csharp/aspire.hosting/distributedapplication.md) instance.

## Remarks

Callers of the [IDistributedApplicationBuilder.Build](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder/methods.md#build) method should only call it once. are responsible for the lifecycle of the [DistributedApplication](/reference/api/csharp/aspire.hosting/distributedapplication.md) instance that is returned. Note that the [DistributedApplication](/reference/api/csharp/aspire.hosting/distributedapplication.md) type implements `IDisposable` and should be disposed of when it is no longer needed. Note that in many templates and samples Dispose is omitted for brevity because in those cases the instance is destroyed when the process exists.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## CreateResourceBuilder(T)

- Name: `CreateResourceBuilder(T)`
- Modifiers: `abstract`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)

Creates a new resource builder based on an existing resource.

```csharp
public interface IDistributedApplicationBuilder
{
    public abstract IResourceBuilder<T> CreateResourceBuilder<T>(
        T resource)
    {
        // ...
    }
}
```

## Parameters

- `resource` (`T`)
  An existing resource.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- A resource builder.

## Remarks

The [IDistributedApplicationBuilder.CreateResourceBuilder(T)](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder/methods.md#createresourcebuilder-t) method is used to create an `ApplicationModel.IResourceBuilder`1` for a specific resource where the original resource builder cannot be referenced. This does not create a new resource, but instead returns a resource builder for an existing resource.

This method is typically used when building extensions to Aspire where the original resource builder cannot be referenced directly. Using the [IDistributedApplicationBuilder.CreateResourceBuilder(T)](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder/methods.md#createresourcebuilder-t) method allows for easier mutation of resources within the application model.

Calling extension methods on the `ApplicationModel.IResourceBuilder`1` typically results in modifications to the [IResource.Annotations](/reference/api/csharp/aspire.hosting/iresource/properties.md#annotations) collection. Not all changes to annotations will be effective depending on what stage of the lifecycle the app host is in. See [IDistributedApplicationLifecycleHook](/reference/api/csharp/aspire.hosting/idistributedapplicationlifecyclehook.md) for more details.

The following example shows the implementation of the [ParameterResourceBuilderExtensions.AddConnectionString(IDistributedApplicationBuilder, string, string?)](/reference/api/csharp/aspire.hosting/parameterresourcebuilderextensions/methods.md#addconnectionstring-idistributedapplicationbuilder-string-string) extension method.

The [ParameterResourceBuilderExtensions.AddConnectionString(IDistributedApplicationBuilder, string, string?)](/reference/api/csharp/aspire.hosting/parameterresourcebuilderextensions/methods.md#addconnectionstring-idistributedapplicationbuilder-string-string) method creates a new [ParameterResource](/reference/api/csharp/aspire.hosting/parameterresource.md) in the application model. The return type of [ParameterResourceBuilderExtensions.AddConnectionString(IDistributedApplicationBuilder, string, string?)](/reference/api/csharp/aspire.hosting/parameterresourcebuilderextensions/methods.md#addconnectionstring-idistributedapplicationbuilder-string-string) is `ApplicationModel.IResourceBuilder`1`. The [ParameterResource](/reference/api/csharp/aspire.hosting/parameterresource.md) type does not implement the [IResourceWithConnectionString](/reference/api/csharp/aspire.hosting/iresourcewithconnectionstring.md).

To work around this issue the [ParameterResourceBuilderExtensions.AddConnectionString(IDistributedApplicationBuilder, string, string?)](/reference/api/csharp/aspire.hosting/parameterresourcebuilderextensions/methods.md#addconnectionstring-idistributedapplicationbuilder-string-string) method wraps the parameter resource in a "surrogate" class which proxies access to the [ParameterResource](/reference/api/csharp/aspire.hosting/parameterresource.md) fields but implements [IResourceWithConnectionString](/reference/api/csharp/aspire.hosting/iresourcewithconnectionstring.md). The [IDistributedApplicationBuilder.CreateResourceBuilder(T)](/reference/api/csharp/aspire.hosting/idistributedapplicationbuilder/methods.md#createresourcebuilder-t) method assists by allowing the creation of a `ApplicationModel.IResourceBuilder`1` without adding another resource to the application model.

```csharp
public static IResourceBuilder<IResourceWithConnectionString> AddConnectionString(this IDistributedApplicationBuilder builder, [ResourceName] string name, string? environmentVariableName = null)
{
    var parameterBuilder = builder.AddParameter(name, _ =>
    {
        return builder.Configuration.GetConnectionString(name) ?? throw new DistributedApplicationException($"Connection string parameter resource could not be used because connection string '{name}' is missing.");
    },
    secret: true,
    connectionString: true);

    var surrogate = new ConnectionStringParameterResource(parameterBuilder.Resource, environmentVariableName);
    return builder.CreateResourceBuilder(surrogate);
}
```