ResourceBuilderExtensions Methods

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

Methods

Docs Reference Search C# APIs Aspire.Hosting ResourceBuilderExtensions Methods

Class Methods 88 members

Provides extension methods for configuring resources with environment variables.

AsHttp2Service(IResourceBuilder<T>) extension IResourceBuilder<T>

Configures a resource to mark all endpoints' transport as HTTP/2. This is useful for HTTP/2 services that need prior knowledge.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> AsHttp2Service<T>(
        this IResourceBuilder<T> builder)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L1050-L1052

Parameters

builder IResourceBuilder<T> The resource builder.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

ClearContainerFilesSources(IResourceBuilder<T>) extension IResourceBuilder<T>

Removes any container files source annotation from the resource being built.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> ClearContainerFilesSources<T>(
        this IResourceBuilder<T> builder)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L1402-L1409

Parameters

builder IResourceBuilder<T> The resource builder to which the container files source annotations should be removed. Cannot be null.

Returns

IResourceBuilder<T> The resource builder instance with the container files source annotation applied.

ExcludeFromManifest(IResourceBuilder<T>) extension IResourceBuilder<T>

Excludes a resource from being published to the manifest.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> ExcludeFromManifest<T>(
        this IResourceBuilder<T> builder)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L1420-L1422

Parameters

builder IResourceBuilder<T> The resource to exclude.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

ExcludeFromMcp(IResourceBuilder<T>) extension IResourceBuilder<T>

Exclude the resource from MCP operations using the Aspire MCP server. The resource is excluded from results that return resources, console logs and telemetry.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> ExcludeFromMcp<T>(
        this IResourceBuilder<T> builder)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L3117-L3119

Parameters

builder IResourceBuilder<T> The resource builder.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

GetConnectionProperty(IResourceWithConnectionString, string) extension ReferenceExpression

Retrieves the value of a specified connection property from the resource's connection properties.

