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

Aspire

Namespaces

Type

IAspireComponent<T>

Source

Indicates that the implementing class is an Aspire component that can generate resources for the application. Classes implementing this interface are responsible for generating resources of type T ,

Type parameters

  • T
    The type of resource the component generates.
Method

Generate

IResourceBuilder<T> Generate(AspireStartupContext context, IDistributedApplicationBuilder appBuilder)
Source

Generates and adds a resource to the Aspire distributed application builder.

Parameters

  • context
    The Aspire startup context.
  • appBuilder
    The distributed application builder.

Returns

A resource builder for the generated resource.

Type

IAspireComponent

Source

The base interface for Aspire components. For now this interface does not define any members, but it serves as a marker interface to identify classes that are Aspire components. This allows for future expansion and additional functionality to be added to all Aspire components if needed.

Type

AspireApp

Source

Entry point for running an Aspire application with no specific root module.

Remarks

Use AspireApp.RunAsync(string[]) when the AppHost should use the framework-default NoHostModule and discover Aspire components from the calling assembly. If the caller has a concrete root module type that should participate in compile-time dependency and configuration registration, prefer AspireApp{TModule}.RunAsync(string[]) instead.

Method

RunAsync

Task RunAsync(string[] args)
Source

Runs the Aspire application asynchronously.

Parameters

  • args
    Command-line arguments.

Returns

A task representing the run operation.

Type

AspireApp<TModule>

Source

Entry point for running an Aspire application with a specific root module.

Type parameters

  • TModule
    The type of the root module.

Remarks

Use AspireApp{TModule}.RunAsync(string[]) when the root module is known at compile time and should participate in AppSurface dependency discovery, configuration registration, and host hooks. The new() constraint means TModule is activated by parameterless constructor rather than dependency injection, so keep constructors cheap, deterministic, and free of external side effects. Use AspireApp.RunAsync(string[]) when no root module is needed or module selection is driven by framework defaults. The call delegates to AspireAppStartup{TModule} for host activation.

Method

RunAsync

Task RunAsync(string[] args)
Source

Runs the Aspire application asynchronously with the specified root module.

Parameters

  • args
    Command-line arguments.

Returns

A task representing the run operation.

Type

AppSurfaceDeploymentTargetResource

Source

Represents one artifact-only deployment target in the evaluated Aspire resource graph.

Remarks

The resource has no runtime lifetime or endpoint. It carries provider inputs and a per-pipeline render cache.

Method

GetHostAddressExpression

ReferenceExpression GetHostAddressExpression(EndpointReference endpointReference)
Source

Rejects endpoint projection because artifact-only targets do not expose deployed addresses.

Property

Target

IDeploymentTarget Target { get; } Source

Gets the provider target.

Property

BindingProfile

ParameterResource BindingProfile { get; } Source

Gets the non-secret binding-profile parameter.

Property

SourceRevision

ParameterResource SourceRevision { get; } Source

Gets the non-secret source-revision parameter.

Property

AppHostDirectory

string AppHostDirectory { get; } Source

Gets the trusted AppHost directory.

Property

EnvironmentName

string EnvironmentName { get; } Source

Gets the Aspire-selected environment name.

Property

LastRenderResult

DeploymentRenderResult? LastRenderResult { get; set; } Source

Gets or sets the render result produced by the publish dependency in the current pipeline process.

Remarks

Verification reuses this value only after its declared publish dependency completes; a new AppHost process starts without cached evidence.

Type

AppSurfaceMigrationJobAnnotation

Source

Immutable Aspire annotation projected into one provider-neutral migration-job intent.

Parameters

  • ResourceName
    Canonical logical resource name.
  • Phase
    Explicit deployment phase.
  • Image
    Non-secret immutable image parameter.
  • Command
    Executable without shell parsing.
  • Arguments
    Ordered executable arguments.
  • Execution
    Bounded run-to-completion policy.
  • ConnectionSecret
    Secret-classified parameter retained only by logical name.
  • ConfigurationKey
    Application configuration key populated by the provider secret reference.
  • RequirePrivateNetwork
    Whether the required v1 private-network declaration was made.
