IDistributedApplicationBuilder Methods
DistributedApplication. T to the distributed application. public interface IDistributedApplicationBuilder{ public abstract IResourceBuilder<T> AddResource<T>( T resource) { // ... }}Parameters
resource T The resource to add. Returns
IResourceBuilder<T> A builder for configuring the added resource. Exceptions
DistributedApplicationException Thrown when a resource with the same name already exists. Remarks
The IDistributedApplicationBuilder.AddResource 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.
ContainerResourceBuilderExtensions.AddContainer method which makes use of the IDistributedApplicationBuilder.AddResource method to add a container resource to the application. In .NET Aspire the pattern for defining new resources is to include a method that extends IDistributedApplicationBuilder and and then constructs a resource derived from IResource and adds it to the application model using the IDistributedApplicationBuilder.AddResource method. Other extension methods (such as ContainerResourceBuilderExtensions.WithImage in this case) can be chained to configure the resource as desired. 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);}DistributedApplication instance. This can only be called once. public interface IDistributedApplicationBuilder{ public abstract DistributedApplication Build() { // ... }}Returns
DistributedApplication A new DistributedApplication instance. Remarks
Callers of the IDistributedApplicationBuilder.Build method should only call it once. are responsible for the lifecycle of the DistributedApplication instance that is returned. Note that the DistributedApplication 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.
public interface IDistributedApplicationBuilder{ public abstract IResourceBuilder<T> CreateResourceBuilder<T>( T resource) { // ... }}Parameters
resource T An existing resource. Returns
IResourceBuilder<T> A resource builder. Remarks
The IDistributedApplicationBuilder.CreateResourceBuilder 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 .NET Aspire where the original resource builder cannot be referenced directly. Using the IDistributedApplicationBuilder.CreateResourceBuilder 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 collection. Not all changes to annotations will be effective depending on what stage of the lifecycle the app host is in. See IDistributedApplicationLifecycleHook for more details.
The following example shows the implementation of the ParameterResourceBuilderExtensions.AddConnectionString extension method.
The ParameterResourceBuilderExtensions.AddConnectionString method creates a new ParameterResource in the application model. The return type of ParameterResourceBuilderExtensions.AddConnectionString is ApplicationModel.IResourceBuilder`1. The ParameterResource type does not implement the IResourceWithConnectionString.
To work around this issue the ParameterResourceBuilderExtensions.AddConnectionString method wraps the parameter resource in a "surrogate" class which proxies access to the ParameterResource fields but implements IResourceWithConnectionString. The IDistributedApplicationBuilder.CreateResourceBuilder method assists by allowing the creation of a ApplicationModel.IResourceBuilder`1 without adding another resource to the application model.
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);}