public static class ResourceBuilderExtensions
{
    public static ReferenceExpression GetConnectionProperty(
        this IResourceWithConnectionString resource,
        string key)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L569-L578

Parameters

resource IResourceWithConnectionString The resource that provides the connection properties. Cannot be null.

key string The key of the connection property to retrieve. Cannot be null.

Returns

ReferenceExpression The value associated with the specified connection property key.

Remarks

Throws a KeyNotFoundException if the specified key does not exist in the resource's connection properties.

GetEndpoint(IResourceBuilder<T>, string, NetworkIdentifier) extension EndpointReference

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.

public static class ResourceBuilderExtensions
{
    public static EndpointReference GetEndpoint<T>(
        this IResourceBuilder<T> builder,
        string name,
        NetworkIdentifier contextNetworkID)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L1022-L1024

Parameters

builder IResourceBuilder<T> The the resource builder.

name string The name of the endpoint.

contextNetworkID NetworkIdentifier The network context in which to resolve the endpoint. If null, localhost (loopback) network context will be used.

Returns

EndpointReference An EndpointReference that can be used to resolve the address of the endpoint after resource allocation has occurred.

GetEndpoint(IResourceBuilder<T>, string) extension EndpointReference

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.

public static class ResourceBuilderExtensions
{
    public static EndpointReference GetEndpoint<T>(
        this IResourceBuilder<T> builder,
        string name)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L1037-L1039

Parameters

builder IResourceBuilder<T> The the resource builder.

name string The name of the endpoint.

Returns

EndpointReference An EndpointReference that can be used to resolve the address of the endpoint after resource allocation has occurred.

PublishWithContainerFiles(IResourceBuilder<T>, IResourceBuilder<IResourceWithContainerFiles>, string) extension IResourceBuilder<T>

Configures the resource to copy container files from the specified source resource during publishing.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> PublishWithContainerFiles<T>(
        this IResourceBuilder<T> builder,
        IResourceBuilder<IResourceWithContainerFiles> source,
        string destinationPath)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L1356-L1369

Parameters

builder IResourceBuilder<T> The resource builder to which container files will be copied to.

source IResourceBuilder<IResourceWithContainerFiles> The resource which contains the container files to be copied.

destinationPath string The destination path within the resource's container where the files will be copied.

WaitFor(IResourceBuilder<T>, IResourceBuilder<IResource>) extension IResourceBuilder<T>

Waits for the dependency resource to enter the Running state before starting the resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WaitFor<T>(
        this IResourceBuilder<T> builder,
        IResourceBuilder<IResource> dependency)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L1454-L1457

Parameters

builder IResourceBuilder<T> The resource builder for the resource that will be waiting.

dependency IResourceBuilder<IResource> The resource builder for the dependency resource.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

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 ResourceBuilderExtensions.WithHealthCheck method can be used to associate additional health checks with a resource.

Start message queue before starting the worker service.

var builder = DistributedApplication.CreateBuilder(args);
var messaging = builder.AddRabbitMQ("messaging");
builder.AddProject<Projects.MyApp>("myapp")
       .WithReference(messaging)
       .WaitFor(messaging);

WaitFor(IResourceBuilder<T>, IResourceBuilder<IResource>, WaitBehavior) extension IResourceBuilder<T>

Waits for the dependency resource to enter the Running state before starting the resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WaitFor<T>(
        this IResourceBuilder<T> builder,
        IResourceBuilder<IResource> dependency,
        WaitBehavior waitBehavior)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L1496-L1499

Parameters

builder IResourceBuilder<T> The resource builder for the resource that will be waiting.

dependency IResourceBuilder<IResource> The resource builder for the dependency resource.

waitBehavior WaitBehavior The wait behavior to use.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

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 ResourceBuilderExtensions.WithHealthCheck method can be used to associate additional health checks with a 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 becomes healthy. This is the default behavior with the ResourceBuilderExtensions.WaitFor overload.

When WaitBehavior.StopOnResourceUnavailable is specified, the wait operation will throw a DistributedApplicationException if the resource enters an unavailable state.

Start message queue before starting the worker service.

var builder = DistributedApplication.CreateBuilder(args);
var messaging = builder.AddRabbitMQ("messaging");
builder.AddProject<Projects.MyApp>("myapp")
       .WithReference(messaging)
       .WaitFor(messaging, WaitBehavior.StopOnResourceUnavailable);

WaitForCompletion(IResourceBuilder<T>, IResourceBuilder<IResource>, int) extension IResourceBuilder<T>

Waits for the dependency resource to enter the Exited or Finished state before starting the resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WaitForCompletion<T>(
        this IResourceBuilder<T> builder,
        IResourceBuilder<IResource> dependency,
        int exitCode = 0)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L1701-L1716

Parameters

builder IResourceBuilder<T> The resource builder for the resource that will be waiting.

dependency IResourceBuilder<IResource> The resource builder for the dependency resource.

exitCode int optional The exit code which is interpreted as successful.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

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")
                    .WithReference(pgsql);
builder.AddProject<Projects.DatabasePrepTool>("dbpreptool")
       .WithReference(pgsql)
       .WaitForCompletion(dbprep);

WaitForStart(IResourceBuilder<T>, IResourceBuilder<IResource>) extension IResourceBuilder<T>

Waits for the dependency resource to enter the Running state before starting the resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WaitForStart<T>(
        this IResourceBuilder<T> builder,
        IResourceBuilder<IResource> dependency)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L1560-L1563

Parameters

builder IResourceBuilder<T> The resource builder for the resource that will be waiting.

dependency IResourceBuilder<IResource> The resource builder for the dependency resource.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

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);
var messaging = builder.AddRabbitMQ("messaging");
builder.AddProject<Projects.MyApp>("myapp")
       .WithReference(messaging)
       .WaitForStart(messaging);

WaitForStart(IResourceBuilder<T>, IResourceBuilder<IResource>, WaitBehavior) extension IResourceBuilder<T>

Waits for the dependency resource to enter the Running state before starting the resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WaitForStart<T>(
        this IResourceBuilder<T> builder,
        IResourceBuilder<IResource> dependency,
        WaitBehavior waitBehavior)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L1600-L1603

Parameters

builder IResourceBuilder<T> The resource builder for the resource that will be waiting.

dependency IResourceBuilder<IResource> The resource builder for the dependency resource.

waitBehavior WaitBehavior The wait behavior to use.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

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.

When WaitBehavior.StopOnResourceUnavailable is specified, the wait operation will throw a DistributedApplicationException if the resource enters an unavailable state.

Start message queue before starting the worker service, but don't wait for health checks.

var builder = DistributedApplication.CreateBuilder(args);
var messaging = builder.AddRabbitMQ("messaging");
builder.AddProject<Projects.MyApp>("myapp")
       .WithReference(messaging)
       .WaitForStart(messaging, WaitBehavior.StopOnResourceUnavailable);

WithArgs(IResourceBuilder<T>, string[]) extension IResourceBuilder<T>

Adds arguments to be passed to a resource that supports arguments when it is launched.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithArgs<T>(
        this IResourceBuilder<T> builder,
        params string[] args)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder for a resource implementing IResourceWithArgs.

args string[] The arguments to be passed to the resource when it is started.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

WithArgs(IResourceBuilder<T>, object[]) extension IResourceBuilder<T>

Adds arguments to be passed to a resource that supports arguments when it is launched.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithArgs<T>(
        this IResourceBuilder<T> builder,
        params object[] args)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder for a resource implementing IResourceWithArgs.

args object[] The arguments to be passed to the resource when it is started.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

WithArgs(IResourceBuilder<T>, Action<CommandLineArgsCallbackContext>) extension IResourceBuilder<T>

Adds a callback to be executed with a list of command-line arguments when a resource is started.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithArgs<T>(
        this IResourceBuilder<T> builder,
        Action<CommandLineArgsCallbackContext> callback)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder for a resource implementing IResourceWithArgs.

callback Action<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.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

WithArgs(IResourceBuilder<T>, Func<CommandLineArgsCallbackContext, Task>) extension IResourceBuilder<T>

Adds an asynchronous callback to be executed with a list of command-line arguments when a resource is started.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithArgs<T>(
        this IResourceBuilder<T> builder,
        Func<CommandLineArgsCallbackContext, Task> callback)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder for a resource implementing IResourceWithArgs.

callback Func<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.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

WithCertificateAuthorityCollection(IResourceBuilder<TResource>, IResourceBuilder<CertificateAuthorityCollection>) extension IResourceBuilder<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.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<TResource> WithCertificateAuthorityCollection<TResource>(
        this IResourceBuilder<TResource> builder,
        IResourceBuilder<CertificateAuthorityCollection> certificateAuthorityCollection)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L2312-L2332

Parameters

builder IResourceBuilder<TResource> The resource builder.

certificateAuthorityCollection IResourceBuilder<CertificateAuthorityCollection> Additional certificates in a CertificateAuthorityCollection to treat as trusted certificate authorities for the resource.

Returns

IResourceBuilder<TResource> The ApplicationModel.IResourceBuilder`1.

Remarks

Add a certificate authority collection to a container resource.

var caCollection = builder.AddCertificateAuthorityCollection("my-cas")
    .WithCertificatesFromFile("../my-ca.pem");

var container = builder.AddContainer("my-service", "my-service:latest")
    .WithCertificateAuthorityCollection(caCollection);

WithCertificateTrustConfiguration(IResourceBuilder<TResource>, Func<CertificateTrustConfigurationCallbackAnnotationContext, Task>) extension IResourceBuilder<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.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<TResource> WithCertificateTrustConfiguration<TResource>(
        this IResourceBuilder<TResource> builder,
        Func<CertificateTrustConfigurationCallbackAnnotationContext, Task> callback)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L2461-L2464

Parameters

builder IResourceBuilder<TResource> The resource builder.

callback Func<CertificateTrustConfigurationCallbackAnnotationContext, Task> The callback to invoke when a resource needs to configure itself for custom certificate trust.

Returns

IResourceBuilder<TResource> The updated resource builder.

Remarks

Add an environment variable that needs to reference the path to the certificate bundle for the container resource:

var container = builder.AddContainer("my-service", "my-service:latest")
    .WithCertificateTrustConfigurationCallback(ctx =>
    {
        if (ctx.Scope != CertificateTrustScope.Append)
        {
            ctx
                .EnvironmentVariables["CUSTOM_CERTS_BUNDLE_ENV"] = ctx
                .CertificateBundlePath;
        }
        ctx
            .EnvironmentVariables["ADDITIONAL_CERTS_DIR_ENV"] = ctx
            .CertificateDirectoriesPath;
    });

WithCertificateTrustScope(IResourceBuilder<TResource>, CertificateTrustScope) extension 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.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<TResource> WithCertificateTrustScope<TResource>(
        this IResourceBuilder<TResource> builder,
        CertificateTrustScope scope)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L2416-L2429

Parameters

builder IResourceBuilder<TResource> The resource builder.

scope CertificateTrustScope The scope to apply to custom certificate authorities associated with the resource.

Returns

IResourceBuilder<TResource> The ApplicationModel.IResourceBuilder`1.

Remarks

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")
    .WithCertificate(new X509Certificate2("my-ca.pem"));

var container = builder.AddContainer("my-service", "my-service:latest")
    .WithCertificateAuthorityCollection(caCollection)
    .WithCertificateTrustScope(CertificateTrustScope.Override);

WithChildRelationship(IResourceBuilder<T>, IResourceBuilder<IResource>) extension IResourceBuilder<T>

Adds a ResourceRelationshipAnnotation to the resource annotations to add a parent-child relationship.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithChildRelationship<T>(
        this IResourceBuilder<T> builder,
        IResourceBuilder<IResource> child)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder.

child IResourceBuilder<IResource> The child of builder.

Returns

IResourceBuilder<T> A resource builder.

Remarks

The WithChildRelationship method is used to add child relationships to the resource. Relationships are used to link resources together in UI.

This example shows adding a relationship between two resources.

var builder = DistributedApplication.CreateBuilder(args);

var parameter = builder.AddParameter("parameter");

var backend = builder.AddProject<Projects.Backend>("backend");
                     .WithChildRelationship(parameter);

WithChildRelationship(IResourceBuilder<T>, IResource) extension IResourceBuilder<T>

Adds a ResourceRelationshipAnnotation to the resource annotations to add a parent-child relationship.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithChildRelationship<T>(
        this IResourceBuilder<T> builder,
        IResource child)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder.

child IResource The child of builder.

Returns

IResourceBuilder<T> A resource builder.

Remarks

The WithChildRelationship method is used to add child relationships to the resource. Relationships are used to link resources together in UI.

This example shows adding a relationship between two resources.

var builder = DistributedApplication.CreateBuilder(args);

var parameter = builder.AddParameter("parameter");

var backend = builder.AddProject<Projects.Backend>("backend");
                    .WithChildRelationship(parameter.Resource);

WithCommand(IResourceBuilder<T>, string, string, Func<ExecuteCommandContext, Task<ExecuteCommandResult>>, CommandOptions?) extension IResourceBuilder<T>

Adds a ResourceCommandAnnotation to the resource annotations to add a resource command.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithCommand<T>(
        this IResourceBuilder<T> builder,
        string name,
        string displayName,
        Func<ExecuteCommandContext, Task<ExecuteCommandResult>> executeCommand,
        CommandOptions? commandOptions = null)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L1956-L1970

Parameters

builder IResourceBuilder<T> The resource builder.

name string The name of the command. The name uniquely identifies the command.

displayName string The display name visible in UI.

executeCommand Func<ExecuteCommandContext, Task<ExecuteCommandResult>> A callback that is executed when the command is executed. The callback is run inside the .NET Aspire host. The callback result is used to indicate success or failure in the UI.

commandOptions CommandOptions? optional Optional configuration for the command.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

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 .NET Aspire host.

Obsolete — This method is obsolete and will be removed in a future version. Use the overload that accepts a CommandOptions instance instead.

WithCommand(IResourceBuilder<T>, string, string, Func<ExecuteCommandContext, Task<ExecuteCommandResult>>, Func<UpdateCommandStateContext, ResourceCommandState>, string?, object?, string?, string?, IconVariant?, bool) extension IResourceBuilder<T>

Adds a ResourceCommandAnnotation to the resource annotations to add a resource command.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithCommand<T>(
        this IResourceBuilder<T> builder,
        string name,
        string displayName,
        Func<ExecuteCommandContext, Task<ExecuteCommandResult>> executeCommand,
        Func<UpdateCommandStateContext, ResourceCommandState>? updateState = null,
        string? displayDescription = null,
        object? parameter = null,
        string? confirmationMessage = null,
        string? iconName = null,
        IconVariant? iconVariant = null,
        bool isHighlighted = false)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L2023-L2035

Parameters

builder IResourceBuilder<T> The resource builder.

name string The name of the command. The name uniquely identifies the command.

displayName string The display name visible in UI.

executeCommand Func<ExecuteCommandContext, Task<ExecuteCommandResult>> A callback that is executed when the command is executed. The callback is run inside the .NET Aspire host. The callback result is used to indicate success or failure in the UI.

updateState Func<UpdateCommandStateContext, ResourceCommandState> optional

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.

displayDescription string? optional Optional description of the command, to be shown in the UI. Could be used as a tooltip. May be localized.

parameter object? optional Optional parameter that configures the command in some way. Clients must return any value provided by the server when invoking the command.

confirmationMessage string? optional When a confirmation message is specified, the UI will prompt with an OK/Cancel dialog and the confirmation message before starting the command.

iconName string? optional The icon name for the command. The name should be a valid FluentUI icon name from https://aka.ms/fluentui-system-icons

iconVariant IconVariant? optional The icon variant.

isHighlighted bool optional A flag indicating whether the command is highlighted in the UI.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

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 .NET Aspire host.

WithComputeEnvironment(IResourceBuilder<T>, IResourceBuilder<IComputeEnvironmentResource>) extension IResourceBuilder<T>

Configures the compute environment for the compute resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithComputeEnvironment<T>(
        this IResourceBuilder<T> builder,
        IResourceBuilder<IComputeEnvironmentResource> computeEnvironmentResource)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L2948-L2952

Parameters

builder IResourceBuilder<T> The compute resource builder.

computeEnvironmentResource IResourceBuilder<IComputeEnvironmentResource> The compute environment resource to associate with the compute resource.

Returns

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

Remarks

This method allows associating a specific compute environment with the compute resource.

WithConnectionProperty(IResourceBuilder<T>, string, ReferenceExpression) extension IResourceBuilder<T>

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.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithConnectionProperty<T>(
        this IResourceBuilder<T> builder,
        string name,
        ReferenceExpression value)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder to which the connection property annotation will be added. Cannot be null.

name string The name of the connection property to annotate. Cannot be null.

value ReferenceExpression The 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.

WithConnectionProperty(IResourceBuilder<T>, string, string) extension IResourceBuilder<T>

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.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithConnectionProperty<T>(
        this IResourceBuilder<T> builder,
        string name,
        string value)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder to which the connection property will be added. Cannot be null.

name string The name of the connection property to add. Cannot be null.

value string The value to assign to the connection property.

Returns

IResourceBuilder<T> The same resource builder instance with the specified connection property annotation applied.

WithConnectionStringRedirection(IResourceBuilder<T>, IResourceWithConnectionString) extension IResourceBuilder<T>

Registers a callback which is invoked when a connection string is requested for a resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithConnectionStringRedirection<T>(
        this IResourceBuilder<T> builder,
        IResourceWithConnectionString resource)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L421-L425

Parameters

builder IResourceBuilder<T> The resource builder.

resource IResourceWithConnectionString Resource to which connection string generation is redirected.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

WithContainerFilesSource(IResourceBuilder<T>, string) extension IResourceBuilder<T>

Adds a container files source annotation to the resource being built, specifying the path to the container files source.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithContainerFilesSource<T>(
        this IResourceBuilder<T> builder,
        string sourcePath)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L1384-L1390

Parameters

builder IResourceBuilder<T> The resource builder to which the container files source annotation will be added. Cannot be null.

sourcePath string The path to the container files source to associate with the resource. Cannot be null.

Returns

IResourceBuilder<T> The resource builder instance with the container files source annotation applied.

Experimental — ASPIREEXTENSION001

WithDebugSupport(IResourceBuilder<T>, Func<string, TLaunchConfiguration>, string, Action<CommandLineArgsCallbackContext>) extension IResourceBuilder<T>

Adds support for debugging the resource in VS Code when running in an extension host.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithDebugSupport<T, TLaunchConfiguration>(
        this IResourceBuilder<T> builder,
        Func<string, TLaunchConfiguration> launchConfigurationProducer,
        string launchConfigurationType,
        Action<CommandLineArgsCallbackContext>? argsCallback = null)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L2966-L2986

Parameters

builder IResourceBuilder<T> The resource builder.

launchConfigurationProducer Func<string, TLaunchConfiguration> Launch configuration producer for the resource.

launchConfigurationType string The type of the resource.

argsCallback Action<CommandLineArgsCallbackContext> optional Optional callback to add or modify command line arguments when running in an extension host. Useful if the entrypoint is usually provided as an argument to the resource executable.

WithDeveloperCertificateTrust(IResourceBuilder<TResource>, bool) extension 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.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<TResource> WithDeveloperCertificateTrust<TResource>(
        this IResourceBuilder<TResource> builder,
        bool trust)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L2368-L2381

Parameters

builder IResourceBuilder<TResource> The resource builder.

trust bool Indicates whether the developer certificate should be treated as trusted.

Returns

IResourceBuilder<TResource> The ApplicationModel.IResourceBuilder`1.

Remarks

Disable trust for app host managed developer certificate(s) for a container resource.

var container = builder.AddContainer("my-service", "my-service:latest")
    .WithDeveloperCertificateTrust(false);

Disable automatic trust for app host managed developer certificate(s), but explicitly enable it for a specific resource.

var builder = DistributedApplication.CreateBuilder(
    new DistributedApplicationOptions()
{
    Args = args,
    TrustDeveloperCertificate = false,
});
var project = builder.AddProject<MyService>("my-service")
   .WithDeveloperCertificateTrust(true);

WithEndpoint(IResourceBuilder<T>, string, Action<EndpointAnnotation>, bool) extension IResourceBuilder<T>

Changes an existing endpoint or creates a new endpoint if it doesn't exist and invokes callback to modify the defaults.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithEndpoint<T>(
        this IResourceBuilder<T> builder,
        string endpointName,
        Action<EndpointAnnotation> callback,
        bool createIfNotExists = true)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L837-L866

Parameters

builder IResourceBuilder<T> Resource builder for resource with endpoints.

endpointName string Name of endpoint to change.

callback Action<EndpointAnnotation> Callback that modifies the endpoint.

createIfNotExists bool optional Create endpoint if it does not exist.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

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";
                       });

WithEndpoint(IResourceBuilder<T>, int?, int?, string?, string?, string?, bool, bool?, ProtocolType?) extension IResourceBuilder<T>

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.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithEndpoint<T>(
        this IResourceBuilder<T> builder,
        int? port = null,
        int? targetPort = null,
        string? scheme = null,
        string? name = null,
        string? env = null,
        bool isProxied = true,
        bool? isExternal = null,
        ProtocolType? protocol = null)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L888-L922

Parameters

builder IResourceBuilder<T> The resource builder.

port int? optional An optional port. This is the port that will be given to other resource to communicate with this resource.

targetPort int? optional This is the port the resource is listening on. If the endpoint is used for the container, it is the container port.

scheme string? optional An optional scheme e.g. (http/https). Defaults to the protocol argument if it is defined or "tcp" otherwise.

name string? optional An optional name of the endpoint. Defaults to the scheme name if not specified.

env string? optional 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.

isProxied bool optional Specifies if the endpoint will be proxied by DCP. Defaults to true.

isExternal bool? optional Indicates that this endpoint should be exposed externally at publish time.

protocol ProtocolType? optional Network protocol: TCP or UDP are supported today, others possibly in future.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Exceptions

DistributedApplicationException Throws an exception if an endpoint with the same name already exists on the specified resource.

WithEndpoint(IResourceBuilder<T>, int?, int?, string?, string?, string?, bool, bool?) extension IResourceBuilder<T>

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.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithEndpoint<T>(
        this IResourceBuilder<T> builder,
        int? port,
        int? targetPort,
        string? scheme,
        string? name,
        string? env,
        bool isProxied,
        bool? isExternal)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L942

Parameters

builder IResourceBuilder<T> The resource builder.

port int? An optional port. This is the port that will be given to other resource to communicate with this resource.

targetPort int? This is the port the resource is listening on. If the endpoint is used for the container, it is the container port.

scheme string? An optional scheme e.g. (http/https). Defaults to "tcp" if not specified.

name string? An optional name of the endpoint. Defaults to the scheme name if not specified.

env string? 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.

isProxied bool Specifies if the endpoint will be proxied by DCP. Defaults to true.

isExternal bool? Indicates that this endpoint should be exposed externally at publish time.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Exceptions

DistributedApplicationException Throws an exception if an endpoint with the same name already exists on the specified resource.

WithEnvironment(IResourceBuilder<T>, string, string?) extension IResourceBuilder<T>

Adds an environment variable to the resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithEnvironment<T>(
        this IResourceBuilder<T> builder,
        string name,
        string? value)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder.

name string The name of the environment variable.

value string? The value of the environment variable.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

WithEnvironment(IResourceBuilder<T>, string, ExpressionInterpolatedStringHandler) extension IResourceBuilder<T>

Adds an environment variable to the resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithEnvironment<T>(
        this IResourceBuilder<T> builder,
        string name,
        in ExpressionInterpolatedStringHandler value)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder.

name string The name of the environment variable.

value ExpressionInterpolatedStringHandler The value of the environment variable.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

WithEnvironment(IResourceBuilder<T>, string, ReferenceExpression) extension IResourceBuilder<T>

Adds an environment variable to the resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithEnvironment<T>(
        this IResourceBuilder<T> builder,
        string name,
        ReferenceExpression value)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder.

name string The name of the environment variable.

value ReferenceExpression The value of the environment variable.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

WithEnvironment(IResourceBuilder<T>, string, Func<string>) extension IResourceBuilder<T>

Adds an environment variable to the resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithEnvironment<T>(
        this IResourceBuilder<T> builder,
        string name,
        Func<string> callback)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L99-L103

Parameters

builder IResourceBuilder<T> The resource builder.

name string The name of the environment variable.

callback Func<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.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

WithEnvironment(IResourceBuilder<T>, Action<EnvironmentCallbackContext>) extension IResourceBuilder<T>

Allows for the population of environment variables on a resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithEnvironment<T>(
        this IResourceBuilder<T> builder,
        Action<EnvironmentCallbackContext> callback)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder.

callback Action<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.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

WithEnvironment(IResourceBuilder<T>, Func<EnvironmentCallbackContext, Task>) extension IResourceBuilder<T>

Allows for the population of environment variables on a resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithEnvironment<T>(
        this IResourceBuilder<T> builder,
        Func<EnvironmentCallbackContext, Task> callback)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder.

callback Func<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.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

WithEnvironment(IResourceBuilder<T>, string, EndpointReference) extension IResourceBuilder<T>

Adds an environment variable to the resource with the endpoint for endpointReference.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithEnvironment<T>(
        this IResourceBuilder<T> builder,
        string name,
        EndpointReference endpointReference)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L147-L156

Parameters

builder IResourceBuilder<T> The resource builder.

name string The name of the environment variable.

endpointReference EndpointReference The endpoint from which to extract the url.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

WithEnvironment(IResourceBuilder<T>, string, IResourceBuilder<ExternalServiceResource>) extension IResourceBuilder<T>

Adds an environment variable to the resource with the URL from the ExternalServiceResource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithEnvironment<T>(
        this IResourceBuilder<T> builder,
        string name,
        IResourceBuilder<ExternalServiceResource> externalService)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L170-L197

Parameters

builder IResourceBuilder<T> The resource builder.

name string The name of the environment variable.

externalService IResourceBuilder<ExternalServiceResource> The external service.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

WithEnvironment(IResourceBuilder<T>, string, IResourceBuilder<ParameterResource>) extension IResourceBuilder<T>

Adds an environment variable to the resource with the value from parameter.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithEnvironment<T>(
        this IResourceBuilder<T> builder,
        string name,
        IResourceBuilder<ParameterResource> parameter)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L210-L219

Parameters

builder IResourceBuilder<T> The resource builder.

name string Name of environment variable.

parameter IResourceBuilder<ParameterResource> Resource builder for the parameter resource.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

WithEnvironment(IResourceBuilder<T>, string, IResourceBuilder<IResourceWithConnectionString>) extension IResourceBuilder<T>

Adds an environment variable to the resource with the connection string from the referenced resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithEnvironment<T>(
        this IResourceBuilder<T> builder,
        string envVarName,
        IResourceBuilder<IResourceWithConnectionString> resource)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L236-L245

Parameters

builder IResourceBuilder<T> The destination resource builder to which the environment variable will be added.

envVarName string The name of the environment variable under which the connection string will be set.

resource IResourceBuilder<IResourceWithConnectionString> The resource builder of the referenced service from which to pull the connection string.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

WithEnvironment(IResourceBuilder<T>, string, TValue) extension IResourceBuilder<T>

Adds an environment variable to the resource with a value that implements both IValueProvider and IManifestExpressionProvider.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithEnvironment<T, TValue>(
        this IResourceBuilder<T> builder,
        string name,
        TValue value)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder.

name string The name of the environment variable.

value TValue The value that provides both runtime values and manifest expressions.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

WithExplicitStart(IResourceBuilder<T>) extension IResourceBuilder<T>

Adds a ExplicitStartupAnnotation annotation to the resource so it doesn't automatically start with the app host startup.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithExplicitStart<T>(
        this IResourceBuilder<T> builder)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L1670

Parameters

builder IResourceBuilder<T> The resource builder.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

This method is useful when a resource shouldn't automatically start when the app host starts.

The database clean up tool project isn't started with the app host. The resource start command can be used to run it ondemand later.

var builder = DistributedApplication.CreateBuilder(args);
var pgsql = builder.AddPostgres("postgres");
builder.AddProject<Projects.CleanUpDatabase>("dbcleanuptool")
       .WithReference(pgsql)
       .WithExplicitStart();

WithExternalHttpEndpoints(IResourceBuilder<T>) extension IResourceBuilder<T>

Marks existing http or https endpoints on a resource as external.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithExternalHttpEndpoints<T>(
        this IResourceBuilder<T> builder)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L993-L1008

Parameters

builder IResourceBuilder<T> The resource builder.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

WithHealthCheck(IResourceBuilder<T>, string) extension IResourceBuilder<T>

Adds a HealthCheckAnnotation to the resource annotations to associate a resource with a named health check managed by the health check service.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithHealthCheck<T>(
        this IResourceBuilder<T> builder,
        string key)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L1757-L1767

Parameters

builder IResourceBuilder<T> The resource builder.

key string The key for the health check.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

The ResourceBuilderExtensions.WithHealthCheck method is used in conjunction with the ResourceBuilderExtensions.WaitFor to associate a resource registered in the application hosts dependency injection container. The ResourceBuilderExtensions.WithHealthCheck method does not inject the health check itself it is purely an association mechanism.

Define a custom health check and associate it with a resource.

var builder = DistributedApplication.CreateBuilder(args);

var startAfter = DateTime.Now.AddSeconds(30);

builder.Services.AddHealthChecks().AddCheck(mycheck", () =>
{
    return DateTime.Now > startAfter ? HealthCheckResult.Healthy(
        ) : HealthCheckResult.Unhealthy();
});

var pg = builder.AddPostgres("pg")
                .WithHealthCheck("mycheck");

builder.AddProject<Projects.MyApp>("myapp")
       .WithReference(pg)
       .WaitFor(
           pg); // This will result in waiting for the building check, and the
                     // custom check defined in the code.

WithHttpCommand(IResourceBuilder<TResource>, string, string, string?, string?, HttpCommandOptions?) extension IResourceBuilder<TResource>

Adds a command to the resource that when invoked sends an HTTP request to the specified endpoint and path.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<TResource> WithHttpCommand<TResource>(
        this IResourceBuilder<TResource> builder,
        string path,
        string displayName,
        string? endpointName = null,
        string? commandName = null,
        HttpCommandOptions? commandOptions = null)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L2119-L2126

Parameters

builder IResourceBuilder<TResource> The resource builder.

path string The path to send the request to when the command is invoked.

displayName string The display name visible in UI.

endpointName string? optional The name of the HTTP endpoint on this resource to send the request to when the command is invoked.

commandName string? optional Optional 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.

commandOptions HttpCommandOptions? optional Optional configuration for the command.

Returns

IResourceBuilder<TResource> The ApplicationModel.IResourceBuilder`1.

Remarks

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.

If HttpCommandOptions.Method is not specified, POST will be used.

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 or other options using HttpClientFactoryServiceCollectionExtensions.AddHttpClient. If HttpCommandOptions.HttpClientName is not specified, the default Http.HttpClient will be used.

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 succesful if the response status code is in the 2xx range.

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);
                            return Task.CompletedTask;
                        }
                     });