Type

AspireDeploymentPipelineAdapter

Source

Isolates the repository-pinned Aspire 13.4.4 experimental deployment-pipeline API.

Method

Register

void Register(IResourceBuilder<IComputeEnvironmentResource> builder, AppSurfaceDeploymentTargetResource resource)
Source

Registers publish and verification factories with their native Aspire dependency relationships.

Parameters

  • builder
    Target resource builder receiving pipeline annotations.
  • resource
    Concrete target resource captured by the step actions.
Method

BuildIntentAsync

Task<DeploymentIntent> BuildIntentAsync(AppSurfaceDeploymentTargetResource targetResource, DistributedApplicationModel model, CancellationToken cancellationToken)
Source

Projects explicitly annotated resources assigned to one target into canonical neutral intent.

Parameters

  • targetResource
    Target whose assigned annotations are selected.
  • model
    Evaluated Aspire model.
  • cancellationToken
    Cancellation observed during non-secret parameter resolution.

Returns

Validated, sorted deployment intent.

Method

CompletePublishAsync

Task CompletePublishAsync(AppSurfaceDeploymentTargetResource resource, DeploymentRenderResult result, Action<string, string> addSummary, IReportingStep reportingStep, CancellationToken cancellationToken)
Source

Reports publish evidence and the no-mutation assurance through Aspire.

Method

VerifyRenderedAsync

Task VerifyRenderedAsync(AppSurfaceDeploymentTargetResource resource, DeploymentRenderResult renderResult, Action<string, string> addSummary, IReportingStep reportingStep, CancellationToken cancellationToken)
Source

Runs shadow parity verification and reports a read-only success or typed failure.

Method

RenderAndWriteAsync

Task<DeploymentRenderResult> RenderAndWriteAsync(AppSurfaceDeploymentTargetResource resource, DistributedApplicationModel model, IServiceProvider services, CancellationToken cancellationToken)
Source

Builds intent, confines the profile, invokes the pure provider renderer, and atomically writes one complete bundle.

Returns

The provider result plus any adapter-owned neutral-intent artifact.

Method

ResolveBindingProfilePath

string ResolveBindingProfilePath(string appHostDirectory, string bindingProfilePath)
Source

Resolves a relative profile path lexically beneath the trusted AppHost directory.

Remarks

The provider loader performs the filesystem-level symbolic-link check before reading.

Type

AspireProfileActivationHostBuilder

Source

Observes resources acquired by one configured profile activation before an unstarted host is returned.

Remarks

Install this forwarding builder before Generic Host defaults and module callbacks. It preserves the selected service-provider object and container type. Its singleton IHost factory receives an idempotent host lease to prevent DI-driven disposal re-entry without wrapping the selected service provider. Configuration sources are decorated only after all configuration callbacks, so callbacks retain their original source collection. Providers and reload registrations returned during framework construction receive shared, idempotent disposal leases: nested roots, failed root construction, detached host configuration and secondary disposal failures cannot cause duplicate leaf disposal. A custom source or service-provider factory owns allocations it does not return; roots explicitly built inside user callbacks remain caller-owned. After Build returns, host-owned files and services are disposed through the host, while the guard retains detached configuration ownership. No hosted service is started by this builder.

Method

ConfigureDefaults

IHostBuilder ConfigureDefaults(string[] args)
Source

Applies the same Generic Host defaults as Host.CreateDefaultBuilder through the observing factory seam.

Parameters

  • args
    The normalized activation arguments.

Returns

This builder, with default provider validation options preserved.

Method

DisposeAsync

ValueTask DisposeAsync()
Source

Joins idempotent asynchronous cleanup, preferring asynchronous host/provider/file disposal when supported.

Returns

A value task that completes after every acquired ownership lease has been attempted.

Remarks

A shared completion is published under the ownership lock before cleanup starts outside that lock, so user disposal code can coordinate with reload registrations on other threads. Calls from that cleanup flow return immediately; independent callers join its completion and observe the same first error. Cleanup continues after secondary errors and rethrows the first error. The activation factory suppresses these errors only when it already has a primary creation failure. Once a host exists, file/provider cleanup follows the host's disposal policy; configuration leases additionally drain detached and partially constructed trees.

