ResourceExtensions Methods

Docs / Reference / Search C# APIs / Aspire.Hosting / ResourceExtensions / Methods

Methods

Docs Reference Search C# APIs Aspire.Hosting ResourceExtensions Methods

Class Methods 27 members

Provides extension methods for the IResource interface.

Obsolete — Use ExecutionConfigurationBuilder instead.

GetArgumentValuesAsync(IResourceWithArgs, DistributedApplicationOperation) extension ValueTask<string[]>

Get the arguments from the given resource.

public static class ResourceExtensions
{
    public static ValueTask<string[]> GetArgumentValuesAsync(
        this IResourceWithArgs resource,
        DistributedApplicationOperation applicationOperation = DistributedApplicationOperation.Run)
    {
        // ...
    }
}

ResourceExtensions.cs#L238-L243

Parameters

resource IResourceWithArgs The resource to get the arguments from.

applicationOperation DistributedApplicationOperation optional The context in which the AppHost is being executed.

Returns

ValueTask<string[]> The arguments retrieved from the resource.

Remarks

This method is useful when you want to make sure the arguments are added properly to resources, mostly in test situations. This method has asynchronous behavior when applicationOperation is DistributedApplicationOperation.Run and arguments were provided from IValueProvider otherwise it will be synchronous. Using ResourceExtensions.GetArgumentValuesAsync inside a unit test to validate argument values.

var builder = DistributedApplication.CreateBuilder();
var container = builder.AddContainer(
    "elasticsearch",
    "library/elasticsearch",
    "8.14.0")
 .WithArgs("--discovery.type", "single-node")
 .WithArgs("--xpack.security.enabled", "true");

var args = await container.Resource.GetArgumentsAsync();

Assert.Collection(args,
    arg =>
        {
            Assert.Equal("--discovery.type", arg);
        },
        arg =>
        {
            Assert.Equal("--xpack.security.enabled", arg);
        });

GetDeploymentTargetAnnotation(IResource, IComputeEnvironmentResource?) extensionnullable DeploymentTargetAnnotation?

Gets the deployment target for the specified resource, if any. Throws an exception if there are multiple compute environments and a compute environment is not explicitly specified.

public static class ResourceExtensions
{
    public static DeploymentTargetAnnotation? GetDeploymentTargetAnnotation(
        this IResource resource,
        IComputeEnvironmentResource? targetComputeEnvironment = null)
    {
        // ...
    }
}

ResourceExtensions.cs#L936-L967

Parameters

resource IResource

targetComputeEnvironment IComputeEnvironmentResource? optional

GetEndpoint(IResourceWithEndpoints, string) extension EndpointReference

Gets an endpoint reference for the specified endpoint name.

public static class ResourceExtensions
{
    public static EndpointReference GetEndpoint(
        this IResourceWithEndpoints resource,
        string endpointName)
    {
        // ...
    }
}

ResourceExtensions.cs#L698-L707

Parameters

resource IResourceWithEndpoints The IResourceWithEndpoints which contains EndpointAnnotation annotations.

endpointName string The name of the endpoint.

Returns

EndpointReference An EndpointReference object providing resolvable reference for the specified endpoint.

GetEndpoint(IResourceWithEndpoints, string, NetworkIdentifier) extension EndpointReference

Gets an endpoint reference for the specified endpoint name.

public static class ResourceExtensions
{
    public static EndpointReference GetEndpoint(
        this IResourceWithEndpoints resource,
        string endpointName,
        NetworkIdentifier contextNetworkID)
    {
        // ...
    }
}

ResourceExtensions.cs#L721-L730

Parameters

resource IResourceWithEndpoints The IResourceWithEndpoints which contains EndpointAnnotation annotations.

endpointName string The name of the endpoint.

contextNetworkID NetworkIdentifier The network ID of the network that provides the context for the returned EndpointReference

Returns

EndpointReference An EndpointReference object providing resolvable reference for the specified endpoint.

GetEndpoints(IResourceWithEndpoints) extension IEnumerable<EndpointReference>