WithHttpCommand(IResourceBuilder<TResource>, string, string, Func<EndpointReference>, string?, HttpCommandOptions?) extension IResourceBuilder<TResource>

Adds a command to the resource that when invoked sends an HTTP request to the specified endpoint and path.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<TResource> WithHttpCommand<TResource>(
        this IResourceBuilder<TResource> builder,
        string path,
        string displayName,
        Func<EndpointReference>? endpointSelector,
        string? commandName = null,
        HttpCommandOptions? commandOptions = null)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L2193-L2285

Parameters

builder IResourceBuilder<TResource> The resource builder.

path string The path to send the request to when the command is invoked.

displayName string The display name visible in UI.

endpointSelector Func<EndpointReference> A callback that selects the HTTP endpoint to send the request to when the command is invoked.

commandName string? optional The name of command. The name uniquely identifies the command.

commandOptions HttpCommandOptions? optional Optional configuration for the command.

Returns

IResourceBuilder<TResource> The ApplicationModel.IResourceBuilder`1.

Exceptions

DistributedApplicationException

Remarks

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.

If HttpCommandOptions.Method is not specified, POST will be used.

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 or other options using HttpClientFactoryServiceCollectionExtensions.AddHttpClient. If no HttpCommandOptions.HttpClientName is specified, the default Http.HttpClient will be used.

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 succesful if the response status code is in the 2xx range.

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")
    .WithHttpCommand(
        "/stress?resource=customer-service&requests=1000",
        "Apply load (1000)",
        endpointSelector: () => loadGeneratorEndpoint)
    .WithHttpCommand(
        "/stress?resource=customer-service&requests=5000",
        "Apply load (5000)",
        endpointSelector: () => loadGeneratorEndpoint);
loadGenerator.WithReference(customerService);

WithHttpEndpoint(IResourceBuilder<T>, int?, int?, string?, string?, bool) extension IResourceBuilder<T>

Exposes an HTTP endpoint on a resource. This endpoint reference can be retrieved using ResourceBuilderExtensions.GetEndpoint. The endpoint name will be "http" if not specified.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithHttpEndpoint<T>(
        this IResourceBuilder<T> builder,
        int? port = null,
        int? targetPort = null,
        string? name = null,
        string? env = null,
        bool isProxied = true)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L960-L962

Parameters

builder IResourceBuilder<T> The resource builder.

port int? optional An optional port. This is the port that will be given to other resource to communicate with this resource.

targetPort int? optional This is the port the resource is listening on. If the endpoint is used for the container, it is the container port.

name string? optional An optional name of the endpoint. Defaults to "http" if not specified.

env string? optional An optional name of the environment variable to inject.

isProxied bool optional Specifies if the endpoint will be proxied by DCP. Defaults to true.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Exceptions

DistributedApplicationException Throws an exception if an endpoint with the same name already exists on the specified resource.

WithHttpHealthCheck(IResourceBuilder<T>, string?, int?, string?) extension IResourceBuilder<T>

Adds a health check to the resource which is mapped to a specific endpoint.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithHttpHealthCheck<T>(
        this IResourceBuilder<T> builder,
        string? path = null,
        int? statusCode = null,
        string? endpointName = null)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L1801-L1807

Parameters

builder IResourceBuilder<T> A resource builder.

path string? optional The relative path to test.

statusCode int? optional The result code to interpret as healthy.

endpointName string? optional The name of the endpoint to derive the base address from.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

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")
                     .WithHttpHealthCheck("/health");
builder.AddProject<Projects.Frontend>("frontend")
       .WithReference(backend).WaitFor(backend);

WithHttpHealthCheck(IResourceBuilder<T>, Func<EndpointReference>, string?, int?) extension IResourceBuilder<T>

Adds a health check to the resource which is mapped to a specific endpoint.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithHttpHealthCheck<T>(
        this IResourceBuilder<T> builder,
        Func<EndpointReference>? endpointSelector,
        string? path = null,
        int? statusCode = null)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L1841-L1890

Parameters

builder IResourceBuilder<T> A resource builder.

endpointSelector Func<EndpointReference>

path string? optional The relative path to test.

statusCode int? optional The result code to interpret as healthy.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

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");
backend.WithHttpHealthCheck(() => backend.GetEndpoint("https"), path: "/health")
builder.AddProject<Projects.Frontend>("frontend")
       .WithReference(backend).WaitFor(backend);

Experimental — ASPIREPROBES001

WithHttpProbe(IResourceBuilder<T>, ProbeType, string?, int?, int?, int?, int?, int?, string?) extension IResourceBuilder<T>

Adds a HTTP probe to the resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithHttpProbe<T>(
        this IResourceBuilder<T> builder,
        ProbeType type,
        string? path = null,
        int? initialDelaySeconds = null,
        int? periodSeconds = null,
        int? timeoutSeconds = null,
        int? failureThreshold = null,
        int? successThreshold = null,
        string? endpointName = null)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L3025-L3031

Parameters

builder IResourceBuilder<T> Resource builder.

type ProbeType Type of the probe.

path string? optional The path to be used.

initialDelaySeconds int? optional The initial delay before calling the probe endpoint for the first time.

periodSeconds int? optional The period between each probe.

timeoutSeconds int? optional Number of seconds after which the probe times out.

failureThreshold int? optional Number of failures in a row before considers that the overall check has failed.

successThreshold int? optional Minimum consecutive successes for the probe to be considered successful after having failed.

endpointName string? optional The name of the endpoint to be used for the probe.

Returns

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

Remarks

This method allows you to specify a probe and implicit adds an http health check to the resource based on probe parameters.

For example add a probe to a resource in this way:

var service = builder.AddProject<Projects.MyService>("service")
    .WithHttpProbe(ProbeType.Liveness, "/health");

Is the same of writing:

var service = builder.AddProject<Projects.MyService>("service")
    .WithHttpProbe(ProbeType.Liveness, "/health")
    .WithHttpHealthCheck("/health");

Experimental — ASPIREPROBES001

WithHttpProbe(IResourceBuilder<T>, ProbeType, Func<EndpointReference>, string?, int?, int?, int?, int?, int?) extension IResourceBuilder<T>

Adds a HTTP probe to the resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithHttpProbe<T>(
        this IResourceBuilder<T> builder,
        ProbeType type,
        Func<EndpointReference>? endpointSelector,
        string? path = null,
        int? initialDelaySeconds = null,
        int? periodSeconds = null,
        int? timeoutSeconds = null,
        int? failureThreshold = null,
        int? successThreshold = null)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L3070-L3087

Parameters

builder IResourceBuilder<T> Resource builder.

type ProbeType Type of the probe.

endpointSelector Func<EndpointReference> The selector used to get endpoint reference.

path string? optional The path to be used.

initialDelaySeconds int? optional The initial delay before calling the probe endpoint for the first time.

periodSeconds int? optional The period between each probe.

timeoutSeconds int? optional Number of seconds after which the probe times out.

failureThreshold int? optional Number of failures in a row before considers that the overall check has failed.

successThreshold int? optional Minimum consecutive successes for the probe to be considered successful after having failed.

Returns

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

Remarks

This method allows you to specify a probe and implicit adds an http health check to the resource based on probe parameters.

For example add a probe to a resource in this way:

var service = builder.AddProject<Projects.MyService>("service")
    .WithHttpProbe(ProbeType.Liveness, "/health");

Is the same of writing:

var service = builder.AddProject<Projects.MyService>("service")
    .WithHttpProbe(ProbeType.Liveness, "/health")
    .WithHttpHealthCheck("/health");

Experimental — ASPIRECERTIFICATES001

WithHttpsCertificate(IResourceBuilder<TResource>, X509Certificate2, IResourceBuilder<ParameterResource>) extension IResourceBuilder<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.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<TResource> WithHttpsCertificate<TResource>(
        this IResourceBuilder<TResource> builder,
        X509Certificate2 certificate,
        IResourceBuilder<ParameterResource>? password = null)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L2523-L2531

Parameters

builder IResourceBuilder<TResource> The resource builder.

certificate X509Certificate2 An X509Certificates.X509Certificate2 key pair to use for HTTPS/TLS endpoints on the resource.

password IResourceBuilder<ParameterResource> optional A parameter specifying the password used to encrypt the certificate private key.

Returns

IResourceBuilder<TResource> The ApplicationModel.IResourceBuilder`1.