Type

AspireStartupContext

Source

Provides context and helper methods during the Aspire application startup process.

Method

Resolve

IResourceBuilder<TResource> Resolve<TResource>(IAspireComponent<TResource> dependency)
Source

Resolves an Aspire resource from a component, ensuring each component is only generated once.

Type parameters

  • TResource
    The type of the resource.

Parameters

  • dependency
    The component providing the resource.

Returns

A resource builder for the resolved resource.

Method

GetPathFromRoot

string GetPathFromRoot(string relativePath)
Source

Combines the constructor's repository root with a trusted repository-relative asset path.

Parameters

  • relativePath
    The asset path, typically relative to the repository root.

Returns

A fully qualified path for repository-relative input, without checking asset existence.

Exceptions

  • ArgumentNullException
    relativePath is null, even if no root was found.
  • InvalidOperationException
    The constructor could not discover a repository root.

Remarks

Retains Path.Combine(string, string) semantics for empty, rooted and parent-traversal inputs; this is path computation, not containment or asset validation. A root is required even for rooted input. Callers check files/directories and own their import or mount errors. The root is never rediscovered here. See the repository asset guide .

Method

FindRepoRoot

string? FindRepoRoot(string? appHostDirectory)
Source

Selects the nearest Git-marked ancestor of a fully qualified AppHost directory, including the anchor itself.

Parameters

  • appHostDirectory
    The source-project anchor; blank or nonabsolute values disable discovery.

Returns

The first Git file/directory ancestor's full path, or null when no usable root is available.

Remarks

Marker contents are not parsed and Git validity is not checked. This single constructor-time walk performs no Git subprocess, existence requirement for the anchor, output/CWD fallback, or repeated path-time discovery. Marker paths use PathUtils.PathUnder to keep each probe beneath its candidate directory.

Type

AspireProfile

Source

A base class for defining an Aspire profile as a CLI command.

Method

GetDependencies

IEnumerable<AspireProfile> GetDependencies()
Source

Gets the dependencies (other profiles) that this profile requires.

Returns

An enumerable of dependent profiles.

Method

GetComponents

IEnumerable<IAspireComponent> GetComponents()
Source

Gets the Aspire components that compose this profile.

Returns

An enumerable of Aspire components.

Method

Compose

void Compose(IDistributedApplicationBuilder appBuilder, CancellationToken cancellationToken)
Source

Composes this profile into an Aspire distributed application builder.

Parameters

  • appBuilder
    The builder that receives the profile graph.
  • cancellationToken
    A token checked before profile enumeration begins and between synchronous composition steps.

Remarks

Components from each profile returned by GetDependencies are resolved in dependency and component enumeration order before this profile's direct GetComponents results. Composition includes only those direct dependencies; it does not recursively traverse their dependencies. Values that do not implement IAspireComponent{TResource} for IResource are ignored. Cancellation is cooperative at the documented checkpoints, and cancellation or another failure does not roll back resources already added to appBuilder .

Property

PassThroughArgs

string[] PassThroughArgs { get; } Source

Gets the command-line arguments to pass through to the Aspire host.

Remarks

Profiles default to an empty argument set so AppSurface command selection remains owned by CliFx. Override this property when a profile intentionally needs to pass known AppHost arguments into DistributedApplicationBuilder . Unknown command-line arguments are not forwarded automatically.

Type

AppSurfaceDeploymentBuilderExtensions

Source

Extends an Aspire resource graph with explicit AppSurface deployment intent.

Method

AddAppSurfaceDeploymentTarget

IResourceBuilder<IComputeEnvironmentResource> AddAppSurfaceDeploymentTarget(this IDistributedApplicationBuilder builder, string name, IDeploymentTarget target, IResourceBuilder<ParameterResource> bindingProfile, IResourceBuilder<ParameterResource> sourceRevision)
Source

