Testing
AppSurfaceAspireTestingBuilder
SourceCreates deterministic Aspire testing builders from AppSurface profile types.
Remarks
This factory activates the selected profile through AppSurface dependency injection but never starts the activation host or invokes the AppHost entry point. The selected profile must not declare CliFx option or positional-parameter bindings because this typed path intentionally has no command-line binding phase.
CreateAsync
Task<AppSurfaceAspireProfileTestingBuilder> CreateAsync<TAppHost, TModule, TProfile>(CancellationToken cancellationToken = default)
Source
Creates a configurable Aspire testing builder for a typed AppSurface profile.
Type Parameters
TAppHostThe generated publicProjects.*marker for the AppHost project.TModuleThe public AppSurface root module in the AppHost assembly.TProfileThe public AppSurface Aspire profile selected for the test graph.
Parameters
cancellationTokenA token checked between synchronous activation and composition steps.
Returns
A builder that the caller may customize once before calling BuildAsync.
Exceptions
InvalidOperationExceptionThe types or generated marker are invalid, the profile uses CliFx member binding, or activation or composition fails. The exception identifies the affected type and preserves the original failure as its inner exception.OperationCanceledExceptionThe operation is cancelled.
AppSurfaceAspireProfileTestingBuilder
SourceAdapts a composed AppSurface profile to Aspire's configurable testing-builder contract.
Remarks
Customize this builder before its single BuildAsync(CancellationToken) call. After a successful build, all builder access and a second build are rejected. Dispose the returned DistributedApplication before disposing this builder so stop and disposal failures remain at the application call site. As a fallback, builder disposal disposes the application before profile activation services. After a process-fatal build failure, builder disposal also makes a best effort to release any captured partial Aspire provider. Both disposal methods are idempotent; disposal during a build is rejected.
BuildAsync
Task<DistributedApplication> BuildAsync(CancellationToken cancellationToken = default)
Source
Builds the composed distributed application exactly once.
Parameters
cancellationTokenA token checked before and immediately after Aspire's synchronous build.
Returns
The built application. The caller controls starting, stopping, and primary disposal.
Exceptions
InvalidOperationExceptionThe builder is already building, built, faulted, or disposing.ObjectDisposedExceptionThe builder has been disposed.OperationCanceledExceptionThe operation is cancelled; any unreturned application is disposed.
Remarks
Immediately before delegating to Aspire, this method attempts to install an internal ownership lease around Aspire's root-provider host factory. A successful build transfers provider ownership to the returned application. A non-process-fatal host-construction failure disposes the captured partial provider before profile activation services, without replacing the original failure with non-fatal cleanup errors. A process-fatal failure retains the captured provider for best-effort cleanup when this builder is later disposed. A consumer-selected Aspire version with an unfamiliar host registration continues without this additional cleanup and emits a trace warning.
Dispose
void Dispose()
Source
Releases the profile activation host synchronously.
Exceptions
InvalidOperationExceptionA build is in progress.
Remarks
After a successful build, this method disposes the application before profile activation services. After a process-fatal build failure, it instead attempts to dispose the captured partial provider before activation.
DisposeAsync
ValueTask DisposeAsync()
Source
Releases the profile activation host asynchronously.
Returns
A value task that completes after activation services are disposed.
Exceptions
InvalidOperationExceptionA build is in progress.
Remarks
After a successful build, this method disposes the application before profile activation services. After a process-fatal build failure, it instead attempts to dispose the captured partial provider before activation.
AspireBuildServiceProviderLease
SourceCaptures the root service provider created while Aspire resolves its host so a failed build can release it.
Remarks
Aspire 13.4.4 registers IHost as a singleton factory. The factory receives the root provider before host construction can fail, while DistributedApplicationBuilder.Build() does not otherwise expose that partial provider. This lease decorates the verified unkeyed registration shape when it is present and ignores unrelated keyed IHost registrations. If a consumer-selected Aspire version changes that shape, installation warns and yields to Aspire without the additional failed-build cleanup. A successful build transfers provider ownership to the returned distributed application by calling Release. Non-process-fatal failures dispose the lease immediately; process-fatal failures retain it for best-effort cleanup when the testing builder is later disposed.
TryInstall
AspireBuildServiceProviderLease? TryInstall(IServiceCollection services, Action<string>? warningSink = null)
Source
Attempts to decorate Aspire's verified host factory and returns the lease that will capture its root provider.
Parameters
servicesThe mutable Aspire builder service collection immediately before build.warningSinkReceives a compatibility warning when the verified registration shape is absent.
Returns
A lease that owns a captured provider until released after a successful build, or null when the consumer-selected Aspire version does not expose the verified registration shape.
Release
void Release()
Source
Transfers ownership of any captured provider to the successfully built distributed application.
DisposeAsync
ValueTask DisposeAsync()
Source
Releases a provider captured before host construction failed.
Returns
A value task that completes after asynchronous or synchronous provider cleanup.
AspireTestingDiagnostics
SourceEmits best-effort compatibility and cleanup warnings without changing primary build behavior.
TryWrite
2 overloads
void TryWrite(Action<string>? warningSink, string message)
Source
Writes a warning through the supplied sink and suppresses non-process-fatal diagnostic failures.
Parameters
warningSinkThe optional warning destination.messageThe warning message.
void TryWrite(Action<string>? warningSink, Func<string> messageFactory)
Source
Creates and writes a warning inside the diagnostic boundary, suppressing non-process-fatal formatting and sink failures.
Parameters
warningSinkThe optional warning destination.messageFactoryCreates the warning message only when a destination is configured.
TraceWarning
void TraceWarning(string message)
Source
Writes a warning to the process trace listeners.
Parameters
messageThe warning message.