Remarks

Use a custom certificate for HTTPS/TLS endpoints on a container resource:

var certificate = new X509Certificate2("path/to/certificate.pfx", "password");
builder.AddContainer("my-service", "my-image")
   .WithHttpsCertificate(certificate);

Experimental — ASPIRECERTIFICATES001

WithHttpsCertificateConfiguration(IResourceBuilder<TResource>, Func<HttpsCertificateConfigurationCallbackAnnotationContext, Task>) extension IResourceBuilder<TResource>

Adds a callback that allows configuring the resource to use a specific HTTPS/TLS certificate key pair for server authentication.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<TResource> WithHttpsCertificateConfiguration<TResource>(
        this IResourceBuilder<TResource> builder,
        Func<HttpsCertificateConfigurationCallbackAnnotationContext, Task> callback)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L2589-L2594

Parameters

builder IResourceBuilder<TResource> The resource builder.

callback Func<HttpsCertificateConfigurationCallbackAnnotationContext, Task> The callback to configure the resource to use a certificate key pair.

Returns

IResourceBuilder<TResource> The updated resource builder.

Remarks

Pass the path to the PFX certificate file to the container arguments.

builder.AddContainer("my-service", "my-image")
    .WithHttpsCertificateConfiguration(ctx =>
    {
        ctx.Arguments.Add("--https-certificate-path");
        ctx.Arguments.Add(ctx.PfxPath);
        return Task.CompletedTask;
    });