Gets references to all endpoints for the specified resource.

public static class ResourceExtensions
{
    public static IEnumerable<EndpointReference> GetEndpoints(
        this IResourceWithEndpoints resource)
    {
        // ...
    }
}

ResourceExtensions.cs#L666-L671

Parameters

resource IResourceWithEndpoints The IResourceWithEndpoints which contains EndpointAnnotation annotations.

Returns

IEnumerable<EndpointReference> An enumeration of EndpointReference based on the EndpointAnnotation annotations from the resources' IResource.Annotations collection.

GetEndpoints(IResourceWithEndpoints, NetworkIdentifier) extension IEnumerable<EndpointReference>

Gets references to all endpoints for the specified resource.

public static class ResourceExtensions
{
    public static IEnumerable<EndpointReference> GetEndpoints(
        this IResourceWithEndpoints resource,
        NetworkIdentifier contextNetworkID)
    {
        // ...
    }
}

ResourceExtensions.cs#L682-L687

Parameters

resource IResourceWithEndpoints The IResourceWithEndpoints which contains EndpointAnnotation annotations.

contextNetworkID NetworkIdentifier The ID of the network that serves as the context context for the endpoint references.

Returns

IEnumerable<EndpointReference> An enumeration of EndpointReference based on the EndpointAnnotation annotations from the resources' IResource.Annotations collection.

Obsolete — Use ExecutionConfigurationBuilder instead.

GetEnvironmentVariableValuesAsync(IResourceWithEnvironment, DistributedApplicationOperation) extension ValueTask<Dictionary<string, string>>

Get the environment variables from the given resource.

public static class ResourceExtensions
{
    public static ValueTask<Dictionary<string, string>> GetEnvironmentVariableValuesAsync(
        this IResourceWithEnvironment resource,
        DistributedApplicationOperation applicationOperation = DistributedApplicationOperation.Run)
    {
        // ...
    }
}

ResourceExtensions.cs#L194-L199

Parameters

resource IResourceWithEnvironment The resource to get the environment variables from.

applicationOperation DistributedApplicationOperation optional The context in which the AppHost is being executed.

Returns

ValueTask<Dictionary<string, string>> The environment variables retrieved from the resource.

Remarks

This method is useful when you want to make sure the environment variables are added properly to resources, mostly in test situations. This method has asynchronous behavior when applicationOperation is DistributedApplicationOperation.Run and environment variables were provided from IValueProvider otherwise it will be synchronous. Using ResourceExtensions.GetEnvironmentVariableValuesAsync inside a unit test to validate environment variable values.

var builder = DistributedApplication.CreateBuilder();
var container = builder.AddContainer(
    "elasticsearch",
    "library/elasticsearch",
    "8.14.0")
 .WithEnvironment("discovery.type", "single-node")
 .WithEnvironment("xpack.security.enabled", "true");

var env = await container.Resource.GetEnvironmentVariableValuesAsync();

Assert.Collection(env,
    env =>
        {
            Assert.Equal("discovery.type", env.Key);
            Assert.Equal("single-node", env.Value);
        },
        env =>
        {
            Assert.Equal("xpack.security.enabled", env.Key);
            Assert.Equal("true", env.Value);
        });

GetReplicaCount(IResource) extension int

Gets the number of replicas for the specified resource. Defaults to 1 if no ReplicaAnnotation is found.

public static class ResourceExtensions
{
    public static int GetReplicaCount(
        this IResource resource)
    {
        // ...
    }
}

ResourceExtensions.cs#L880-L886

Parameters

resource IResource The resource to get the replica count for.

Returns

int The number of replicas for the specified resource.

HasAnnotationIncludingAncestorsOfType(IResource) extension bool

Gets whether resource or its ancestors have an annotation of type T

public static class ResourceExtensions
{
    public static bool HasAnnotationIncludingAncestorsOfType<T>(
        this IResource resource)
    {
        // ...
    }
}

ResourceExtensions.cs#L119-L141

Parameters

resource IResource The resource to retrieve annotations from.

Returns

