ResourceExtensions Methods
ClassMethods30 members
Provides extension methods for the
IResource interface. GetArgumentValuesAsync(IResourceWithArgs, DistributedApplicationOperation)Section titled GetArgumentValuesAsync(IResourceWithArgs, DistributedApplicationOperation)extensionValueTask<string[]> Get the arguments from the given resource.
public static class ResourceExtensions{ public static ValueTask<string[]> GetArgumentValuesAsync( this IResourceWithArgs resource, DistributedApplicationOperation applicationOperation = DistributedApplicationOperation.Run) { // ... }}Parameters
resourceIResourceWithArgsThe resource to get the arguments from.applicationOperationDistributedApplicationOperationoptionalThe 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); });GetComputeEnvironment(IResource)Section titled GetComputeEnvironment(IResource)extensionnullableIComputeEnvironmentResource? Gets the compute environment that the resource is explicitly bound to, if any.
public static class ResourceExtensions{ public static IComputeEnvironmentResource? GetComputeEnvironment( this IResource resource) { // ... }}Parameters
resourceIResourceThe resource to get the compute environment for.Returns
IComputeEnvironmentResource?The compute environment the resource is bound to, or null if the resource is not bound to any specific compute environment.GetDeploymentTargetAnnotation(IResource, IComputeEnvironmentResource?)Section titled GetDeploymentTargetAnnotation(IResource, IComputeEnvironmentResource?)extensionnullableDeploymentTargetAnnotation? 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) { // ... }}Parameters
resourceIResourcetargetComputeEnvironmentIComputeEnvironmentResource?optionalGetEndpoint(IResourceWithEndpoints, string)Section titled GetEndpoint(IResourceWithEndpoints, string)extensionEndpointReference Gets an endpoint reference for the specified endpoint name.
public static class ResourceExtensions{ public static EndpointReference GetEndpoint( this IResourceWithEndpoints resource, string endpointName) { // ... }}Parameters
resourceIResourceWithEndpointsThe IResourceWithEndpoints which contains EndpointAnnotation annotations.endpointNamestringThe name of the endpoint.Returns
EndpointReferenceAn EndpointReference object providing resolvable reference for the specified endpoint.GetEndpoint(IResourceWithEndpoints, string, NetworkIdentifier)Section titled GetEndpoint(IResourceWithEndpoints, string, NetworkIdentifier)extensionEndpointReference Gets an endpoint reference for the specified endpoint name.
public static class ResourceExtensions{ public static EndpointReference GetEndpoint( this IResourceWithEndpoints resource, string endpointName, NetworkIdentifier contextNetworkID) { // ... }}Parameters
resourceIResourceWithEndpointsThe IResourceWithEndpoints which contains EndpointAnnotation annotations.endpointNamestringThe name of the endpoint.contextNetworkIDNetworkIdentifierThe network ID of the network that provides the context for the returned EndpointReferenceReturns
EndpointReferenceAn EndpointReference object providing resolvable reference for the specified endpoint.GetEndpoints(IResourceWithEndpoints)Section titled GetEndpoints(IResourceWithEndpoints)extensionIEnumerable<EndpointReference> Gets references to all endpoints for the specified resource.
public static class ResourceExtensions{ public static IEnumerable<EndpointReference> GetEndpoints( this IResourceWithEndpoints resource) { // ... }}Parameters
resourceIResourceWithEndpointsThe 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)Section titled GetEndpoints(IResourceWithEndpoints, NetworkIdentifier)extensionIEnumerable<EndpointReference> Gets references to all endpoints for the specified resource.
public static class ResourceExtensions{ public static IEnumerable<EndpointReference> GetEndpoints( this IResourceWithEndpoints resource, NetworkIdentifier contextNetworkID) { // ... }}Parameters
resourceIResourceWithEndpointsThe IResourceWithEndpoints which contains EndpointAnnotation annotations.contextNetworkIDNetworkIdentifierThe 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.GetEnvironmentVariableValuesAsync(IResourceWithEnvironment, DistributedApplicationOperation)Section titled GetEnvironmentVariableValuesAsync(IResourceWithEnvironment, DistributedApplicationOperation)extensionValueTask<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) { // ... }}Parameters
resourceIResourceWithEnvironmentThe resource to get the environment variables from.applicationOperationDistributedApplicationOperationoptionalThe 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); }); 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) { // ... }}Parameters
resourceIResourceThe resource to get the replica count for.Returns
intThe number of replicas for the specified resource.GetResourceDependenciesAsync(IResource, DistributedApplicationExecutionContext, ResourceDependencyDiscoveryMode, CancellationToken)Section titled GetResourceDependenciesAsync(IResource, DistributedApplicationExecutionContext, ResourceDependencyDiscoveryMode, CancellationToken)extensionTask<IReadOnlySet<IResource>> Computes the set of resources that the specified
resource depends on. public static class ResourceExtensions{ public static Task<IReadOnlySet<IResource>> GetResourceDependenciesAsync( this IResource resource, DistributedApplicationExecutionContext executionContext, ResourceDependencyDiscoveryMode mode = ResourceDependencyDiscoveryMode.Recursive, CancellationToken cancellationToken = default(CancellationToken)) { // ... }}Parameters
resourceIResourceThe resource to compute dependencies for.executionContextDistributedApplicationExecutionContextThe execution context for resolving environment variables and arguments.modeResourceDependencyDiscoveryModeoptionalSpecifies dependency discovery mode.cancellationTokenCancellationTokenoptionalA cancellation token to observe while computing dependencies.Returns
Task<IReadOnlySet<IResource>>A set of all resources that the specified resource depends on.Remarks
Dependencies are computed from multiple sources: IResourceWithParentWaitAnnotationConnectionStringRedirectAnnotationIValueWithReferences)
When mode is ResourceDependencyDiscoveryMode.DirectOnly, only the immediate dependencies are returned. When mode is ResourceDependencyDiscoveryMode.Recursive, all transitive dependencies are included.
This method invokes environment variable and command-line argument callbacks to discover all references. The context resource ( resource) is not considered a dependency (even if it is transitively referenced).
GetResourceDependenciesAsync(IResource, DistributedApplicationExecutionContext, ResourceDependencyDiscoveryOptions, CancellationToken)Section titled GetResourceDependenciesAsync(IResource, DistributedApplicationExecutionContext, ResourceDependencyDiscoveryOptions, CancellationToken)extensionTask<IReadOnlySet<IResource>> Computes the set of resources that the specified
resource depends on. public static class ResourceExtensions{ public static Task<IReadOnlySet<IResource>> GetResourceDependenciesAsync( this IResource resource, DistributedApplicationExecutionContext executionContext, ResourceDependencyDiscoveryOptions options, CancellationToken cancellationToken = default(CancellationToken)) { // ... }}Parameters
resourceIResourceThe resource to compute dependencies for.executionContextDistributedApplicationExecutionContextThe execution context for resolving environment variables and arguments.optionsResourceDependencyDiscoveryOptionsChanges details of dependency discovery process. See ResourceDependencyDiscoveryOptions enumeration for more information.cancellationTokenCancellationTokenoptionalA cancellation token to observe while computing dependencies.Returns
Task<IReadOnlySet<IResource>>A set of all resources that the specified resource depends on.Remarks
Dependencies are computed from multiple sources: IResourceWithParentWaitAnnotationConnectionStringRedirectAnnotationIValueWithReferences)
This method invokes environment variable and command-line argument callbacks to discover all references. The context resource ( resource) is not considered a dependency (even if it is transitively referenced).
HasAnnotationIncludingAncestorsOfType(IResource)Section titled HasAnnotationIncludingAncestorsOfType(IResource)extensionbool Gets whether
resource or its ancestors have an annotation of type Tpublic static class ResourceExtensions{ public static bool HasAnnotationIncludingAncestorsOfType<T>( this IResource resource) { // ... }}Parameters
resourceIResourceThe resource to retrieve annotations from.Returns
booltrue if an annotation of the specified type was found; otherwise, false. Gets whether
resource has an annotation of type Tpublic static class ResourceExtensions{ public static bool HasAnnotationOfType<T>( this IResource resource) { // ... }}Parameters
resourceIResourceThe resource to retrieve annotations from.Returns
booltrue if an annotation of the specified type was found; otherwise, false. Gets a value indicating whether the resource is excluded from being published.
public static class ResourceExtensions{ public static bool IsExcludedFromPublish( this IResource resource) { // ... }}Parameters
resourceIResourceThe resource to determine if it should be excluded from being published.ProcessArgumentValuesAsync(IResource, DistributedApplicationExecutionContext, Action<object?, string?, Exception?, bool>, ILogger, CancellationToken)Section titled ProcessArgumentValuesAsync(IResource, DistributedApplicationExecutionContext, Action<object?, string?, Exception?, bool>, ILogger, CancellationToken)extensionValueTask 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)) { // ... }}Parameters
resourceIResourceThe resource containing the argument values to process.executionContextDistributedApplicationExecutionContextThe execution context used during the processing of argument values.processValueAction<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. loggerILoggerThe logger used for logging information or errors during the argument processing.cancellationTokenCancellationTokenoptionalA token for cancelling the operation, if needed.Returns
ValueTaskA task representing the asynchronous operation.ProcessEnvironmentVariableValuesAsync(IResource, DistributedApplicationExecutionContext, Action<string, object?, string?, Exception?>, ILogger, CancellationToken)Section titled ProcessEnvironmentVariableValuesAsync(IResource, DistributedApplicationExecutionContext, Action<string, object?, string?, Exception?>, ILogger, CancellationToken)extensionValueTask 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)) { // ... }}Parameters
resourceIResourceThe resource from which the environment variables are retrieved and processed.executionContextDistributedApplicationExecutionContextThe execution context to be used for processing the environment variables.processValueAction<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.loggerILoggerThe logger used to log any information or errors during the environment variables processing.cancellationTokenCancellationTokenoptionalA cancellation token to observe during the asynchronous operation.Returns
ValueTaskA task that represents the asynchronous operation. Determines whether the specified resource requires image building.
public static class ResourceExtensions{ public static bool RequiresImageBuild( this IResource resource) { // ... }}Parameters
resourceIResourceThe resource to evaluate for image build requirements.Returns
boolTrue 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)Section titled RequiresImageBuildAndPush(IResource)extensionbool Determines whether the specified resource requires image building and pushing.
public static class ResourceExtensions{ public static bool RequiresImageBuildAndPush( this IResource resource) { // ... }}Parameters
resourceIResourceThe resource to evaluate for image push requirements.Returns
boolTrue 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?)Section titled ResolveEndpoints(IResource, IPortAllocator?)extensionIReadOnlyList<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) { // ... }}Parameters
resourceIResourceThe resource containing endpoints to resolve.portAllocatorIPortAllocator?optionalOptional 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>)Section titled TryGetAnnotationsIncludingAncestorsOfType(IResource, IEnumerable<T>)extensionbool 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) { // ... }}Parameters
resourceIResourceThe resource to retrieve annotations from.resultIEnumerable<T>When this method returns, contains the annotations of the specified type, if found; otherwise, null.Returns
booltrue if annotations of the specified type were found; otherwise, false.TryGetAnnotationsOfType(IResource, IEnumerable<T>)Section titled TryGetAnnotationsOfType(IResource, IEnumerable<T>)extensionbool 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) { // ... }}Parameters
resourceIResourceThe resource to retrieve annotations from.resultIEnumerable<T>When this method returns, contains the annotations of the specified type, if found; otherwise, null.Returns
booltrue if annotations of the specified type were found; otherwise, false.TryGetContainerImageName(IResource, string?)Section titled TryGetContainerImageName(IResource, string?)extensionbool 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) { // ... }}Parameters
resourceIResourceThe resource to get the container image name from.imageNamestring?The container image name if found, otherwise null.Returns
boolTrue if the container image name was found, otherwise false.TryGetContainerImageName(IResource, bool, string?)Section titled TryGetContainerImageName(IResource, bool, string?)extensionbool 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) { // ... }}Parameters
resourceIResourceThe resource to get the container image name from.useBuiltImageboolWhen true, uses the image name from DockerfileBuildAnnotation if present. When false, uses only ContainerImageAnnotation.imageNamestring?The container image name if found, otherwise null.Returns
boolTrue if the container image name was found, otherwise false.TryGetContainerMounts(IResource, IEnumerable<ContainerMountAnnotation>)Section titled TryGetContainerMounts(IResource, IEnumerable<ContainerMountAnnotation>)extensionbool 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) { // ... }}Parameters
resourceIResourceThe resource to get the volume mounts for.volumeMountsIEnumerable<ContainerMountAnnotation>When this method returns, contains the volume mounts for the specified resource, if found; otherwise, null.Returns
booltrue if the volume mounts were successfully retrieved; otherwise, false.TryGetEndpoints(IResource, IEnumerable<EndpointAnnotation>)Section titled TryGetEndpoints(IResource, IEnumerable<EndpointAnnotation>)extensionbool Attempts to retrieve the endpoints for the given resource.
public static class ResourceExtensions{ public static bool TryGetEndpoints( this IResource resource, out IEnumerable<EndpointAnnotation>? endpoints) { // ... }}Parameters
resourceIResourceThe resource to retrieve the endpoints for.endpointsIEnumerable<EndpointAnnotation>The endpoints for the given resource, if found.Returns
boolTrue if the endpoints were found, false otherwise.TryGetEnvironmentVariables(IResource, IEnumerable<EnvironmentCallbackAnnotation>)Section titled TryGetEnvironmentVariables(IResource, IEnumerable<EnvironmentCallbackAnnotation>)extensionbool 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) { // ... }}Parameters
resourceIResourceThe resource to get the environment variables from.environmentVariablesIEnumerable<EnvironmentCallbackAnnotation>The environment variables retrieved from the resource, if any.Returns
boolTrue if the environment variables were successfully retrieved, false otherwise. 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) { // ... }}Parameters
resourceIResourceThe resource to get the annotation from.annotationT?When this method returns, contains the last annotation of the specified type from the resource, if found; otherwise, the default value for T.Returns
booltrue if the last annotation of the specified type was found in the resource; otherwise, false.TryGetUrls(IResource, IEnumerable<ResourceUrlAnnotation>)Section titled TryGetUrls(IResource, IEnumerable<ResourceUrlAnnotation>)extensionbool Attempts to retrieve the URLs for the given resource.
public static class ResourceExtensions{ public static bool TryGetUrls( this IResource resource, out IEnumerable<ResourceUrlAnnotation>? urls) { // ... }}Parameters
resourceIResourceThe resource to retrieve the URLs for.urlsIEnumerable<ResourceUrlAnnotation>The URLs for the given resource, if found.Returns
boolTrue if the URLs were found, false otherwise.WithContainerBuildOptions(IResourceBuilder<T>, Action<ContainerBuildOptionsCallbackContext>)Section titled WithContainerBuildOptions(IResourceBuilder<T>, Action<ContainerBuildOptionsCallbackContext>)extensionIResourceBuilder<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) { // ... }}Parameters
builderIResourceBuilder<T>The resource builder.callbackAction<ContainerBuildOptionsCallbackContext>A callback to configure container build options.Returns
IResourceBuilder<T>A reference to the ApplicationModel.IResourceBuilder`1.Remarks
This method is not available in polyglot app hosts.
WithContainerBuildOptions(IResourceBuilder<T>, Func<ContainerBuildOptionsCallbackContext, Task>)Section titled WithContainerBuildOptions(IResourceBuilder<T>, Func<ContainerBuildOptionsCallbackContext, Task>)extensionIResourceBuilder<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) { // ... }}Parameters
builderIResourceBuilder<T>The resource builder.callbackFunc<ContainerBuildOptionsCallbackContext, Task>An async callback to configure container build options.Returns
IResourceBuilder<T>A reference to the ApplicationModel.IResourceBuilder`1.Remarks
This method is not available in polyglot app hosts.