Adds one artifact-only deployment target to the native Aspire deployment pipeline.

Parameters

  • builder
    The native Aspire application builder.
  • name
    The unique Aspire compute-environment resource name.
  • target
    The provider compiler and read-only verifier.
  • bindingProfile
    A non-secret parameter containing the provider binding-profile path.
  • sourceRevision
    A non-secret parameter containing a full lowercase source commit.

Returns

The compute environment used with Aspire's WithComputeEnvironment extension.

Remarks

The publish step writes artifacts only. It does not call a cloud API, apply infrastructure, resolve secret values, execute a job, or change traffic. Verification is exposed as the separately named appsurface-gcp-verify step, performs shadow parity for pre-cutover adoption, and is required to remain read-only. After writer cutover, the application-owned release workflow may call the provider target directly with DeploymentParityMode.Owned .

Method

WithAppSurfaceMigrationJob

IResourceBuilder<ProjectResource> WithAppSurfaceMigrationJob(this IResourceBuilder<ProjectResource> builder, Action<AppSurfaceMigrationJobOptions> configure)
Source

Annotates an existing Aspire project as one explicit migration-job intent.

Parameters

  • builder
    The existing project resource builder; no second project resource is created.
  • configure
    Configures immutable image, command, secret reference, and execution bounds.

Returns

The original project builder for chaining.

Remarks

This annotation never reads the connection parameter value. Assign the returned project explicitly with Aspire's WithComputeEnvironment ; unassigned annotations are rejected during publish rather than inferred. Calling this method twice for the same resource is an error.

Type

AppSurfaceMigrationJobOptions

Source

Builds the provider-neutral intent annotation for one existing Aspire project resource.

Method

WithImage

AppSurfaceMigrationJobOptions WithImage(IResourceBuilder<ParameterResource> image)
Source

Uses a non-secret parameter containing a full immutable container image identity.

Method

WithPhase

AppSurfaceMigrationJobOptions WithPhase(DeploymentPhase phase)
Source

Sets the deployment phase. Version 1 supports candidate preparation.

Method

WithCommand

AppSurfaceMigrationJobOptions WithCommand(string command, params string[] arguments)
Source

Sets the executable and ordered arguments without parsing a shell command line.

Method

WithConnectionSecret

AppSurfaceMigrationJobOptions WithConnectionSecret(IResourceBuilder<ParameterResource> secret, string configurationKey)
Source

Records a secret parameter by logical name without resolving its value.

Parameters

  • secret
    An Aspire secret parameter used only as a logical reference.
  • configurationKey
    The application configuration key populated by the provider reference.
Method

RequirePrivateNetwork

AppSurfaceMigrationJobOptions RequirePrivateNetwork()
Source

Requires the provider target to supply private networking. Version 1 supports candidate preparation and requires every migration-job configuration to call this method; otherwise building the annotation throws ASDEPLOY207 .

Method

WithExecutionPolicy

AppSurfaceMigrationJobOptions WithExecutionPolicy(int tasks, int parallelism, int retries, TimeSpan timeout)
Source

Sets explicit task, parallelism, retry, and timeout bounds.

Type

AspireAppStartup<TModule>

Source

Starts an Aspire AppHost with an AppSurface root module that implements IAppSurfaceHostModule .

Type parameters

  • TModule
    The root AppSurface host module type for the Aspire AppHost.

Remarks

AspireAppStartup{TModule} is the Aspire-specific bootstrapper behind AspireApp{TModule}.RunAsync(string[]) . The new() constraint activates the root module with a parameterless constructor before dependency injection is available, so module constructors should avoid service resolution, blocking work, and disposable ownership. Host-module service registrations run through ConsoleStartup{TModule} before ConfigureAdditionalServices discovers Aspire components.

Method

ConfigureAdditionalServices

void ConfigureAdditionalServices(StartupContext context, IServiceCollection services)
Source

Discovers IAspireComponent types from the entry assembly and registers each concrete type as a singleton.

Parameters

  • context
    The AppSurface startup context that supplies the entry assembly to scan.
  • services
    The service collection receiving discovered Aspire component registrations.