bool true if an annotation of the specified type was found; otherwise, false.

HasAnnotationOfType(IResource) extension bool

Gets whether resource has an annotation of type T

public static class ResourceExtensions
{
    public static bool HasAnnotationOfType<T>(
        this IResource resource)
    {
        // ...
    }
}

ResourceExtensions.cs#L70

Parameters

resource IResource The resource to retrieve annotations from.

Returns

bool true if an annotation of the specified type was found; otherwise, false.

IsExcludedFromPublish(IResource) extension bool

Gets a value indicating whether the resource is excluded from being published.

public static class ResourceExtensions
{
    public static bool IsExcludedFromPublish(
        this IResource resource)
    {
        // ...
    }
}

ResourceExtensions.cs#L543

Parameters

resource IResource The resource to determine if it should be excluded from being published.

Obsolete — Use ExecutionConfigurationBuilder instead.

ProcessArgumentValuesAsync(IResource, DistributedApplicationExecutionContext, Action<object?, string?, Exception?, bool>, ILogger, CancellationToken) extension ValueTask

Processes argument values for the specified resource in the given execution context.

public static class ResourceExtensions
{
    public static ValueTask ProcessArgumentValuesAsync(
        this IResource resource,
        DistributedApplicationExecutionContext executionContext,
        Action<object?, string?, Exception?, bool> processValue,
        ILogger logger,
        CancellationToken cancellationToken = default(CancellationToken))
    {
        // ...
    }
}

ResourceExtensions.cs#L338-L341

Parameters

resource IResource The resource containing the argument values to process.

executionContext DistributedApplicationExecutionContext The execution context used during the processing of argument values.

processValue Action<object?, string?, Exception?, bool> A callback invoked for each argument value. This action provides the unprocessed value, processed string representation, an exception if one occurs, and a boolean indicating the success of processing.

logger ILogger The logger used for logging information or errors during the argument processing.

cancellationToken CancellationToken optional A token for cancelling the operation, if needed.

Returns

ValueTask A task representing the asynchronous operation.

Obsolete — Use ExecutionConfigurationBuilder instead.

ProcessEnvironmentVariableValuesAsync(IResource, DistributedApplicationExecutionContext, Action<string, object?, string?, Exception?>, ILogger, CancellationToken) extension ValueTask

Processes environment variable values for the specified resource within the given execution context.

public static class ResourceExtensions
{
    public static ValueTask ProcessEnvironmentVariableValuesAsync(
        this IResource resource,
        DistributedApplicationExecutionContext executionContext,
        Action<string, object?, string?, Exception?> processValue,
        ILogger logger,
        CancellationToken cancellationToken = default(CancellationToken))
    {
        // ...
    }
}

ResourceExtensions.cs#L430-L433

Parameters

resource IResource The resource from which the environment variables are retrieved and processed.

executionContext DistributedApplicationExecutionContext The execution context to be used for processing the environment variables.

processValue Action<string, object?, string?, Exception?> An action delegate invoked for each environment variable, providing the key, the unprocessed value, the processed value (if available), and any exception encountered during processing.

logger ILogger The logger used to log any information or errors during the environment variables processing.

cancellationToken CancellationToken optional A cancellation token to observe during the asynchronous operation.

Returns

ValueTask A task that represents the asynchronous operation.

RequiresImageBuild(IResource) extension bool

Determines whether the specified resource requires image building.

public static class ResourceExtensions
{
    public static bool RequiresImageBuild(
        this IResource resource)
    {
        // ...
    }
}

ResourceExtensions.cs#L901-L906

Parameters

resource IResource The resource to evaluate for image build requirements.

Returns

bool True if the resource requires image building; otherwise, false.

Remarks

Resources require an image build if they provide their own Dockerfile or are a project. Resources that are excluded from publishing are not considered to require image building.

RequiresImageBuildAndPush(IResource) extension bool

Determines whether the specified resource requires image building and pushing.

public static class ResourceExtensions
{
    public static bool RequiresImageBuildAndPush(
        this IResource resource)
    {
        // ...
    }
}