Experimental — ASPIRECERTIFICATES001

WithHttpsDeveloperCertificate(IResourceBuilder<TResource>, IResourceBuilder<ParameterResource>) extension IResourceBuilder<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.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<TResource> WithHttpsDeveloperCertificate<TResource>(
        this IResourceBuilder<TResource> builder,
        IResourceBuilder<ParameterResource>? password = null)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L2489-L2497

Parameters

builder IResourceBuilder<TResource> The resource builder.

password IResourceBuilder<ParameterResource> optional A parameter specifying the password used to encrypt the certificate private key.

Returns

IResourceBuilder<TResource> The ApplicationModel.IResourceBuilder`1.

Remarks

Use the developer certificate for HTTPS/TLS endpoints on a container resource:

builder.AddContainer("my-service", "my-image")
    .WithHttpsDeveloperCertificate()

WithHttpsEndpoint(IResourceBuilder<T>, int?, int?, string?, string?, bool) extension IResourceBuilder<T>

Exposes an HTTPS endpoint on a resource. This endpoint reference can be retrieved using ResourceBuilderExtensions.GetEndpoint. The endpoint name will be "https" if not specified.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithHttpsEndpoint<T>(
        this IResourceBuilder<T> builder,
        int? port = null,
        int? targetPort = null,
        string? name = null,
        string? env = null,
        bool isProxied = true)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L980-L982

Parameters

builder IResourceBuilder<T> The resource builder.

port int? optional An optional host port.

targetPort int? optional This is the port the resource is listening on. If the endpoint is used for the container, it is the container port.

name string? optional An optional name of the endpoint. Defaults to "https" if not specified.

env string? optional An optional name of the environment variable to inject.

isProxied bool optional Specifies if the endpoint will be proxied by DCP. Defaults to true.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Exceptions

DistributedApplicationException Throws an exception if an endpoint with the same name already exists on the specified resource.

Obsolete — This method is obsolete and will be removed in a future version. Use the WithHttpHealthCheck method instead.

WithHttpsHealthCheck(IResourceBuilder<T>, string?, int?, string?) extension IResourceBuilder<T>

Adds a health check to the resource which is mapped to a specific endpoint.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithHttpsHealthCheck<T>(
        this IResourceBuilder<T> builder,
        string? path = null,
        int? statusCode = null,
        string? endpointName = null)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L1925-L1927

Parameters

builder IResourceBuilder<T> A resource builder.

path string? optional The relative path to test.

statusCode int? optional The result code to interpret as healthy.

endpointName string? optional The name of the endpoint to derive the base address from.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

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")
                     .WithHttpsHealthCheck("/health");
builder.AddProject<Projects.Frontend>("frontend")
       .WithReference(backend).WaitFor(backend);

WithIconName(IResourceBuilder<T>, string, IconVariant) extension IResourceBuilder<T>

Specifies the icon to use when displaying the resource in the dashboard.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithIconName<T>(
        this IResourceBuilder<T> builder,
        string iconName,
        IconVariant iconVariant = IconVariant.Filled)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L2930-L2933

Parameters

builder IResourceBuilder<T> The resource builder.

iconName string The name of the FluentUI icon to use. See https://aka.ms/fluentui-system-icons for available icons.

iconVariant IconVariant optional The variant of the icon (Regular or Filled). Defaults to Filled.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

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")
    .WithIconName("CloudArrowUp", IconVariant.Regular);

Experimental — ASPIREPIPELINES003

WithImagePushOptions(IResourceBuilder<T>, Action<ContainerImagePushOptionsCallbackContext>) extension IResourceBuilder<T>

Adds a callback to configure container image push options for the resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithImagePushOptions<T>(
        this IResourceBuilder<T> builder,
        Action<ContainerImagePushOptionsCallbackContext> callback)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder.

callback Action<ContainerImagePushOptionsCallbackContext> The callback to configure push options.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Exceptions

ArgumentNullException Thrown 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")
    .WithImagePushOptions(context =>
    {
        context.Options.RemoteImageName = "myorg/myapp";
        context.Options.RemoteImageTag = "v1.0.0";
    });

Experimental — ASPIREPIPELINES003

WithImagePushOptions(IResourceBuilder<T>, Func<ContainerImagePushOptionsCallbackContext, Task>) extension IResourceBuilder<T>

Adds an asynchronous callback to configure container image push options for the resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithImagePushOptions<T>(
        this IResourceBuilder<T> builder,
        Func<ContainerImagePushOptionsCallbackContext, Task> callback)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder.

callback Func<ContainerImagePushOptionsCallbackContext, Task> The asynchronous callback to configure push options.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Exceptions

ArgumentNullException Thrown 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")
    .WithImagePushOptions(async context =>
    {
        var config = await GetConfigurationAsync();
        context.Options.RemoteImageName = config.ImageName;
        context.Options.RemoteImageTag = config.ImageTag;
    });

WithManifestPublishingCallback(IResourceBuilder<T>, Action<ManifestPublishingContext>) extension IResourceBuilder<T>

Registers a callback which is invoked when manifest is generated for the app model.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithManifestPublishingCallback<T>(
        this IResourceBuilder<T> builder,
        Action<ManifestPublishingContext> callback)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder.

callback Action<ManifestPublishingContext> Callback method which takes a ManifestPublishingContext which can be used to inject JSON into the manifest.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

WithManifestPublishingCallback(IResourceBuilder<T>, Func<ManifestPublishingContext, Task>) extension IResourceBuilder<T>

Registers an async callback which is invoked when manifest is generated for the app model.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithManifestPublishingCallback<T>(
        this IResourceBuilder<T> builder,
        Func<ManifestPublishingContext, Task> callback)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder.

callback Func<ManifestPublishingContext, Task> Callback method which takes a ManifestPublishingContext which can be used to inject JSON into the manifest.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Experimental — ASPIRECERTIFICATES001

WithoutHttpsCertificate(IResourceBuilder<TResource>) extension IResourceBuilder<TResource>

Disable HTTPS/TLS server certificate configuration for the resource. No HTTPS/TLS termination configuration will be applied.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<TResource> WithoutHttpsCertificate<TResource>(
        this IResourceBuilder<TResource> builder)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L2553-L2561

Parameters

builder IResourceBuilder<TResource> The resource builder.

Returns

IResourceBuilder<TResource> The ApplicationModel.IResourceBuilder`1.

