Class AspireTestHostBuilder<TAppHost>

Namespace

XBullet.EasyTesting.Aspire

Assembly

XBullet.EasyTesting.Aspire.dll

Configures and starts an isolated Aspire distributed application.

public sealed class AspireTestHostBuilder<TAppHost> where TAppHost : class

Type Parameters

TAppHost

The AppHost entry-point type used to create the distributed application.

Inheritance

object

AspireTestHostBuilder<TAppHost>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This mutable builder is not thread-safe and can start only one application. A start attempt consumes the builder even when startup fails.

Methods

ConfigureAppHost(Action<IDistributedApplicationTestingBuilder>)

Configures the native distributed application testing builder.

public AspireTestHostBuilder<TAppHost> ConfigureAppHost(Action<IDistributedApplicationTestingBuilder> configure)

Parameters

configure Action<IDistributedApplicationTestingBuilder>

A non-null callback invoked once, in registration order, after the native testing builder is created and before the application is built. The callback may configure the builder but must not retain or dispose it because the started test application owns it.

Returns

AspireTestHostBuilder<TAppHost>

This builder, for chaining. The callback is retained until startup.

RunAsync(Func<AspireTestApplication<TAppHost>, CancellationToken, Task>, CancellationToken)

Runs a distributed test, attaching diagnostics to any failure.

public Task RunAsync(Func<AspireTestApplication<TAppHost>, CancellationToken, Task> test, CancellationToken cancellationToken = default)

Parameters

test Func<AspireTestApplication<TAppHost>, CancellationToken, Task>

A non-null asynchronous callback invoked once with the running application and the caller's cancellation token. The application is owned by this method; the callback must not dispose or retain it beyond completion.

cancellationToken CancellationToken

A token used during startup and passed unchanged to test. The default token does not request cancellation. Failure diagnostics and cleanup are attempted without this token.

Returns

Task

A task that completes after the callback and application cleanup. If the callback fails, current diagnostics are attached to the exception before it is rethrown.

StartAsync(CancellationToken)

Starts the AppHost and waits for all configured resources to become healthy.

public Task<AspireTestApplication<TAppHost>> StartAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A token that cancels AppHost creation, startup, and resource waits. The default token does not request cancellation. The configured startup timeout independently cancels those operations.

Returns

Task<AspireTestApplication<TAppHost>>

A task whose result owns the running application and native testing builder. The caller must asynchronously dispose the result. On failure, partially created resources are disposed.

Remarks

Caller-requested cancellation is reported as cancellation. Expiry of the configured startup timeout is reported as a TimeoutException.

WaitForResource(string)

Adds a resource that must be healthy before the test application is returned.

public AspireTestHostBuilder<TAppHost> WaitForResource(string resourceName)

Parameters

resourceName string

The non-empty AppHost resource name. Duplicate names are ignored using an ordinal, case-insensitive comparison.

Returns

AspireTestHostBuilder<TAppHost>

This builder, for chaining.

WithArguments(params string[])

Adds command-line arguments passed to the AppHost entry point.

public AspireTestHostBuilder<TAppHost> WithArguments(params string[] arguments)

Parameters

arguments string[]

The arguments to append in order. The array and its elements must be non-null; empty strings and an empty array are accepted.

Returns

AspireTestHostBuilder<TAppHost>

This builder, for chaining. The supplied array is not retained.

WithMaximumDiagnosticLinesPerResource(int)

Sets the maximum number of recent log lines retained per diagnostic resource.

public AspireTestHostBuilder<TAppHost> WithMaximumDiagnosticLinesPerResource(int maximumLines)

Parameters

maximumLines int

The non-negative number of lines retained for each resource. The default is 500 lines; zero disables log capture, and older lines are discarded first.

Returns

AspireTestHostBuilder<TAppHost>

This builder, for chaining.

WithStartupTimeout(TimeSpan)

Sets the maximum time allowed for AppHost and resource readiness.

public AspireTestHostBuilder<TAppHost> WithStartupTimeout(TimeSpan timeout)

Parameters

timeout TimeSpan

A positive duration covering AppHost creation, startup, and all configured resource waits. The default is two minutes.

Returns

AspireTestHostBuilder<TAppHost>

This builder, for chaining.