ResourceBuilderExtensions
Classstaticnet10.0
Provides extension methods for configuring resources with environment variables.
namespace Aspire.Hosting;
public static class ResourceBuilderExtensions{ // ...}110 members
Methods110
Section titled Methods Configures a resource to mark all endpoints' transport as HTTP/2. This is useful for HTTP/2 services that need prior knowledge.
Removes any container files source annotation from the resource being built.
Excludes a resource from being published to the manifest.
Exclude the resource from MCP operations using the Aspire MCP server. The resource is excluded from results that return resources, console logs and telemetry.
Retrieves the value of a specified connection property from the resource's connection properties.
Gets an
EndpointReference by name from the resource. These endpoints are declared either using ResourceBuilderExtensions.WithEndpoint or by launch settings (for project resources). The EndpointReference can be used to resolve the address of the endpoint in ResourceBuilderExtensions.WithEnvironment . Gets an
EndpointReference by name from the resource. These endpoints are declared either using ResourceBuilderExtensions.WithEndpoint or by launch settings (for project resources). The EndpointReference can be used to resolve the address of the endpoint in ResourceBuilderExtensions.WithEnvironment . PublishWithContainerFiles(IResourceBuilder<T>, IResourceBuilder<IResourceWithContainerFiles>, string) extensionats export Configures the resource to copy container files from the specified source resource during publishing.
SubscribeHttpsEndpointsUpdate(IResourceBuilder<TResource>, Action<HttpsEndpointUpdateCallbackContext>) extensionexperimentalats exportIResourceBuilder<TResource> 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. Waits for the dependency resource to enter the Running state before starting the resource.
Waits for the dependency resource to enter the Running state before starting the resource.
Waits for the dependency resource to enter the Exited or Finished state before starting the resource.
Waits for the dependency resource to enter the Running state before starting the resource.
Waits for the dependency resource to enter the Running state before starting the resource.
Adds arguments to be passed to a resource that supports arguments when it is launched.
Adds arguments to be passed to a resource that supports arguments when it is launched.
Adds a callback to be executed with a list of command-line arguments when a resource is started.
Adds an asynchronous callback to be executed with a list of command-line arguments when a resource is started.
WithCertificateAuthorityCollection(IResourceBuilder<TResource>, IResourceBuilder<CertificateAuthorityCollection>) extensionats ignoredIResourceBuilder<TResource> 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. WithCertificateTrustConfiguration(IResourceBuilder<TResource>, Func<CertificateTrustConfigurationCallbackAnnotationContext, Task>) extensionats ignoredIResourceBuilder<TResource> 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. IResourceBuilder<TResource> 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. Adds a
ResourceRelationshipAnnotation to the resource annotations to add a parent-child relationship. Adds a
ResourceRelationshipAnnotation to the resource annotations to add a parent-child relationship. WithCommand(IResourceBuilder<T>, string, string, Func<ExecuteCommandContext, Task<ExecuteCommandResult>>, CommandOptions?) extensionats export Adds a
ResourceCommandAnnotation to the resource annotations to add a resource command. Adds a
ResourceCommandAnnotation to the resource annotations to add a resource command. WithComputeEnvironment(IResourceBuilder<T>, IResourceBuilder<IComputeEnvironmentResource>) extensionats export Configures the compute environment for the compute resource.
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.
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.
WithConnectionStringRedirection(IResourceBuilder<T>, IResourceWithConnectionString) extensionats ignored Registers a callback which is invoked when a connection string is requested for a resource.
Adds a container files source annotation to the resource being built, specifying the path to the container files source.
WithDebugSupport(IResourceBuilder<T>, Func<string, TLaunchConfiguration>, string) extensionexperimentalats ignored Adds support for debugging the resource in an IDE or extension host.
WithDebugSupport(IResourceBuilder<T>, Func<string, CancellationToken, Task<TLaunchConfiguration>>, string) extensionexperimentalats ignored Adds support for asynchronously producing an IDE launch configuration for the resource.
WithDebugSupport(IResourceBuilder<T>, Func<LaunchConfigurationCallbackContext, Task<TLaunchConfiguration>>, string) extensionexperimentalats ignored Adds support for producing an IDE launch configuration from the resolved executable environment.
IResourceBuilder<TResource> 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.
Changes an existing endpoint or creates a new endpoint if it doesn't exist and invokes callback to modify the defaults.
WithEndpoint(IResourceBuilder<T>, int?, int?, string?, string?, string?, bool?, bool?, ProtocolType?) extensionats export 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. WithEndpoint(IResourceBuilder<T>, int?, int?, string?, string?, string?, bool, bool?, ProtocolType?) extensionats ignored Exposes an endpoint on a resource. A reference to this endpoint can be retrieved using
ResourceBuilderExtensions.GetEndpoint . WithEndpoint(IResourceBuilder<T>, int?, int?, string?, string?, string?, bool?, bool?) extensionats ignored 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. WithEndpoint(IResourceBuilder<T>, int?, int?, string?, string?, string?, bool, bool?) extensionats ignored 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. IResourceBuilder<IResourceWithEndpoints> 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. Adds an environment variable to the resource.
WithEnvironment(IResourceBuilder<T>, string, ExpressionInterpolatedStringHandler) extensionats ignored Adds an environment variable to the resource.
Adds an environment variable to the resource with a reference expression value.
Adds an environment variable to the resource.
Allows for the population of environment variables on a resource.
Allows for the population of environment variables on a resource.
Adds an environment variable to the resource with the endpoint for
endpointReference . WithEnvironment(IResourceBuilder<T>, string, IResourceBuilder<ExternalServiceResource>) extensionats ignored Adds an environment variable to the resource with the URL from the
ExternalServiceResource . WithEnvironment(IResourceBuilder<T>, string, IResourceBuilder<ParameterResource>) extensionats ignored Adds an environment variable to the resource with the value from
parameter. WithEnvironment(IResourceBuilder<T>, string, IResourceBuilder<IResourceWithConnectionString>) extensionats ignored Adds an environment variable to the resource with the connection string from the referenced resource.
Adds an environment variable to the resource with a value that provides both a runtime value and a manifest expression.
Adds an environment variable to the resource with a value that implements both
IValueProvider and IManifestExpressionProvider . Adds a
ExplicitStartupAnnotation annotation to the resource so it doesn't automatically start with the AppHost startup. Marks existing http or https endpoints on a resource as external.
Adds a
HealthCheckAnnotation to the resource annotations to associate a resource with a named health check managed by the health check service. WithHttpCommand(IResourceBuilder<TResource>, string, string, string?, string?, HttpCommandOptions?) extensionats ignoredIResourceBuilder<TResource> Adds a command to the resource that when invoked sends an HTTP request to the specified endpoint and path.
WithHttpCommand(IResourceBuilder<TResource>, string, string, Func<EndpointReference>, string?, HttpCommandOptions?) extensionats ignoredIResourceBuilder<TResource> Adds a command to the resource that when invoked sends an HTTP request to the specified endpoint and path.
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. Exposes an HTTP endpoint on a resource, or updates the existing HTTP endpoint if one with the same name already exists.
Adds a health check to the resource which is mapped to a specific endpoint.
WithHttpHealthCheck(IResourceBuilder<T>, Func<EndpointReference>, string?, int?) extensionats ignored Adds a health check to the resource which is mapped to a specific endpoint.
WithHttpProbe(IResourceBuilder<T>, ProbeType, string?, int?, int?, int?, int?, int?, string?) extensionexperimentalats ignored Adds a HTTP probe to the resource.
WithHttpProbe(IResourceBuilder<T>, ProbeType, Func<EndpointReference>, string?, int?, int?, int?, int?, int?) extensionexperimentalats ignored Adds a HTTP probe to the resource.
WithHttpsCertificate(IResourceBuilder<TResource>, X509Certificate2, IResourceBuilder<ParameterResource>) extensionexperimentalats ignoredIResourceBuilder<TResource> 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. WithHttpsCertificateConfiguration(IResourceBuilder<TResource>, Func<HttpsCertificateConfigurationCallbackAnnotationContext, Task>) extensionexperimentalats exportIResourceBuilder<TResource> Adds a callback that allows configuring the resource to use a specific HTTPS/TLS certificate key pair for server authentication.
WithHttpsDeveloperCertificate(IResourceBuilder<TResource>, IResourceBuilder<ParameterResource>) extensionexperimentalats exportIResourceBuilder<TResource> 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. Exposes an HTTPS endpoint on a resource, or updates the existing HTTPS endpoint if one with the same name already exists.
Adds a health check to the resource which is mapped to a specific endpoint.
Specifies the icon to use when displaying the resource in the dashboard.
WithImagePushOptions(IResourceBuilder<T>, Action<ContainerImagePushOptionsCallbackContext>) extensionexperimentalats ignored Adds a callback to configure container image push options for the resource.
WithImagePushOptions(IResourceBuilder<T>, Func<ContainerImagePushOptionsCallbackContext, Task>) extensionexperimentalats export Adds an asynchronous callback to configure container image push options for the resource.
WithLaunchToolArgs(IResourceBuilder<T>, Action<CommandLineArgsCallbackContext>, string?, bool) extensionexperimentalats ignored 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. WithLaunchToolArgs(IResourceBuilder<T>, Func<CommandLineArgsCallbackContext, Task>, string?, bool) extensionexperimentalats ignored Asynchronously declares the resource's launch tool arguments.
Configures a resource to match the lifetime of another resource.
WithManifestPublishingCallback(IResourceBuilder<T>, Action<ManifestPublishingContext>) extensionats ignored Registers a callback which is invoked when manifest is generated for the app model.
WithManifestPublishingCallback(IResourceBuilder<T>, Func<ManifestPublishingContext, Task>) extensionats ignored Registers an async callback which is invoked when manifest is generated for the app model.
IResourceBuilder<TResource> Disable HTTPS/TLS server certificate configuration for the resource. No HTTPS/TLS termination configuration will be applied.
Configures a resource to use a persistent lifetime that ends when a parent process exits.
Adds a
ResourceRelationshipAnnotation to the resource annotations to add a parent-child relationship. Adds a
ResourceRelationshipAnnotation to the resource annotations to add a parent-child relationship. Configures a resource to use a persistent lifetime.
WithProcessCommand(IResourceBuilder<TResource>, string, string, string, IReadOnlyList<string>, ProcessCommandOptions?) extensionexperimentalats ignoredIResourceBuilder<TResource> Adds a command to the resource that starts a local process when invoked.
WithProcessCommand(IResourceBuilder<TResource>, string, string, Func<ExecuteCommandContext, ProcessCommandSpec>, ProcessCommandOptions?) extensionexperimentalats ignoredIResourceBuilder<TResource> Adds a command to the resource that starts a local process when invoked.
WithProcessCommand(IResourceBuilder<TResource>, string, string, Func<ExecuteCommandContext, ValueTask<ProcessCommandSpec>>, ProcessCommandOptions?) extensionexperimentalats ignoredIResourceBuilder<TResource> Adds a command to the resource that starts a local process when invoked.
WithReference(IResourceBuilder<TDestination>, IResourceBuilder<IResourceWithConnectionString>, string?, bool) extensionats ignoredIResourceBuilder<TDestination> 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. Each resource defines the format of the connection string value. The underlying connection string value can be retrieved using I.
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.
WithReference(IResourceBuilder<TDestination>, IResourceBuilder<IResourceWithServiceDiscovery>) extensionats ignoredIResourceBuilder<TDestination> 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. WithReference(IResourceBuilder<TDestination>, IResourceBuilder<IResourceWithServiceDiscovery>, string) extensionats ignoredIResourceBuilder<TDestination> 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. IResourceBuilder<TDestination> 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. WithReference(IResourceBuilder<TDestination>, IResourceBuilder<ExternalServiceResource>) extensionats ignoredIResourceBuilder<TDestination> 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}." IResourceBuilder<TDestination> 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. WithReferenceEnvironment(IResourceBuilder<TDestination>, ReferenceEnvironmentInjectionFlags) extensionats ignoredIResourceBuilder<TDestination> Configures how information is injected into environment variables when the resource references other resources.
Adds a
ResourceRelationshipAnnotation to the resource annotations to add a reference to another resource. Walks the reference expression and adds
ResourceRelationshipAnnotation s for all resources found in the expression. Adds a
ResourceRelationshipAnnotation to the resource annotations to add a reference to another resource. Adds a
ResourceRelationshipAnnotation to the resource annotations to add a relationship. Adds a relationship to another resource using its builder.
Sets the remote image name (without registry endpoint or tag) for container push operations.
Sets the remote image tag for container push operations.
Configures a resource to use a session lifetime.
Adds a URL to be displayed for the resource.
Adds a URL to be displayed for the resource.
Adds a URL to be displayed for the resource.
Registers a callback to update the URL displayed for the endpoint with the specified name.
WithUrlForEndpoint(IResourceBuilder<T>, string, Func<EndpointReference, ResourceUrlAnnotation>) extensionats ignored Registers a callback to add a URL for the endpoint with the specified name.
Registers a callback to customize the URLs displayed for the resource.
Registers an async callback to customize the URLs displayed for the resource.
Aspire