AppSurface Search
Section API Reference
API Reference Language: C# Component: Aspire Audience: developer

Testing

Type

AspireTestingDiagnostics

Source

Emits best-effort compatibility and cleanup warnings without changing primary build behavior.

Method

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

  • warningSink
    The optional warning destination.
  • message
    The 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

  • warningSink
    The optional warning destination.
  • messageFactory
    Creates the warning message only when a destination is configured.
Method

TraceWarning

void TraceWarning(string message)
Source

Writes a warning to the process trace listeners.

Parameters

  • message
    The warning message.
Type

AppSurfaceAspireTestingBuilder

Source

Creates 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.

Method

CreateAsync

Task<AppSurfaceAspireProfileTestingBuilder> CreateAsync<TAppHost, TModule, TProfile>(CancellationToken cancellationToken = default)
Source

Creates a configurable Aspire testing builder for a typed AppSurface profile.

Type parameters

  • TAppHost
    The generated public Projects.* marker for the AppHost project.
  • TModule
    The public AppSurface root module in the AppHost assembly.
  • TProfile
    The public AppSurface Aspire profile selected for the test graph.

Parameters

  • cancellationToken
    A token checked between synchronous activation and composition steps.

Returns

A builder that the caller may customize once before calling BuildAsync .

Exceptions

  • InvalidOperationException
    The 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.
  • OperationCanceledException
    The operation is cancelled.
Type

AppSurfaceAspireProfileTestingBuilder

Source

Adapts 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.

Method

BuildAsync

Task<DistributedApplication> BuildAsync(CancellationToken cancellationToken = default)
Source

Builds the composed distributed application exactly once.

Parameters

  • cancellationToken
    A token checked before and immediately after Aspire's synchronous build.

Returns

The built application. The caller controls starting, stopping, and primary disposal.

Exceptions

  • InvalidOperationException
    The builder is already building, built, faulted, or disposing.
  • ObjectDisposedException
    The builder has been disposed.
  • OperationCanceledException
    The 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.

Method

Dispose

void Dispose()
Source

Releases the profile activation host synchronously.

Exceptions

  • InvalidOperationException
    A 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.

Method

DisposeAsync

ValueTask DisposeAsync()
Source

Releases the profile activation host asynchronously.

Returns

A value task that completes after activation services are disposed.

Exceptions

  • InvalidOperationException
    A 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.

Type

AspireBuildServiceProviderLease

Source

Captures 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.

Method

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

  • services
    The mutable Aspire builder service collection immediately before build.
  • warningSink
    Receives 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.

Method

Release

void Release()
Source

Transfers ownership of any captured provider to the successfully built distributed application.

Method

DisposeAsync

ValueTask DisposeAsync()
Source

Releases a provider captured before host construction failed.

Returns

A value task that completes after asynchronous or synchronous provider cleanup.