DistributedApplicationBuilderExtensions Methods

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

Methods

Docs Reference Search C# APIs Aspire.Hosting DistributedApplicationBuilderExtensions Methods

Class Methods 2 members

Extensions for IDistributedApplicationBuilder.

CreateResourceBuilder(IDistributedApplicationBuilder, string) extension IResourceBuilder<T>

Creates a new resource builder based on the name of an existing resource.

public static class DistributedApplicationBuilderExtensions
{
    public static IResourceBuilder<T> CreateResourceBuilder<T>(
        this IDistributedApplicationBuilder builder,
        string name)
    {
        // ...
    }
}

DistributedApplicationBuilderExtensions.cs#L63-L76

Parameters

builder IDistributedApplicationBuilder The distributed application builder.

name string The name of an existing resource.

Returns

IResourceBuilder<T> A resource builder.

Remarks

The DistributedApplicationBuilderExtensions.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 based on its name.

This method is typically used when testing .NET Aspire applications where the original resource builder cannot be referenced directly. Using the DistributedApplicationBuilderExtensions.CreateResourceBuilder method allows for easier mutation of resources within the test scenario.

In this example, the MyAspireApp.AppHost project has previously added a Redis resource named "cache" to the application host. The test project, MyAspireApp.AppHost.Tests, modifies that resource so that it sleeps instead of starting the Redis container. This allows the test case to verify that the application's health check returns an 'Unhealthy' status when the Redis resource is not available.

[Fact]
public async Task GetWebResourceHealthReturnsUnhealthyWhenRedisUnavailable()
{
    // Arrange
    var appHost = await DistributedApplicationTestingBuilder
        .CreateAsync<Projects.MyAspireApp_AppHost>(
        );

    // Get the "cache" resource and modify it to sleep for 1 day instead of starting Redis.
    var redis = appHost.CreateResourceBuilder<ContainerResource>("cache"));
    redis.WithEntrypoint("sleep 1d");

    await using var app = await appHost.BuildAsync();
    await app.StartAsync();

    // Act
    var httpClient = new HttpClient { BaseAddress = app.GetEndpoint(
        "webfrontend") };
    var response = await httpClient.GetAsync("/health");

    // Assert
    Assert.Equal(HttpStatusCode.ServiceUnavailable, response.StatusCode);
    Assert.Equal("Unhealthy", await response.Content.ReadAsStringAsync());
}

TryCreateResourceBuilder(IDistributedApplicationBuilder, string, IResourceBuilder<T>) extension bool

Attempts to create a new resource builder based on the name of an existing resource.

public static class DistributedApplicationBuilderExtensions
{
    public static bool TryCreateResourceBuilder<T>(
        this IDistributedApplicationBuilder builder,
        string name,
        out IResourceBuilder<T>? resourceBuilder)
    {
        // ...
    }
}

DistributedApplicationBuilderExtensions.cs#L93-L104

Parameters

builder IDistributedApplicationBuilder The distributed application builder.

name string The name of an existing resource.

resourceBuilder IResourceBuilder<T> When this method returns, contains the resource builder if the resource was found and is of the correct type; otherwise, null.

Returns

bool true if the resource was found and is of the correct type; otherwise, false.

Remarks

This method is similar to DistributedApplicationBuilderExtensions.CreateResourceBuilder but returns false instead of throwing an exception when the resource is not found or is not of the correct type.