Remarks

ConfigureAdditionalServices runs after the root IAppSurfaceHostModule and dependency modules have registered services. Components are registered by concrete type only, not by implemented interfaces, so consumers should resolve concrete component types directly. The registration is startup-only and does not transfer disposal ownership beyond normal container ownership.

Type

AspireProfileActivationLease<TProfile>

Source

Owns the unstarted AppSurface host used to activate one typed Aspire profile.

Type parameters

  • TProfile
    The activated profile type.

Remarks

Construction transfers ownership of the supplied host to the lease. Callers may use Profile and Services only while the lease is active; profile dependencies may come from the owned service provider. Disposal is idempotent, chooses asynchronous host disposal when available, and invalidates service access. Callers must not dispose the owned host separately or use the profile after lease disposal begins.

Method

DisposeHostAsync

Task DisposeHostAsync(IHost host)
Source

Disposes a host asynchronously when its concrete implementation supports asynchronous cleanup.

Parameters

  • host
    The host to dispose.

Returns

A task that completes after host cleanup.

Property

Profile

TProfile Profile { get; } Source

Gets the activated profile while the lease and its constructor-injected services remain valid.

Property

Services

IServiceProvider Services { get; } Source

Gets the owned activation host's service provider before disposal begins.

Exceptions

  • ObjectDisposedException
    The lease is disposing or has been disposed.
Type

AspireProfileActivator

Source

Activates Aspire profiles through the same AppSurface host composition used at runtime.

Method

ActivateAsync

Task<AspireProfileActivationLease<TProfile>> ActivateAsync<TAppHost, TModule, TProfile>(CancellationToken cancellationToken)
Source

Builds an unstarted AppSurface host for TAppHost and resolves one typed Aspire profile.

Type parameters

  • TAppHost
    The public generated AppHost marker type whose assembly supplies activation identity.
  • TModule
    The public AppSurface module used to compose the activation host.
  • TProfile
    The public concrete Aspire profile resolved from the activation host.

Parameters

  • cancellationToken
    A token observed before host creation and around profile resolution.

Returns

A lease that owns the unstarted host, profile, and service provider. The caller must dispose the returned lease.

Exceptions

  • OperationCanceledException
    Cancellation is requested before activation completes.

Remarks

Activation uses empty command-line arguments and pins the entry-point assembly to TAppHost . The host is never started. If activation or cancellation prevents ownership from being returned, the method disposes the host before propagating the primary failure.

Method

ActivateConfiguredAsync

Task<AspireProfileActivationLease<TProfile>> ActivateConfiguredAsync<TAppHost, TModule, TProfile>(Action<IConfigurationBuilder>? configureConfiguration, Action<IServiceCollection>? configureServices, CancellationToken cancellationToken)
Source

Activates a profile after final per-call configuration and services callbacks with early ownership observation.

Type parameters

  • TAppHost
    The marker whose assembly pins activation identity.
  • TModule
    The module composed through ordinary AppSurface startup.
  • TProfile
    The profile resolved after both callbacks.

Parameters

  • configureConfiguration
    The optional final application-configuration callback.
  • configureServices
    The optional final service-collection callback.
  • cancellationToken
    A token checked around callbacks and profile construction.

Returns

A lease owning the unstarted host and detached or partially constructed configuration.

Remarks

The selected provider factory is retained, including later container precedence. Callback exceptions are preserved for the Testing factory's phase diagnostics. Cleanup and logging failures cannot replace them.

Type

AspireExceptionUtilities

Source

Classifies the process-fatal exception families used by Aspire profile activation and testing cleanup paths.

Remarks

This deliberately narrow helper recognizes OutOfMemoryException , StackOverflowException , and AccessViolationException . It is not a general exception-handling policy for AppSurface callers.

Method

IsProcessFatal

bool IsProcessFatal(Exception exception)
Source

Determines whether an exception is an OutOfMemoryException , StackOverflowException , or AccessViolationException that should propagate immediately.

Parameters

  • exception
    The exception to classify.

Returns

true for process-fatal exception types; otherwise false .