ResourceExtensions.cs#L921

Parameters

resource IResource The resource to evaluate for image push requirements.

Returns

bool True if the resource requires image building and pushing; otherwise, false.

Remarks

Resources require an image build and a push to a container registry if they provide their own Dockerfile or are a project. Resources that are excluded from publishing are not considered to require image building and pushing.

ResolveEndpoints(IResource, IPortAllocator?) extension IReadOnlyList<ResolvedEndpoint>

Resolves endpoint port configuration for the specified resource. Computes target ports and exposed ports based on resource type, endpoint configuration, and whether the endpoint is considered a default HTTP endpoint.

public static class ResourceExtensions
{
    public static IReadOnlyList<ResolvedEndpoint> ResolveEndpoints(
        this IResource resource,
        IPortAllocator? portAllocator = null)
    {
        // ...
    }
}

ResourceExtensions.cs#L744-L814

Parameters

resource IResource The resource containing endpoints to resolve.

portAllocator IPortAllocator? optional Optional port allocator. If null, uses default allocation starting from port 8000.

Returns

IReadOnlyList<ResolvedEndpoint> A read-only list of resolved endpoints with computed port values.

TryGetAnnotationsIncludingAncestorsOfType(IResource, IEnumerable<T>) extension bool

Attempts to retrieve all annotations of the specified type from the given resource including from parents.

public static class ResourceExtensions
{
    public static bool TryGetAnnotationsIncludingAncestorsOfType<T>(
        this IResource resource,
        out IEnumerable<T>? result)
    {
        // ...
    }
}

ResourceExtensions.cs#L82-L108

Parameters

resource IResource The resource to retrieve annotations from.

result IEnumerable<T> When this method returns, contains the annotations of the specified type, if found; otherwise, null.

Returns

bool true if annotations of the specified type were found; otherwise, false.

TryGetAnnotationsOfType(IResource, IEnumerable<T>) extension bool

Attempts to retrieve all annotations of the specified type from the given resource.

public static class ResourceExtensions
{
    public static bool TryGetAnnotationsOfType<T>(
        this IResource resource,
        out IEnumerable<T>? result)
    {
        // ...
    }
}

ResourceExtensions.cs#L48-L58

Parameters

resource IResource The resource to retrieve annotations from.

result IEnumerable<T> When this method returns, contains the annotations of the specified type, if found; otherwise, null.

Returns

bool true if annotations of the specified type were found; otherwise, false.

TryGetContainerImageName(IResource, string?) extension bool

Attempts to get the container image name from the given resource.

public static class ResourceExtensions
{
    public static bool TryGetContainerImageName(
        this IResource resource,
        out string? imageName)
    {
        // ...
    }
}

ResourceExtensions.cs#L827

Parameters

resource IResource The resource to get the container image name from.

imageName string? The container image name if found, otherwise null.

Returns

bool True if the container image name was found, otherwise false.

TryGetContainerImageName(IResource, bool, string?) extension bool

Attempts to get the container image name from the given resource.

public static class ResourceExtensions
{
    public static bool TryGetContainerImageName(
        this IResource resource,
        bool useBuiltImage,
        out string? imageName)
    {
        // ...
    }
}

ResourceExtensions.cs#L841-L869

Parameters

resource IResource The resource to get the container image name from.

useBuiltImage bool When true, uses the image name from DockerfileBuildAnnotation if present. When false, uses only ContainerImageAnnotation.

imageName string? The container image name if found, otherwise null.

Returns

bool True if the container image name was found, otherwise false.

TryGetContainerMounts(IResource, IEnumerable<ContainerMountAnnotation>) extension bool

Attempts to get the container mounts for the specified resource.

public static class ResourceExtensions
{
    public static bool TryGetContainerMounts(
        this IResource resource,
        out IEnumerable<ContainerMountAnnotation>? volumeMounts)
    {
        // ...
    }
}

ResourceExtensions.cs#L634

Parameters

resource IResource The resource to get the volume mounts for.