Remarks

Disable HTTPS certificate configuration for a Redis resource:

var redis = builder.AddRedis("cache")
    .WithoutHttpsCertificate();

WithParentRelationship(IResourceBuilder<T>, IResourceBuilder<IResource>) extension IResourceBuilder<T>

Adds a ResourceRelationshipAnnotation to the resource annotations to add a parent-child relationship.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithParentRelationship<T>(
        this IResourceBuilder<T> builder,
        IResourceBuilder<IResource> parent)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder.

parent IResourceBuilder<IResource> The parent of builder.

Returns

IResourceBuilder<T> A resource builder.

Remarks

The WithParentRelationship method is used to add parent relationships to the resource. Relationships are used to link resources together in UI.

This example shows adding a relationship between two resources.

var builder = DistributedApplication.CreateBuilder(args);
var backend = builder.AddProject<Projects.Backend>("backend");

var frontend = builder.AddProject<Projects.Manager>("frontend")
                     .WithParentRelationship(backend);

WithParentRelationship(IResourceBuilder<T>, IResource) extension IResourceBuilder<T>

Adds a ResourceRelationshipAnnotation to the resource annotations to add a parent-child relationship.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithParentRelationship<T>(
        this IResourceBuilder<T> builder,
        IResource parent)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The resource builder.

