Exclude the resource from MCP operations using the Aspire MCP server. The resource is excluded from results that return resources, console logs and telemetry.
Subscribes to the BeforeStartEvent and invokes the specified callback when an HTTPS certificate is determined to be available for the resource. This is used to conditionally update endpoint URI schemes or perform other HTTPS-related configuration at startup.
callbackAction<HttpsEndpointUpdateCallbackContext>The callback to invoke when HTTPS is enabled. Receives an HttpsEndpointUpdateCallbackContext providing access to the service provider, resource, and application model.
This method is useful when a resource should wait until another has started running. This can help reduce errors in logs during local development where dependency resources.
Some resources automatically register health checks with the application host container. For these resources, calling ResourceBuilderExtensions.WaitFor also results in the resource being blocked from starting until the health checks associated with the dependency resource return HealthStatus.Healthy.
This method is useful when a resource should wait until another has started running. This can help reduce errors in logs during local development where dependency resources.
Some resources automatically register health checks with the application host container. For these resources, calling ResourceBuilderExtensions.WaitFor also results in the resource being blocked from starting until the health checks associated with the dependency resource return HealthStatus.Healthy.
The waitBehavior parameter can be used to control the behavior of the wait operation. When WaitBehavior.WaitOnResourceUnavailable is specified, the wait operation will continue to wait until the resource becomes healthy. This is the default behavior with the ResourceBuilderExtensions.WaitFor overload.
This method is useful when a resource should wait until another has completed. A common usage pattern would be to include a console application that initializes the database schema or performs other one off initialization tasks.
Note that this method has no impact at deployment time and only works for local development.
Wait for database initialization app to complete running.
var builder =DistributedApplication.CreateBuilder(args);
var pgsql =builder.AddPostgres("postgres");
var dbprep =builder.AddProject<Projects.DbPrepApp>("dbprep")
This method is useful when a resource should wait until another has started running but doesn't need to wait for health checks to pass. This can help enable initialization scenarios where services need to start before health checks can pass.
Unlike ResourceBuilderExtensions.WaitFor, this method only waits for the dependency resource to enter the Running state and ignores any health check annotations associated with the dependency resource.
Start message queue before starting the worker service, but don't wait for health checks.
var builder =DistributedApplication.CreateBuilder(args);
This method is useful when a resource should wait until another has started running but doesn't need to wait for health checks to pass. This can help enable initialization scenarios where services need to start before health checks can pass.
Unlike ResourceBuilderExtensions.WaitFor, this method only waits for the dependency resource to enter the Running state and ignores any health check annotations associated with the dependency resource.
The waitBehavior parameter can be used to control the behavior of the wait operation. When WaitBehavior.WaitOnResourceUnavailable is specified, the wait operation will continue to wait until the resource enters the Running state. This is the default behavior with the ResourceBuilderExtensions.WaitForStart overload.
callbackAction<CommandLineArgsCallbackContext>A callback that allows for deferred execution for computing arguments. This runs after resources have been allocated by the orchestrator and allows access to other resources to resolve computed data, e.g. connection strings, ports.
callbackFunc<CommandLineArgsCallbackContext, Task>An asynchronous callback that allows for deferred execution for computing arguments. This runs after resources have been allocated by the orchestrator and allows access to other resources to resolve computed data, e.g. connection strings, ports.
Adds a CertificateAuthorityCollectionAnnotation to the resource annotations to associate a certificate authority collection with the resource. This is used to configure additional trusted certificate authorities for the resource. Custom certificate trust is only applied in run mode; in publish mode resources will use their default certificate trust behavior.
certificateAuthorityCollectionIResourceBuilder<CertificateAuthorityCollection>Additional certificates in a CertificateAuthorityCollection to treat as trusted certificate authorities for the resource.
Adds a CertificateTrustConfigurationCallbackAnnotation to the resource annotations to associate a callback that is invoked when a resource needs to configure itself for custom certificate trust. May be called multiple times to register additional callbacks to append additional configuration. Custom certificate trust is only applied in run mode; in publish mode resources will use their default certificate trust behavior.
callbackFunc<CertificateTrustConfigurationCallbackAnnotationContext, Task>The callback to invoke when a resource needs to configure itself for custom certificate trust.
Sets the CertificateTrustScope for custom certificate authorities associated with the resource. The scope specifies how custom certificate authorities should be applied to a resource at run time in local development scenarios. Custom certificate trust is only applied in run mode; in publish mode resources will use their default certificate trust behavior.
The default scope if not overridden is CertificateTrustScope.Append which means that custom certificate authorities should be appended to the default trusted certificate authorities for the resource. Setting the scope to CertificateTrustScope.Override indicates the set of certificates in referenced CertificateAuthorityCollection (and optionally Aspire developer certificiates) should be used as the exclusive source of trust for a resource. In all cases, this is a best effort implementation as not all resources support full customization of certificate trust. Set the scope for custom certificate authorities to override the default trusted certificate authorities for a container resource.
var caCollection =builder.AddCertificateAuthorityCollection("my-cas")
namestringThe name of the command. The name uniquely identifies the command.
displayNamestringThe display name visible in UI.
executeCommandFunc<ExecuteCommandContext, Task<ExecuteCommandResult>> A callback that is executed when the command is executed. The callback is run inside the Aspire host. The callback result is used to indicate success or failure in the UI.
commandOptionsCommandOptions?optionalOptional configuration for the command.
The WithCommand method is used to add commands to the resource. Commands are displayed in the dashboard and can be executed by a user using the dashboard UI.
When a command is executed, the executeCommand callback is called and is run inside the Aspire host.
namestringThe name of the command. The name uniquely identifies the command.
displayNamestringThe display name visible in UI.
executeCommandFunc<ExecuteCommandContext, Task<ExecuteCommandResult>> A callback that is executed when the command is executed. The callback is run inside the Aspire host. The callback result is used to indicate success or failure in the UI.
A callback that is used to update the command state. The callback is executed when the command's resource snapshot is updated.
If a callback isn't specified, the command is always enabled.
displayDescriptionstring?optional Optional description of the command, to be shown in the UI. Could be used as a tooltip. May be localized.
parameterobject?optional Optional parameter that configures the command in some way. Clients must return any value provided by the server when invoking the command.
confirmationMessagestring?optional When a confirmation message is specified, the UI will prompt with an OK/Cancel dialog and the confirmation message before starting the command.
The WithCommand method is used to add commands to the resource. Commands are displayed in the dashboard and can be executed by a user using the dashboard UI.
When a command is executed, the executeCommand callback is called and is run inside the Aspire host.
Adds a connection property annotation to the resource being built. Any resource referencing this resource will get this connection property included in its environment variables.
builderIResourceBuilder<T>The resource builder to which the connection property annotation will be added. Cannot be null.
namestringThe name of the connection property to annotate. Cannot be null.
valueReferenceExpressionThe value of the connection property, specified as a reference expression.
Returns
IResourceBuilder<T>The same resource builder instance with the connection property annotation applied.
Remarks
Use this method to associate a named connection property with a resource during its construction. This is typically used to provide connection-related metadata for resources that require environment-specific configuration.
Adds a connection property annotation to the resource being built. Any resource referencing this resource will get this connection property included in its environment variables.
launchConfigurationProducerFunc<string, TLaunchConfiguration>A callback that receives the launch mode and produces the complete launch configuration handed to the IDE.
launchConfigurationTypestringThe type tag of the launch configuration sent to the IDE.
ArgumentExceptionTLaunchConfiguration is a Tasks.Task or Tasks.ValueTask. Use an asynchronous overload instead so the task result, rather than the task itself, becomes the launch configuration.
Remarks
Registering debug support is synchronous. Aspire invokes launchConfigurationProducer later only for executable creations where this debug-support annotation is active, including restarts and replicas. The callback does not run for unsupported debug sessions, publish mode, or inactive annotations superseded by a later SupportsDebuggingAnnotation.
Use this overload when producing the launch configuration requires asynchronous work. Aspire invokes the producer after resolving the execution configuration and may invoke it several times for the same resource.
launchConfigurationProducerFunc<LaunchConfigurationCallbackContext, Task<TLaunchConfiguration>> A callback that receives the resolved environment variables and asynchronously produces the complete launch configuration handed to the IDE.
launchConfigurationTypestringThe type tag of the launch configuration sent to the IDE.
Aspire invokes launchConfigurationProducer after resolving the execution configuration for each executable creation. A producer that completes synchronously should return its result with Task.FromResult. Process execution does not generally require a producer, but Aspire can still invoke a supported non- project producer for a process executable so it can contribute launch metadata.
Examples
Produce a launch configuration using a resolved environment variable:
Indicates whether developer certificates should be treated as trusted certificate authorities for the resource at run time. Currently this indicates trust for the ASP.NET Core developer certificate. The developer certificate will only be trusted when running in local development scenarios; in publish mode resources will use their default certificate trust.
The ResourceBuilderExtensions.WithEndpoint method allows developers to mutate any aspect of an endpoint annotation. Note that changing one value does not automatically change other values to compatible/consistent values. For example setting the EndpointAnnotation.Protocol property of the endpoint annotation in the callback will not automatically change the EndpointAnnotation.UriScheme. All values should be set in the callback if the defaults are not acceptable.
Configure an endpoint to use UDP.
var builder =DistributedApplication.Create(args);
var container =builder.AddContainer("mycontainer","myimage")
.WithEndpoint("myendpoint", e =>{
e.Port=9998;
e.TargetPort=9999;
e.Protocol=ProtocolType.Udp;
e.UriScheme="udp";
});
This method is not available in polyglot AppHosts. Use the callback-based endpoint mutation export instead.
Exposes an endpoint on a resource. A reference to this endpoint can be retrieved using ResourceBuilderExtensions.GetEndpoint. The endpoint name will be the scheme name if not specified.
portint?optionalAn optional port. This is the port that will be given to other resource to communicate with this resource.
targetPortint?optionalThis is the port the resource is listening on. If the endpoint is used for the container, it is the container port.
schemestring?optionalAn optional scheme e.g. (http/https). Defaults to the protocol argument if it is defined or "tcp" otherwise.
namestring?optionalAn optional name of the endpoint. Defaults to the scheme name if not specified.
envstring?optionalAn optional name of the environment variable that will be used to inject the targetPort. If the target port is null one will be dynamically generated and assigned to the environment variable.
isProxiedbool?optionalSpecifies if the endpoint will be proxied by DCP. Defaults to null.
isExternalbool?optionalIndicates that this endpoint should be exposed externally at publish time.
protocolProtocolType?optionalNetwork protocol: TCP or UDP are supported today, others possibly in future.
portint?An optional port. This is the port that will be given to other resource to communicate with this resource.
targetPortint?This is the port the resource is listening on. If the endpoint is used for the container, it is the container port.
schemestring?An optional scheme e.g. (http/https). Defaults to the protocol argument if it is defined or "tcp" otherwise.
namestring?An optional name of the endpoint. Defaults to the scheme name if not specified.
envstring?An optional name of the environment variable that will be used to inject the targetPort. If the target port is null one will be dynamically generated and assigned to the environment variable.
isProxiedboolSpecifies if the endpoint will be proxied by DCP.
isExternalbool?Indicates that this endpoint should be exposed externally at publish time.
protocolProtocolType?Network protocol: TCP or UDP are supported today, others possibly in future.
DistributedApplicationExceptionThrows an exception if an endpoint with the same name already exists on the specified resource.
Remarks
This overload preserves binary compatibility for callers compiled against the previous boolisProxied signature. New source that omits isProxied binds to the nullable overload where omission is represented as null.
Exposes an endpoint on a resource. This endpoint reference can be retrieved using ResourceBuilderExtensions.GetEndpoint. The endpoint name will be the scheme name if not specified.
portint?An optional port. This is the port that will be given to other resource to communicate with this resource.
targetPortint?This is the port the resource is listening on. If the endpoint is used for the container, it is the container port.
schemestring?An optional scheme e.g. (http/https). Defaults to "tcp" if not specified.
namestring?An optional name of the endpoint. Defaults to the scheme name if not specified.
envstring?An optional name of the environment variable that will be used to inject the targetPort. If the target port is null one will be dynamically generated and assigned to the environment variable.
isProxiedbool?Specifies if the endpoint will be proxied by DCP. Defaults to null.
isExternalbool?Indicates that this endpoint should be exposed externally at publish time.
Exposes an endpoint on a resource. This endpoint reference can be retrieved using ResourceBuilderExtensions.GetEndpoint. The endpoint name will be the scheme name if not specified.
portint?An optional port. This is the port that will be given to other resource to communicate with this resource.
targetPortint?This is the port the resource is listening on. If the endpoint is used for the container, it is the container port.
schemestring?An optional scheme e.g. (http/https). Defaults to "tcp" if not specified.
namestring?An optional name of the endpoint. Defaults to the scheme name if not specified.
envstring?An optional name of the environment variable that will be used to inject the targetPort. If the target port is null one will be dynamically generated and assigned to the environment variable.
isProxiedboolSpecifies if the endpoint will be proxied by DCP.
isExternalbool?Indicates that this endpoint should be exposed externally at publish time.
DistributedApplicationExceptionThrows an exception if an endpoint with the same name already exists on the specified resource.
Remarks
This overload preserves binary compatibility for callers compiled against the previous boolisProxied signature. New source that omits isProxied binds to the nullable overload where omission is represented as null.
Set whether a resource can use proxied endpoints or whether they should be disabled for all endpoints belonging to the resource. If set to false, endpoints belonging to the resource will ignore the configured proxy settings and run proxy-less.
This method is intended to support scenarios with persistent lifetime resources where it is desirable for the resource to be accessible over the same port whether the Aspire application is running or not. Proxied endpoints bind ports that are only accessible while the Aspire application is running. The user needs to be careful to ensure that endpoints are using unique ports when disabling proxy support as by default for proxy-less endpoints, Aspire will allocate the target port as the host port, which will increase the chance of port conflicts.
This overload enables polyglot hosts to set environment variables using dynamic expressions that reference endpoints, parameters, and other value providers.
callbackFunc<string>A callback that allows for deferred execution of a specific environment variable. This runs after resources have been allocated by the orchestrator and allows access to other resources to resolve computed data, e.g. connection strings, ports.
callbackAction<EnvironmentCallbackContext>A callback that allows for deferred execution for computing many environment variables. This runs after resources have been allocated by the orchestrator and allows access to other resources to resolve computed data, e.g. connection strings, ports.
callbackFunc<EnvironmentCallbackContext, Task>A callback that allows for deferred execution for computing many environment variables. This runs after resources have been allocated by the orchestrator and allows access to other resources to resolve computed data, e.g. connection strings, ports.
Use this method to hide resources that are implementation details and should never be displayed by default. Hidden resources can still be accessed directly by their name, by using Show hidden resources toggle in the dashboard or by using aspire describe --include-hidden from the CLI.
This method is useful for one-off resources such as setup scripts, migrations, or build steps that should remain visible while running and then be hidden after successful completion. Hidden resources can still be accessed directly by their name, by using Show hidden resources toggle in the dashboard or by using aspire describe --include-hidden from the CLI.
This method is useful for one-off resources such as setup scripts, migrations, or build steps that should remain visible while running and then be hidden after successful completion. Hidden resources can still be accessed directly by their name, by using Show hidden resources toggle in the dashboard or by using aspire describe --include-hidden from the CLI.
pathstringThe path to send the request to when the command is invoked.
displayNamestringThe display name visible in UI.
endpointNamestring?optionalThe name of the HTTP endpoint on this resource to send the request to when the command is invoked.
commandNamestring?optionalOptional name of the command. The name uniquely identifies the command. If a name isn't specified then it's inferred using the command's endpoint and HTTP method.
commandOptionsHttpCommandOptions?optionalOptional configuration for the command.
The command will be added to the resource represented by builder.
If endpointName is specified, the request will be sent to the endpoint with that name on the resource represented by builder. If an endpoint with that name is not found, or the endpoint with that name is not an HTTP endpoint, an exception will be thrown.
If no endpointName is specified, the first HTTP endpoint found on the resource will be used. HTTP endpoints with an https scheme are preferred over those with an http scheme. If no HTTP endpoint is found on the resource, an exception will be thrown.
The command will not be enabled until the endpoint is allocated and the resource the endpoint is associated with is healthy.
Specifying HttpCommandOptions.HttpClientName will use that named Http.HttpClient when sending the request. This allows you to configure the Http.HttpClient instance with a specific handler, timeout, or other options using HttpClientFactoryServiceCollectionExtensions.AddHttpClient. If HttpCommandOptions.HttpClientName is not specified, the default Http.HttpClient will be used and its HttpClient.Timeout will be set to Timeout.InfiniteTimeSpan. Specify a named client to preserve its configured timeout.
The HttpCommandOptions.PrepareRequest callback will be invoked to configure the request before it is sent. This can be used to add headers or a request payload before the request is sent.
The HttpCommandOptions.GetCommandResult callback will be invoked after the response is received to determine the result of the command invocation. If this callback is not specified, the command will be considered successful if the response status code is in the 2xx range. Set HttpCommandOptions.ResultMode to flow the HTTP response body back to the command caller.
Adds a command to the project resource that when invoked sends an HTTP POST request to the path /clear-cache.
var apiService =builder.AddProject>MyApiService>("api")
.WithHttpCommand("/clear-cache","Clear cache");
Adds a command to the project resource that when invoked sends an HTTP GET request to the path /reset-db on endpoint named admin. The request's headers are configured to include an X-Admin-Key header for verification.
var adminKey =builder.AddParameter("admin-key");
var apiService =builder.AddProject>MyApiService>("api")
.WithHttpsEndpoint("admin")
.WithEnvironment("ADMIN_KEY",adminKey)
.WithHttpCommand("/reset-db","Reset database",
endpointName:"admin",
commandOptions:new()
{
Method=HttpMethod.Get,
ConfirmationMessage="Are you sure you want to reset the database?",
PrepareRequest: request =>
{
request.Headers.Add("X-Admin-Key",adminKey);
returnTask.CompletedTask;
}
});
This method is not available in polyglot AppHosts.
The command will be added to the resource represented by builder.
If no HttpCommandOptions.EndpointSelector is specified, the first HTTP endpoint found on the resource will be used. HTTP endpoints with an https scheme are preferred over those with an http scheme. If no HTTP endpoint is found on the resource, an exception will be thrown.
The supplied HttpCommandOptions.EndpointSelector may return an endpoint from a different resource to that which the command is being added to.
The command will not be enabled until the endpoint is allocated and the resource the endpoint is associated with is healthy.
Specifying a HttpCommandOptions.HttpClientName will use that named Http.HttpClient when sending the request. This allows you to configure the Http.HttpClient instance with a specific handler, timeout, or other options using HttpClientFactoryServiceCollectionExtensions.AddHttpClient. If HttpCommandOptions.HttpClientName is not specified, the default Http.HttpClient will be used and its HttpClient.Timeout will be set to Timeout.InfiniteTimeSpan. Specify a named client to preserve its configured timeout.
The HttpCommandOptions.PrepareRequest callback will be invoked to configure the request before it is sent. This can be used to add headers or a request payload before the request is sent.
The HttpCommandOptions.GetCommandResult callback will be invoked after the response is received to determine the result of the command invocation. If this callback is not specified, the command will be considered successful if the response status code is in the 2xx range. Set HttpCommandOptions.ResultMode to flow the HTTP response body back to the command caller.
Adds commands to a project resource that when invoked sends an HTTP POST request to an endpoint on a separate load generator resource, to generate load against the resource the command was executed against.
var loadGenerator =builder.AddProject>LoadGenerator>("load");
var loadGeneratorEndpoint =loadGenerator.GetEndpoint("https");
var customerService =builder.AddProject>CustomerService>("customer-service")
Exposes an HTTP endpoint on a resource, or updates the existing HTTP endpoint if one with the same name already exists. This endpoint reference can be retrieved using ResourceBuilderExtensions.GetEndpoint. The endpoint name will be "http" if not specified.
If an endpoint with the same name already exists on the resource, the existing endpoint is updated with any non-null parameter values. Parameters left as null will not modify the existing endpoint's values.
This overload preserves binary compatibility for callers compiled against the previous boolisProxied signature. New source that omits isProxied binds to the nullable overload where omission is represented as null.
This method adds a health check to the health check service which polls the specified endpoint on the resource on a periodic basis. The base address is dynamically determined based on the endpoint that was selected. By default the path is set to "/" and the status code is set to 200.
This example shows adding an HTTP health check to a backend project. The health check makes sure that the front end does not start until the backend is reporting a healthy status based on the return code returned from the "/health" path on the backend server.
var builder =DistributedApplication.CreateBuilder(args);
var backend =builder.AddProject<Projects.Backend>("backend")
This method adds a health check to the health check service which polls the specified endpoint on a periodic basis. The base address is dynamically determined based on the endpoint that was selected. By default the path is set to "/" and the status code is set to 200.
This example shows adding an HTTP health check to a backend project. The health check makes sure that the front end does not start until the backend is reporting a healthy status based on the return code returned from the "/health" path on the backend server.
var builder =DistributedApplication.CreateBuilder(args);
var backend =builder.AddProject<Projects.Backend>("backend");
Adds a HttpsCertificateAnnotation to the resource annotations to associate an X.509 certificate key pair with the resource. This is used to configure the certificate presented by the resource for HTTPS/TLS endpoints.
Indicates that a resource should use the developer certificate key pair for HTTPS endpoints at run time. Currently this indicates use of the ASP.NET Core developer certificate. The developer certificate will only be used when running in local development scenarios; in publish mode resources will use their default certificate configuration.
Exposes an HTTPS endpoint on a resource, or updates the existing HTTPS endpoint if one with the same name already exists. This endpoint reference can be retrieved using ResourceBuilderExtensions.GetEndpoint. The endpoint name will be "https" if not specified.
If an endpoint with the same name already exists on the resource, the existing endpoint is updated with any non-null parameter values. Parameters left as null will not modify the existing endpoint's values.
This overload preserves binary compatibility for callers compiled against the previous boolisProxied signature. New source that omits isProxied binds to the nullable overload where omission is represented as null.
This method adds a health check to the health check service which polls the specified endpoint on the resource on a periodic basis. The base address is dynamically determined based on the endpoint that was selected. By default the path is set to "/" and the status code is set to 200.
This example shows adding an HTTPS health check to a backend project. The health check makes sure that the front end does not start until the backend is reporting a healthy status based on the return code returned from the "/health" path on the backend server.
var builder =DistributedApplication.CreateBuilder(args);
var backend =builder.AddProject<Projects.Backend>("backend")
This method allows you to specify a custom FluentUI icon that will be displayed for the resource in the dashboard. If no custom icon is specified, the dashboard will use default icons based on the resource type.
Set a Redis resource to use the Database icon:
var redis =builder.AddContainer("redis","redis:latest")
.WithIconName("Database");
Set a custom service to use a specific icon with Regular variant:
var service =builder.AddProject<Projects.MyService>("service")
ArgumentNullExceptionThrown when builder or callback is null.
Remarks
This method allows customization of how container images are named and tagged when pushed to a registry. The callback receives a ContainerImagePushOptionsCallbackContext that provides access to the resource and the ContainerImagePushOptions that can be modified. Multiple callbacks can be registered on the same resource, and they will be invoked in the order they were added.
Examples
Configure a custom image name and tag for a container resource:
var container =builder.AddContainer("myapp","myapp:latest")
ArgumentNullExceptionThrown when builder or callback is null.
Remarks
This method allows customization of how container images are named and tagged when pushed to a registry using an asynchronous callback. Use this overload when the callback needs to perform asynchronous operations such as retrieving configuration values from external sources. The callback receives a ContainerImagePushOptionsCallbackContext that provides access to the resource and the ContainerImagePushOptions that can be modified. Multiple callbacks can be registered on the same resource, and they will be invoked in the order they were added.
Examples
Configure image options asynchronously by retrieving values from configuration:
var container =builder.AddContainer("myapp","myapp:latest")
Declares the resource's launch tool arguments: the tool-invocation prefix that hosts the program, for example run ./cmd/api for go, -m flask for python, or tool exec <package> --yes -- for dotnet.
callbackAction<CommandLineArgsCallbackContext> Callback that produces the launch tool arguments. It is invoked with an empty CommandLineArgsCallbackContext.Args list; everything it adds becomes the leading arguments.
ownedByLaunchConfigurationTypestring?optional The debug launch configuration type that performs this tool invocation itself, for example "go" or "python" — the same value passed to WithDebugSupport. Leave this null (the default) when the prefix is not a debugging concern and must always be passed to the launched program.
showInCommandLinebooloptional Whether these arguments are part of the command line shown for the resource in the dashboard. Pass false for a prefix that is pure invocation plumbing the user did not write and cannot act on.
Launch tool arguments are always placed ahead of every argument contributed by WithArgs, no matter when this method is called, and no WithArgs callback can observe or modify them. Declaring the tool invocation this way therefore avoids any dependency on the order in which resource builder methods are called.
When ownedByLaunchConfigurationType is supplied and the resource is launched by an IDE using a launch configuration of that type (see WithDebugSupport), the launch configuration already carries the tool invocation, so these arguments are not passed to the launched program. In every other case — process execution, publish, or when a launch configuration of a different type is active — they are part of the resource's command line.
This has no effect on a container resource, which invokes its program through the image's ENTRYPOINT rather than through a local tool. That matters for executables published as a Dockerfile, because ExecutableResourceBuilderExtensions.PublishAsDockerFile carries the executable's annotations over to the generated container resource.
Calling this method more than once is allowed; the most recent declaration wins. It therefore declares a single tool invocation rather than accumulating one, which is why it is the integration's own description of how it launches the program, not a place for callers to append flags.
callbackFunc<CommandLineArgsCallbackContext, Task> Callback that produces the launch tool arguments. It is invoked with an empty CommandLineArgsCallbackContext.Args list.
ownedByLaunchConfigurationTypestring?optional The debug launch configuration type that performs this tool invocation, or null when the prefix is always passed to the launched program.
showInCommandLinebooloptionalWhether these arguments appear in the dashboard command line.
InvalidOperationExceptionThrown when the resource does not support lifetime configuration.
Remarks
The resource lifetime is evaluated from sourceBuilder when the application model is prepared, so later lifetime changes to the source resource are reflected by this resource.
callbackFunc<ManifestPublishingContext, Task>Callback method which takes a ManifestPublishingContext which can be used to inject JSON into the manifest.
ArgumentOutOfRangeExceptionThrown when parentProcessId is less than or equal to zero.
ArgumentExceptionThrown when parentProcessId does not identify a running process.
InvalidOperationExceptionThrown when the resource does not support lifetime configuration.
Remarks
The resource is tied to both the configured process ID and the process identity timestamp to avoid accidentally matching a reused process ID. Configure a resource to remain available across AppHost restarts, but clean it up when a parent process exits.
var builder =DistributedApplication.CreateBuilder(args);
The command will be added to the resource represented by builder. When the command executes, the process is started inside the AppHost process. Standard output and standard error are streamed to the command logger and a bounded tail of the combined output is returned as command result data.
This C# overload is not exported to polyglot AppHosts. Use the language-specific static process command API instead.
The command will be added to the resource represented by builder. When the command executes, processSpecFactory is called inside the AppHost process with the command execution context. Use ExecuteCommandContext.Arguments to read values supplied by the command caller.
commandNamestringThe name of command. The name uniquely identifies the command.
displayNamestringThe display name visible in UI.
processSpecFactoryFunc<ExecuteCommandContext, ValueTask<ProcessCommandSpec>>A callback that creates the local process specification when the command is invoked.
The command will be added to the resource represented by builder. When the command executes, processSpecFactory is called inside the AppHost process with the command execution context. Use ExecuteCommandContext.Arguments to read values supplied by the command caller.
Injects a connection string as an environment variable from the source resource into the destination resource, using the source resource's name as the connection string name (if not overridden). The logical connection name is preserved for application configuration. When the source resource does not specify IResourceWithConnectionString.ConnectionStringEnvironmentVariable and the logical name is not portable as an environment-variable suffix, Aspire emits both the original name and a portable alias that replaces characters unsupported in environment-variable names. For example, my-db produces ConnectionStrings__my-db and ConnectionStrings__my_db on targets that support both names.
Connection strings are also resolved by the configuration system (appSettings.json in the AppHost project, or environment variables). If a connection string is not found on the resource, the configuration system will be queried for a connection string using the resource's name.
builderIResourceBuilder<TDestination>The resource where connection string will be injected.
sourceIResourceBuilder<IResourceWithConnectionString>The resource from which to extract the connection string.
connectionNamestring?optional An override of the source resource's logical connection name. The physical environment-variable names are derived from this value when it is not null, unless the source resource specifies IResourceWithConnectionString.ConnectionStringEnvironmentVariable, in which case that explicit physical name is preserved.
optionalbooloptionaltrue to allow a missing connection string; false to throw an exception if the connection string is not found.
DistributedApplicationExceptionThrows an exception if the connection string resolves to null. It can be null if the resource has no connection string, and if the configuration has no connection string for the source resource.
Injects service discovery and endpoint information as environment variables from the source resource into the destination resource, using the source resource's name as the service name. Each non-excluded endpoint (where EndpointAnnotation.ExcludeReferenceEndpoint is false) defined on the source resource will be injected using the format defined by the ReferenceEnvironmentInjectionAnnotation on the destination resource, i.e. either "services__{sourceResourceName}__{endpointScheme}__{endpointIndex}={uriString}" for .NET service discovery, or "{RESOURCE_ENDPOINT}={uri}" for endpoint injection.
All endpoints are included in the default reference set unless explicitly excluded. Resource authors can opt out individual endpoints by setting EndpointAnnotation.ExcludeReferenceEndpoint to true (for example, using .WithEndpoint("endpointName", e => e.ExcludeReferenceEndpoint = true)) to exclude them from this method's behavior. Endpoints that have been excluded (such as management or health check endpoints) can still be referenced explicitly using ResourceBuilderExtensions.WithReference with ResourceBuilderExtensions.GetEndpoint.
Injects service discovery and endpoint information as environment variables from the source resource into the destination resource, using the source resource's name as the service name. Each non-excluded endpoint (where EndpointAnnotation.ExcludeReferenceEndpoint is false) defined on the source resource will be injected using the format defined by the ReferenceEnvironmentInjectionAnnotation on the destination resource, i.e. either "services__{name}__{endpointScheme}__{endpointIndex}={uriString}" for .NET service discovery, or "{name}_{ENDPOINT}={uri}" for endpoint injection.
All endpoints are included in the default reference set unless explicitly excluded. Resource authors can opt out individual endpoints by setting EndpointAnnotation.ExcludeReferenceEndpoint to true (for example, using .WithEndpoint("endpointName", e => e.ExcludeReferenceEndpoint = true)) to exclude them from this method's behavior. Endpoints that have been excluded (such as management or health check endpoints) can still be referenced explicitly using ResourceBuilderExtensions.WithReference with ResourceBuilderExtensions.GetEndpoint.
Injects service discovery and endpoint information as environment variables from the uri into the destination resource, using the name as the service name. The uri will be injected using the format defined by the ReferenceEnvironmentInjectionAnnotation on the destination resource, i.e. either "services__{name}__default__0={uri}" for .NET service discovery, or "{name}={uri}" for endpoint injection.
Injects service discovery information as environment variables from the ExternalServiceResource into the destination resource, using the name as the service name. The uri will be injected using the format "services__{name}__default__0={uri}."
Injects service discovery and endpoint information from the specified endpoint into the project resource using the source resource's name as the service name. Each endpoint uri will be injected using the format defined by the ReferenceEnvironmentInjectionAnnotation on the destination resource, i.e. either "services__{name}__{endpointScheme}__{endpointIndex}={uriString}" for .NET service discovery, or "{NAME}_{ENDPOINT}={uri}" for endpoint injection.
The WithRelationship method is used to add relationships to the resource. Relationships are used to link resources together in UI. The type indicates information about the relationship type.
This example shows adding a relationship between two resources.
var builder =DistributedApplication.CreateBuilder(args);
var backend =builder.AddProject<Projects.Backend>("backend");
var manager =builder.AddProject<Projects.Manager>("manager")
.WithRelationship(backend.Resource,"Manager");
This method is not available in polyglot AppHosts.
ArgumentNullExceptionThrown when builder or remoteImageTag is null.
Remarks
This is a convenience method that registers a callback to set the ContainerImagePushOptions.RemoteImageTag property. The tag can be any valid container image tag such as version numbers, environment names, or deployment identifiers. This method can be combined with ResourceBuilderExtensions.WithRemoteImageName to fully customize the image reference.
Examples
Set a specific version tag for a container:
var container =builder.AddContainer("myapp","myapp:latest")
Use this method to add a URL to be displayed for the resource. If the URL is relative, it will be applied to all URLs for the resource, replacing the path portion of the URL. Note that any endpoints on the resource will automatically get a corresponding URL added for them. To modify the URL for a specific endpoint, use ResourceBuilderExtensions.WithUrlForEndpoint.
Examples
Add a static URL to be displayed for the resource:
var frontend =builder.AddProject<Projects.Frontend>("frontend")
.WithUrl("https://example.com/","Home");
Update all displayed URLs to use the specified path and (optional) display text:
var frontend =builder.AddProject<Projects.Frontend>("frontend")
Use this method to add a URL to be displayed for the resource. Note that any endpoints on the resource will automatically get a corresponding URL added for them.
This method is not available in polyglot AppHosts. Use the ReferenceExpression overload instead.
Use this method to add a URL to be displayed for the resource. Note that any endpoints on the resource will automatically get a corresponding URL added for them.
Use this method to customize the URL that is automatically added for an endpoint on the resource. To add another URL for an endpoint, use ResourceBuilderExtensions.WithUrlForEndpoint.
The callback will be executed after endpoints have been allocated and the URL has been generated. This allows you to modify the URL or its display text.
If the URL returned by callback is relative, it will be combined with the endpoint URL to create an absolute URL.
If the endpoint with the specified name does not exist, the callback will not be executed and a warning will be logged.
Customize the URL for the "https" endpoint to use the link text "Home":
var frontend =builder.AddProject<Projects.Frontend>("frontend")
.WithUrlForEndpoint(
"https",
url =>url.DisplayText="Home");
Customize the URL for the "https" endpoint to deep to the "/home" path:
var frontend =builder.AddProject<Projects.Frontend>("frontend")
Use this method to add another URL for an endpoint on the resource. To customize the URL that is automatically added for an endpoint, use ResourceBuilderExtensions.WithUrlForEndpoint.
The callback will be executed after endpoints have been allocated and the resource is about to start.
If the endpoint with the specified name does not exist, the callback will not be executed and a warning will be logged.
Add a URL for the "https" endpoint that deep-links to an admin page with the text "Admin":
var frontend =builder.AddProject<Projects.Frontend>("frontend")
The callback will be executed after endpoints have been allocated for this resource. This allows you to modify any URLs for the resource, including adding, modifying, or even deletion. Note that any endpoints on the resource will automatically get a corresponding URL added for them.
Update all displayed URLs to have display text:
var frontend =builder.AddProject<Projects.Frontend>("frontend")
.WithUrls(c =>
{
foreach(var url inc.Urls)
{
if(string.IsNullOrEmpty(url.DisplayText))
{
url.DisplayText="frontend";
}
}
});
Update endpoint URLs to use a custom host name based on the resource name:
var frontend =builder.AddProject<Projects.Frontend>("frontend")
The callback will be executed after endpoints have been allocated for this resource. This allows you to modify any URLs for the resource, including adding, modifying, or even deletion. Note that any endpoints on the resource will automatically get a corresponding URL added for them.
Aspire