volumeMounts IEnumerable<ContainerMountAnnotation> When this method returns, contains the volume mounts for the specified resource, if found; otherwise, null.

Returns

bool true if the volume mounts were successfully retrieved; otherwise, false.

TryGetEndpoints(IResource, IEnumerable<EndpointAnnotation>) extension bool

Attempts to retrieve the endpoints for the given resource.

public static class ResourceExtensions
{
    public static bool TryGetEndpoints(
        this IResource resource,
        out IEnumerable<EndpointAnnotation>? endpoints)
    {
        // ...
    }
}

ResourceExtensions.cs#L645

Parameters

resource IResource The resource to retrieve the endpoints for.

endpoints IEnumerable<EndpointAnnotation> The endpoints for the given resource, if found.

Returns

bool True if the endpoints were found, false otherwise.

TryGetEnvironmentVariables(IResource, IEnumerable<EnvironmentCallbackAnnotation>) extension bool

Attempts to get the environment variables from the given resource.

public static class ResourceExtensions
{
    public static bool TryGetEnvironmentVariables(
        this IResource resource,
        out IEnumerable<EnvironmentCallbackAnnotation>? environmentVariables)
    {
        // ...
    }
}

ResourceExtensions.cs#L152

Parameters

resource IResource The resource to get the environment variables from.

environmentVariables IEnumerable<EnvironmentCallbackAnnotation> The environment variables retrieved from the resource, if any.

Returns

bool True if the environment variables were successfully retrieved, false otherwise.

TryGetLastAnnotation(IResource, T?) extension bool

Attempts to get the last annotation of the specified type from the resource.

public static class ResourceExtensions
{
    public static bool TryGetLastAnnotation<T>(
        this IResource resource,
        out T? annotation)
    {
        // ...
    }
}

ResourceExtensions.cs#L27-L35

Parameters

resource IResource The resource to get the annotation from.

annotation T? When this method returns, contains the last annotation of the specified type from the resource, if found; otherwise, the default value for T.

Returns

bool true if the last annotation of the specified type was found in the resource; otherwise, false.

TryGetUrls(IResource, IEnumerable<ResourceUrlAnnotation>) extension bool

Attempts to retrieve the URLs for the given resource.

public static class ResourceExtensions
{
    public static bool TryGetUrls(
        this IResource resource,
        out IEnumerable<ResourceUrlAnnotation>? urls)
    {
        // ...
    }
}

ResourceExtensions.cs#L656

Parameters

resource IResource The resource to retrieve the URLs for.

urls IEnumerable<ResourceUrlAnnotation> The URLs for the given resource, if found.

Returns

bool True if the URLs were found, false otherwise.

Experimental — ASPIREPIPELINES003

WithContainerBuildOptions(IResourceBuilder<T>, Action<ContainerBuildOptionsCallbackContext>) extension IResourceBuilder<T>

Configures container build options for a compute resource using a callback.

public static class ResourceExtensions
{
    public static IResourceBuilder<T> WithContainerBuildOptions<T>(
        this IResourceBuilder<T> builder,
        Action<ContainerBuildOptionsCallbackContext> callback)
    {
        // ...
    }
}

ResourceExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder.

callback Action<ContainerBuildOptionsCallbackContext> A callback to configure container build options.

Returns

IResourceBuilder<T> A reference to the ApplicationModel.IResourceBuilder`1.

Experimental — ASPIREPIPELINES003

WithContainerBuildOptions(IResourceBuilder<T>, Func<ContainerBuildOptionsCallbackContext, Task>) extension IResourceBuilder<T>

Configures container build options for a compute resource using an async callback.

public static class ResourceExtensions
{
    public static IResourceBuilder<T> WithContainerBuildOptions<T>(
        this IResourceBuilder<T> builder,
        Func<ContainerBuildOptionsCallbackContext, Task> callback)
    {
        // ...
    }
}

ResourceExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder.

callback Func<ContainerBuildOptionsCallbackContext, Task> An async callback to configure container build options.

Returns

IResourceBuilder<T> A reference to the ApplicationModel.IResourceBuilder`1.