parent IResource The parent of builder.

Returns

IResourceBuilder<T> A resource builder.

Remarks

The WithParentRelationship method is used to add parent relationships to the resource. Relationships are used to link resources together in UI.

This example shows adding a relationship between two resources.

var builder = DistributedApplication.CreateBuilder(args);
var backend = builder.AddProject<Projects.Backend>("backend");

var frontend = builder.AddProject<Projects.Manager>("frontend")
                     .WithParentRelationship(backend.Resource);

WithReference(IResourceBuilder<TDestination>, IResourceBuilder<IResourceWithConnectionString>, string?, bool) extension IResourceBuilder<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 format of the environment variable will be "ConnectionStrings__{sourceResourceName}={connectionString}".

Each resource defines the format of the connection string value. The underlying connection string value can be retrieved using IResourceWithConnectionString.GetConnectionStringAsync.

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.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<TDestination> WithReference<TDestination>(
        this IResourceBuilder<TDestination> builder,
        IResourceBuilder<IResourceWithConnectionString> source,
        string? connectionName = null,
        bool optional = false)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L508-L546

Parameters

builder IResourceBuilder<TDestination> The resource where connection string will be injected.

source IResourceBuilder<IResourceWithConnectionString> The resource from which to extract the connection string.

connectionName string? optional An override of the source resource's name for the connection string. The resulting connection string will be "ConnectionStrings__connectionName" if this is not null.

optional bool optional true to allow a missing connection string; false to throw an exception if the connection string is not found.

Returns

IResourceBuilder<TDestination> The ApplicationModel.IResourceBuilder`1.

Exceptions

DistributedApplicationException Throws 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.

WithReference(IResourceBuilder<TDestination>, IResourceBuilder<IResourceWithServiceDiscovery>) extension IResourceBuilder<TDestination>

Injects service discovery and endpoint information as environment variables from the project resource into the destination resource, using the source resource's name as the service name. Each endpoint defined on the project resource will be injected using the format defined by the ReferenceEnvironmentInjectionAnnotation on the destination resource, i.e. either "services__{sourceResourceName}__{endpointName}__{endpointIndex}={uriString}" for .NET service discovery, or "{RESOURCE_ENDPOINT}={uri}" for endpoint injection.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<TDestination> WithReference<TDestination>(
        this IResourceBuilder<TDestination> builder,
        IResourceBuilder<IResourceWithServiceDiscovery> source)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L592-L596

Parameters

builder IResourceBuilder<TDestination> The resource where the service discovery information will be injected.

source IResourceBuilder<IResourceWithServiceDiscovery> The resource from which to extract service discovery information.

Returns

IResourceBuilder<TDestination> The ApplicationModel.IResourceBuilder`1.

WithReference(IResourceBuilder<TDestination>, IResourceBuilder<IResourceWithServiceDiscovery>, string) extension IResourceBuilder<TDestination>

Injects service discovery and endpoint information as environment variables from the project resource into the destination resource, using the source resource's name as the service name. Each endpoint defined on the project resource will be injected using the format defined by the ReferenceEnvironmentInjectionAnnotation on the destination resource, i.e. either "services__{name}__{endpointName}__{endpointIndex}={uriString}" for .NET service discovery, or "{name}_{ENDPOINT}={uri}" for endpoint injection.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<TDestination> WithReference<TDestination>(
        this IResourceBuilder<TDestination> builder,
        IResourceBuilder<IResourceWithServiceDiscovery> source,
        string name)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L612-L616

Parameters

builder IResourceBuilder<TDestination> The resource where the service discovery information will be injected.

source IResourceBuilder<IResourceWithServiceDiscovery> The resource from which to extract service discovery information.

name string The name of the resource for the environment variable.

Returns

IResourceBuilder<TDestination> The ApplicationModel.IResourceBuilder`1.

WithReference(IResourceBuilder<TDestination>, string, Uri) extension 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.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<TDestination> WithReference<TDestination>(
        this IResourceBuilder<TDestination> builder,
        string name,
        Uri uri)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L632-L670

Parameters

builder IResourceBuilder<TDestination> The resource where the service discovery information will be injected.

name string The name of the service.

uri Uri The uri of the service.

Returns

IResourceBuilder<TDestination> The ApplicationModel.IResourceBuilder`1.

WithReference(IResourceBuilder<TDestination>, IResourceBuilder<ExternalServiceResource>) extension IResourceBuilder<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}."

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<TDestination> WithReference<TDestination>(
        this IResourceBuilder<TDestination> builder,
        IResourceBuilder<ExternalServiceResource> externalService)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L684-L744

Parameters

builder IResourceBuilder<TDestination> The resource where the service discovery information will be injected.

externalService IResourceBuilder<ExternalServiceResource> The external service.

Returns

IResourceBuilder<TDestination> The ApplicationModel.IResourceBuilder`1.

WithReference(IResourceBuilder<TDestination>, EndpointReference) extension 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}__{endpointName}__{endpointIndex}={uriString}" for .NET service discovery, or "{NAME}_{ENDPOINT}={uri}" for endpoint injection.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<TDestination> WithReference<TDestination>(
        this IResourceBuilder<TDestination> builder,
        EndpointReference endpointReference)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L759-L763

Parameters

builder IResourceBuilder<TDestination> The resource where the service discovery information will be injected.

endpointReference EndpointReference The endpoint from which to extract the url.

Returns

IResourceBuilder<TDestination> The ApplicationModel.IResourceBuilder`1.

WithReferenceEnvironment(IResourceBuilder<TDestination>, ReferenceEnvironmentInjectionFlags) extension IResourceBuilder<TDestination>

Configures how information is injected into environment variables when the resource references other resources.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<TDestination> WithReferenceEnvironment<TDestination>(
        this IResourceBuilder<TDestination> builder,
        ReferenceEnvironmentInjectionFlags flags)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L481-L483

Parameters

builder IResourceBuilder<TDestination> The resource to configure.

flags ReferenceEnvironmentInjectionFlags The injection flags determining which reference information is emitted.

Returns

IResourceBuilder<TDestination> The ApplicationModel.IResourceBuilder`1.

WithReferenceRelationship(IResourceBuilder<T>, IResource) extension IResourceBuilder<T>

Adds a ResourceRelationshipAnnotation to the resource annotations to add a reference to another resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithReferenceRelationship<T>(
        this IResourceBuilder<T> builder,
        IResource resource)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L2694-L2697

Parameters

builder IResourceBuilder<T> The resource builder.

resource IResource The resource that the relationship is to.

Returns

IResourceBuilder<T> A resource builder.

WithReferenceRelationship(IResourceBuilder<T>, ReferenceExpression) extension IResourceBuilder<T>

Walks the reference expression and adds ResourceRelationshipAnnotation s for all resources found in the expression.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithReferenceRelationship<T>(
        this IResourceBuilder<T> builder,
        ReferenceExpression expression)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L2711-L2716

Parameters

builder IResourceBuilder<T> The resource builder.

expression ReferenceExpression The reference expression.

Returns

IResourceBuilder<T> A resource builder.

WithReferenceRelationship(IResourceBuilder<T>, IResourceBuilder<IResource>) extension IResourceBuilder<T>

Adds a ResourceRelationshipAnnotation to the resource annotations to add a reference to another resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithReferenceRelationship<T>(
        this IResourceBuilder<T> builder,
        IResourceBuilder<IResource> resourceBuilder)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L2770-L2773

Parameters

builder IResourceBuilder<T> The resource builder.

resourceBuilder IResourceBuilder<IResource> The resource builder that the relationship is to.

Returns

IResourceBuilder<T> A resource builder.

WithRelationship(IResourceBuilder<T>, IResource, string) extension IResourceBuilder<T>

Adds a ResourceRelationshipAnnotation to the resource annotations to add a relationship.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithRelationship<T>(
        this IResourceBuilder<T> builder,
        IResource resource,
        string type)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L2676-L2680

Parameters

builder IResourceBuilder<T> The resource builder.

resource IResource The resource that the relationship is to.

type string The relationship type.

Returns

IResourceBuilder<T> A resource builder.

Remarks

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");

Experimental — ASPIREPIPELINES003

WithRemoteImageName(IResourceBuilder<T>, string) extension IResourceBuilder<T>

Sets the remote image name (without registry endpoint or tag) for container push operations.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithRemoteImageName<T>(
        this IResourceBuilder<T> builder,
        string remoteImageName)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L3224-L3230

Parameters

builder IResourceBuilder<T> The resource builder.

remoteImageName string The remote image name (e.g., "myapp" or "myorg/myapp").

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Exceptions

ArgumentNullException Thrown when builder or remoteImageName is null.

Remarks

This is a convenience method that registers a callback to set the ContainerImagePushOptions.RemoteImageName property. The remote image name should not include the registry endpoint or tag. Those are managed separately. This method can be combined with ResourceBuilderExtensions.WithRemoteImageTag to fully customize the image reference.

Examples

Set a custom remote image name for a container:

var container = builder.AddContainer("myapp", "myapp:latest")
    .WithRemoteImageName("myorg/myapp");

Experimental — ASPIREPIPELINES003

WithRemoteImageTag(IResourceBuilder<T>, string) extension IResourceBuilder<T>

Sets the remote image tag for container push operations.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithRemoteImageTag<T>(
        this IResourceBuilder<T> builder,
        string remoteImageTag)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs#L3259-L3265

Parameters

builder IResourceBuilder<T> The resource builder.

remoteImageTag string The remote image tag (e.g., "latest", "v1.0.0").

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Exceptions

ArgumentNullException Thrown 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")
    .WithRemoteImageTag("v1.0.0");

WithUrl(IResourceBuilder<T>, string, string?) extension IResourceBuilder<T>

Adds a URL to be displayed for the resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithUrl<T>(
        this IResourceBuilder<T> builder,
        string url,
        string? displayText = null)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The builder for the resource.

url string A URL to show for the resource.

displayText string? optional The display text to show when the link is displayed.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

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")
                      .WithUrl("/home", "Home");

WithUrl(IResourceBuilder<T>, ExpressionInterpolatedStringHandler, string?) extension IResourceBuilder<T>

Adds a URL to be displayed for the resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithUrl<T>(
        this IResourceBuilder<T> builder,
        in ExpressionInterpolatedStringHandler url,
        string? displayText = null)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The builder for the resource.

url ExpressionInterpolatedStringHandler The interpolated string that produces the URL.

displayText string? optional The display text to show when the link is displayed.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

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.

WithUrl(IResourceBuilder<T>, ReferenceExpression, string?) extension IResourceBuilder<T>

Adds a URL to be displayed for the resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithUrl<T>(
        this IResourceBuilder<T> builder,
        ReferenceExpression url,
        string? displayText = null)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The builder for the resource.

url ReferenceExpression A ReferenceExpression that will produce the URL.

displayText string? optional The display text to show when the link is displayed.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

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.

WithUrlForEndpoint(IResourceBuilder<T>, string, Action<ResourceUrlAnnotation>) extension IResourceBuilder<T>

Registers a callback to update the URL displayed for the endpoint with the specified name.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithUrlForEndpoint<T>(
        this IResourceBuilder<T> builder,
        string endpointName,
        Action<ResourceUrlAnnotation> callback)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The builder for the resource.

endpointName string The name of the endpoint to customize the URL for.

callback Action<ResourceUrlAnnotation> The callback that will customize the URL.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

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")
                      .WithUrlForEndpoint("https", url => url.Url = "/home");

WithUrlForEndpoint(IResourceBuilder<T>, string, Func<EndpointReference, ResourceUrlAnnotation>) extension IResourceBuilder<T>

Registers a callback to add a URL for the endpoint with the specified name.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithUrlForEndpoint<T>(
        this IResourceBuilder<T> builder,
        string endpointName,
        Func<EndpointReference, ResourceUrlAnnotation> callback)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The builder for the resource.

endpointName string The name of the endpoint to add the URL for.

callback Func<EndpointReference, ResourceUrlAnnotation> The callback that will create the URL.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

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")
                      .WithUrlForEndpoint(
                          "https",
                          ep => new() { Url = "/admin",
                          DisplayText = "Admin" });

WithUrls(IResourceBuilder<T>, Action<ResourceUrlsCallbackContext>) extension IResourceBuilder<T>

Registers a callback to customize the URLs displayed for the resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithUrls<T>(
        this IResourceBuilder<T> builder,
        Action<ResourceUrlsCallbackContext> callback)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The builder for the resource.

callback Action<ResourceUrlsCallbackContext> The callback that will customize URLs for the resource.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

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 in c.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")
                      .WithUrls(c =>
                      {
                          foreach (var url in c.Urls)
                          {
                              if (url.Endpoint is not null)
                              {
                                  var uri = new UriBuilder(
                                      url.Url) { Host = $"{c.Resource.Name}.localhost" };
                                  url.Url = uri.ToString();
                              }
                          }
                      });

WithUrls(IResourceBuilder<T>, Func<ResourceUrlsCallbackContext, Task>) extension IResourceBuilder<T>

Registers an async callback to customize the URLs displayed for the resource.

public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<T> WithUrls<T>(
        this IResourceBuilder<T> builder,
        Func<ResourceUrlsCallbackContext, Task> callback)
    {
        // ...
    }
}

ResourceBuilderExtensions.cs

Parameters

builder IResourceBuilder<T> The builder for the resource.

callback Func<ResourceUrlsCallbackContext, Task> The async callback that will customize URLs for the resource.

Returns

IResourceBuilder<T> The ApplicationModel.IResourceBuilder`1.

Remarks

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.