# ResourceBuilderExtensions Methods

- Package: [Aspire.Hosting](/reference/api/csharp/aspire.hosting.md)
- Type: [ResourceBuilderExtensions](/reference/api/csharp/aspire.hosting/resourcebuilderextensions.md)
- Kind: `Methods`
- Members: `91`

Provides extension methods for configuring resources with environment variables.

## AsHttp2Service(IResourceBuilder<T>)

- Name: `AsHttp2Service(IResourceBuilder<T>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L1590-L1592)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## ClearContainerFilesSources(IResourceBuilder<T>)

- Name: `ClearContainerFilesSources(IResourceBuilder<T>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L1971-L1978)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder to which the container files source annotations should be removed. Cannot be null.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The resource builder instance with the container files source annotation applied.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## ExcludeFromManifest(IResourceBuilder<T>)

- Name: `ExcludeFromManifest(IResourceBuilder<T>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L1990-L1992)

Excludes a resource from being published to the manifest.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource to exclude.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## ExcludeFromMcp(IResourceBuilder<T>)

- Name: `ExcludeFromMcp(IResourceBuilder<T>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3986-L3988)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## GetConnectionProperty(IResourceWithConnectionString, string)

- Name: `GetConnectionProperty(IResourceWithConnectionString, string)`
- Modifiers: `extension`
- Returns: [ReferenceExpression](/reference/api/csharp/aspire.hosting/referenceexpression.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L969-L978)

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

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

## Parameters

- `resource` ([IResourceWithConnectionString](/reference/api/csharp/aspire.hosting/iresourcewithconnectionstring.md))
  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](/reference/api/csharp/aspire.hosting/referenceexpression.md) -- 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.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## GetEndpoint(IResourceBuilder<T>, string, NetworkIdentifier)

- Name: `GetEndpoint(IResourceBuilder<T>, string, NetworkIdentifier)`
- Modifiers: `extension`
- Returns: [EndpointReference](/reference/api/csharp/aspire.hosting/endpointreference.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L1560-L1562)

Gets an [EndpointReference](/reference/api/csharp/aspire.hosting/endpointreference.md) by name from the resource. These endpoints are declared either using [ResourceBuilderExtensions.WithEndpoint(IResourceBuilder<T>, string, Action<EndpointAnnotation>, bool)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withendpoint-iresourcebuilder-t-string-action-endpointannotation-bool) or by launch settings (for project resources). The [EndpointReference](/reference/api/csharp/aspire.hosting/endpointreference.md) can be used to resolve the address of the endpoint in [ResourceBuilderExtensions.WithEnvironment(IResourceBuilder<T>, string, string?)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withenvironment-iresourcebuilder-t-string-string).

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The the resource builder.
- `name` (`string`)
  The name of the endpoint.
- `contextNetworkID` ([NetworkIdentifier](/reference/api/csharp/aspire.hosting/networkidentifier.md))
  The network context in which to resolve the endpoint. If null, localhost (loopback) network context will be used.

## Returns

[EndpointReference](/reference/api/csharp/aspire.hosting/endpointreference.md) -- An [EndpointReference](/reference/api/csharp/aspire.hosting/endpointreference.md) that can be used to resolve the address of the endpoint after resource allocation has occurred.

## Remarks

This method is not available in polyglot app hosts. Use the overload without NetworkIdentifier instead.

## ATS metadata

### Ignored by ATS

- Reason: NetworkIdentifier is not ATS-compatible.

## GetEndpoint(IResourceBuilder<T>, string)

- Name: `GetEndpoint(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: [EndpointReference](/reference/api/csharp/aspire.hosting/endpointreference.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L1576-L1578)

Gets an [EndpointReference](/reference/api/csharp/aspire.hosting/endpointreference.md) by name from the resource. These endpoints are declared either using [ResourceBuilderExtensions.WithEndpoint(IResourceBuilder<T>, string, Action<EndpointAnnotation>, bool)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withendpoint-iresourcebuilder-t-string-action-endpointannotation-bool) or by launch settings (for project resources). The [EndpointReference](/reference/api/csharp/aspire.hosting/endpointreference.md) can be used to resolve the address of the endpoint in [ResourceBuilderExtensions.WithEnvironment(IResourceBuilder<T>, string, string?)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withenvironment-iresourcebuilder-t-string-string).

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The the resource builder.
- `name` (`string`)
  The name of the endpoint.

## Returns

[EndpointReference](/reference/api/csharp/aspire.hosting/endpointreference.md) -- An [EndpointReference](/reference/api/csharp/aspire.hosting/endpointreference.md) that can be used to resolve the address of the endpoint after resource allocation has occurred.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `PublishWithContainerFiles(IResourceBuilder<T>, IResourceBuilder<IResourceWithContainerFiles>, string)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L1923-L1936)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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.

## ATS metadata

### ATS export

- Capability ID: `Aspire.Hosting/publishWithContainerFilesFromResource`
- Generated method name override: `publishWithContainerFiles`

## SubscribeHttpsEndpointsUpdate(IResourceBuilder<TResource>, Action<HttpsEndpointUpdateCallbackContext>)

> **Experimental:** ASPIRECERTIFICATES001 - [Learn more](/diagnostics/aspirecertificates001/)

- Name: `SubscribeHttpsEndpointsUpdate(IResourceBuilder<TResource>, Action<HttpsEndpointUpdateCallbackContext>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<TResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3372-L3409)

Subscribes to the [BeforeStartEvent](/reference/api/csharp/aspire.hosting/beforestartevent.md) and invokes the specified callback when an HTTPS certificate is determined to be available for the resource. This is used to conditionally update endpoint URI schemes or perform other HTTPS-related configuration at startup.

```csharp
public static class ResourceBuilderExtensions
{
    public static IResourceBuilder<TResource> SubscribeHttpsEndpointsUpdate<TResource>(
        this IResourceBuilder<TResource> builder,
        Action<HttpsEndpointUpdateCallbackContext> callback)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<TResource>`)
  The resource builder.
- `callback` (`Action<HttpsEndpointUpdateCallbackContext>`)
  The callback to invoke when HTTPS is enabled. Receives an [HttpsEndpointUpdateCallbackContext](/reference/api/csharp/aspire.hosting/httpsendpointupdatecallbackcontext.md) providing access to the service provider, resource, and application model.

## Returns

`IResourceBuilder<TResource>` -- The updated resource builder.

## Remarks

The callback is invoked when either:

- No [HttpsCertificateAnnotation](/reference/api/csharp/aspire.hosting/httpscertificateannotation.md) is present and the [IDeveloperCertificateService](/reference/api/csharp/aspire.hosting/idevelopercertificateservice.md) indicates that HTTPS should be used by default.
- An [HttpsCertificateAnnotation](/reference/api/csharp/aspire.hosting/httpscertificateannotation.md) is present that requests a developer certificate or provides a custom certificate.

Switch an endpoint to HTTPS when a certificate is available:

```csharp
builder.SubscribeHttpsEndpointsUpdate(ctx =>
{
    builder.WithEndpoint("http", ep => ep.UriScheme = "https");
});
```

This method is not available in polyglot app hosts.

## ATS metadata

### Ignored by ATS

- Reason: HttpsEndpointUpdateCallbackContext exposes IServiceProvider and IResource -- not usable from polyglot hosts.

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

- Name: `WaitFor(IResourceBuilder<T>, IResourceBuilder<IResource>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L2025-L2028)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder for the resource that will be waiting.
- `dependency` (`IResourceBuilder<IResource>`)
  The resource builder for the dependency resource.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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(IResourceBuilder<T>, IResourceBuilder<IResource>)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#waitfor-iresourcebuilder-t-iresourcebuilder-iresource) also results in the resource being blocked from starting until the health checks associated with the dependency resource return `HealthStatus.Healthy`.

The [ResourceBuilderExtensions.WithHealthCheck(IResourceBuilder<T>, string)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withhealthcheck-iresourcebuilder-t-string) method can be used to associate additional health checks with a resource.

Start message queue before starting the worker service.

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

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the internal waitFor dispatcher export.

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

- Name: `WaitFor(IResourceBuilder<T>, IResourceBuilder<IResource>, WaitBehavior)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L2082-L2085)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder for the resource that will be waiting.
- `dependency` (`IResourceBuilder<IResource>`)
  The resource builder for the dependency resource.
- `waitBehavior` ([WaitBehavior](/reference/api/csharp/aspire.hosting/waitbehavior.md))
  The wait behavior to use.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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(IResourceBuilder<T>, IResourceBuilder<IResource>)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#waitfor-iresourcebuilder-t-iresourcebuilder-iresource) also results in the resource being blocked from starting until the health checks associated with the dependency resource return `HealthStatus.Healthy`.

The [ResourceBuilderExtensions.WithHealthCheck(IResourceBuilder<T>, string)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withhealthcheck-iresourcebuilder-t-string) 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](/reference/api/csharp/aspire.hosting/waitbehavior/fields.md) is specified, the wait operation will continue to wait until the resource becomes healthy. This is the default behavior with the [ResourceBuilderExtensions.WaitFor(IResourceBuilder<T>, IResourceBuilder<IResource>)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#waitfor-iresourcebuilder-t-iresourcebuilder-iresource) overload.

When [WaitBehavior.StopOnResourceUnavailable](/reference/api/csharp/aspire.hosting/waitbehavior/fields.md) is specified, the wait operation will throw a [DistributedApplicationException](/reference/api/csharp/aspire.hosting/distributedapplicationexception.md) if the resource enters an unavailable state.

Start message queue before starting the worker service.

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

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the internal waitFor dispatcher export.

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

- Name: `WaitForCompletion(IResourceBuilder<T>, IResourceBuilder<IResource>, int)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L2305-L2320)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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.

```csharp
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);
```

## ATS metadata

### ATS export

- Capability ID: `Aspire.Hosting/waitForResourceCompletion`
- Generated method name override: `waitForCompletion`

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

- Name: `WaitForStart(IResourceBuilder<T>, IResourceBuilder<IResource>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L2147-L2150)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder for the resource that will be waiting.
- `dependency` (`IResourceBuilder<IResource>`)
  The resource builder for the dependency resource.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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(IResourceBuilder<T>, IResourceBuilder<IResource>)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#waitfor-iresourcebuilder-t-iresourcebuilder-iresource), 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.

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

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the internal waitForStart dispatcher export.

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

- Name: `WaitForStart(IResourceBuilder<T>, IResourceBuilder<IResource>, WaitBehavior)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L2202-L2205)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder for the resource that will be waiting.
- `dependency` (`IResourceBuilder<IResource>`)
  The resource builder for the dependency resource.
- `waitBehavior` ([WaitBehavior](/reference/api/csharp/aspire.hosting/waitbehavior.md))
  The wait behavior to use.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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(IResourceBuilder<T>, IResourceBuilder<IResource>)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#waitfor-iresourcebuilder-t-iresourcebuilder-iresource), 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](/reference/api/csharp/aspire.hosting/waitbehavior/fields.md) 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(IResourceBuilder<T>, IResourceBuilder<IResource>)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#waitforstart-iresourcebuilder-t-iresourcebuilder-iresource) overload.

When [WaitBehavior.StopOnResourceUnavailable](/reference/api/csharp/aspire.hosting/waitbehavior/fields.md) is specified, the wait operation will throw a [DistributedApplicationException](/reference/api/csharp/aspire.hosting/distributedapplicationexception.md) if the resource enters an unavailable state.

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

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

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the internal waitForStart dispatcher export.

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

- Name: `WithArgs(IResourceBuilder<T>, string[])`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder for a resource implementing [IResourceWithArgs](/reference/api/csharp/aspire.hosting/iresourcewithargs.md).
- `args` (`string[]`)
  The arguments to be passed to the resource when it is started.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithArgs(IResourceBuilder<T>, object[])`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder for a resource implementing [IResourceWithArgs](/reference/api/csharp/aspire.hosting/iresourcewithargs.md).
- `args` (`object[]`)
  The arguments to be passed to the resource when it is started.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

This method is not available in polyglot app hosts. Use the string[] overload instead.

## ATS metadata

### Ignored by ATS

- Reason: object[] is not ATS-compatible. String[] overload is exported.

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

- Name: `WithArgs(IResourceBuilder<T>, Action<CommandLineArgsCallbackContext>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder for a resource implementing [IResourceWithArgs](/reference/api/csharp/aspire.hosting/iresourcewithargs.md).
- `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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### ATS export

- Capability ID: `Aspire.Hosting/withArgsCallback`

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

- Name: `WithArgs(IResourceBuilder<T>, Func<CommandLineArgsCallbackContext, Task>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder for a resource implementing [IResourceWithArgs](/reference/api/csharp/aspire.hosting/iresourcewithargs.md).
- `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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the synchronous Action<> overload via withArgsCallback.

## WithCertificateAuthorityCollection(IResourceBuilder<TResource>, IResourceBuilder<CertificateAuthorityCollection>)

- Name: `WithCertificateAuthorityCollection(IResourceBuilder<TResource>, IResourceBuilder<CertificateAuthorityCollection>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<TResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3044-L3064)

Adds a [CertificateAuthorityCollectionAnnotation](/reference/api/csharp/aspire.hosting/certificateauthoritycollectionannotation.md) 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.

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

## Parameters

- `builder` (`IResourceBuilder<TResource>`)
  The resource builder.
- `certificateAuthorityCollection` (`IResourceBuilder<CertificateAuthorityCollection>`)
  Additional certificates in a [CertificateAuthorityCollection](/reference/api/csharp/aspire.hosting/certificateauthoritycollection.md) 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.

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

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

This method is not available in polyglot app hosts.

## ATS metadata

### Ignored by ATS

- Reason: CertificateAuthorityCollection -- all companion With* methods require X509Certificate2, making the resource unusable in polyglot hosts.

## WithCertificateTrustConfiguration(IResourceBuilder<TResource>, Func<CertificateTrustConfigurationCallbackAnnotationContext, Task>)

- Name: `WithCertificateTrustConfiguration(IResourceBuilder<TResource>, Func<CertificateTrustConfigurationCallbackAnnotationContext, Task>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<TResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3197-L3200)

Adds a [CertificateTrustConfigurationCallbackAnnotation](/reference/api/csharp/aspire.hosting/certificatetrustconfigurationcallbackannotation.md) 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.

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

## 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:

```csharp
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;
    });
```

This method is not available in polyglot app hosts.

## ATS metadata

### Ignored by ATS

- Reason: CertificateTrustConfigurationCallbackAnnotationContext exposes IResource -- not usable from polyglot hosts. Callback-free variant is exported.

## WithCertificateTrustScope(IResourceBuilder<TResource>, CertificateTrustScope)

- Name: `WithCertificateTrustScope(IResourceBuilder<TResource>, CertificateTrustScope)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<TResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3150-L3163)

Sets the [CertificateTrustScope](/reference/api/csharp/aspire.hosting/certificatetrustscope.md) 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.

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

## Parameters

- `builder` (`IResourceBuilder<TResource>`)
  The resource builder.
- `scope` ([CertificateTrustScope](/reference/api/csharp/aspire.hosting/certificatetrustscope.md))
  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](/reference/api/csharp/aspire.hosting/certificatetrustscope/fields.md) which means that custom certificate authorities should be appended to the default trusted certificate authorities for the resource. Setting the scope to [CertificateTrustScope.Override](/reference/api/csharp/aspire.hosting/certificatetrustscope/fields.md) indicates the set of certificates in referenced [CertificateAuthorityCollection](/reference/api/csharp/aspire.hosting/certificateauthoritycollection.md) (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.

```csharp
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);
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithChildRelationship(IResourceBuilder<T>, IResourceBuilder<IResource>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

Adds a [ResourceRelationshipAnnotation](/reference/api/csharp/aspire.hosting/resourcerelationshipannotation.md) to the resource annotations to add a parent-child relationship.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `child` (`IResourceBuilder<IResource>`)
  The child of `builder`.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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.

```csharp
var builder = DistributedApplication.CreateBuilder(args);

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

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

## ATS metadata

### ATS export

- Capability ID: `Aspire.Hosting/withBuilderChildRelationship`
- Generated method name override: `withChildRelationship`

## WithChildRelationship(IResourceBuilder<T>, IResource)

- Name: `WithChildRelationship(IResourceBuilder<T>, IResource)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

Adds a [ResourceRelationshipAnnotation](/reference/api/csharp/aspire.hosting/resourcerelationshipannotation.md) to the resource annotations to add a parent-child relationship.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `child` ([IResource](/reference/api/csharp/aspire.hosting/iresource.md))
  The child of `builder`.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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.

```csharp
var builder = DistributedApplication.CreateBuilder(args);

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

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

This method is not available in polyglot app hosts. Use the IResourceBuilder overload instead.

## ATS metadata

### Ignored by ATS

- Reason: Raw IResource interface -- not ATS-compatible.

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

- Name: `WithCommand(IResourceBuilder<T>, string, string, Func<ExecuteCommandContext, Task<ExecuteCommandResult>>, CommandOptions?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L2565-L2579)

Adds a [ResourceCommandAnnotation](/reference/api/csharp/aspire.hosting/resourcecommandannotation.md) to the resource annotations to add a resource command.

```csharp
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)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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 Aspire host. The callback result is used to indicate success or failure in the UI.
- `commandOptions` ([CommandOptions?](/reference/api/csharp/aspire.hosting/commandoptions.md)) `optional`
  Optional configuration for the command.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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 Aspire host.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

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

- Name: `WithCommand(IResourceBuilder<T>, string, string, Func<ExecuteCommandContext, Task<ExecuteCommandResult>>, Func<UpdateCommandStateContext, ResourceCommandState>, string?, object?, string?, string?, IconVariant?, bool)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L2632-L2644)

Adds a [ResourceCommandAnnotation](/reference/api/csharp/aspire.hosting/resourcecommandannotation.md) to the resource annotations to add a resource command.

```csharp
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)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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 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](https://aka.ms/fluentui-system-icons)
- `iconVariant` ([IconVariant?](/reference/api/csharp/aspire.hosting/iconvariant.md)) `optional`
  The icon variant.
- `isHighlighted` (`bool`) `optional`
  A flag indicating whether the command is highlighted in the UI.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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 Aspire host.

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

- Name: `WithComputeEnvironment(IResourceBuilder<T>, IResourceBuilder<IComputeEnvironmentResource>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3800-L3804)

Configures the compute environment for the compute resource.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The compute resource builder.
- `computeEnvironmentResource` (`IResourceBuilder<IComputeEnvironmentResource>`)
  The compute environment resource to associate with the compute resource.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Remarks

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

This method is not available in polyglot app hosts.

## ATS metadata

### Ignored by ATS

- Reason: IComputeEnvironmentResource is a specialized interface -- not ATS-compatible.

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

- Name: `WithConnectionProperty(IResourceBuilder<T>, string, ReferenceExpression)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

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.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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](/reference/api/csharp/aspire.hosting/referenceexpression.md))
  The value of the connection property, specified as a reference expression.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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.

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the internal withConnectionProperty dispatcher export.

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

- Name: `WithConnectionProperty(IResourceBuilder<T>, string, string)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

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.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The same resource builder instance with the specified connection property annotation applied.

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the internal withConnectionProperty dispatcher export.

## WithConnectionStringRedirection(IResourceBuilder<T>, IResourceWithConnectionString)

- Name: `WithConnectionStringRedirection(IResourceBuilder<T>, IResourceWithConnectionString)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L598-L602)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `resource` ([IResourceWithConnectionString](/reference/api/csharp/aspire.hosting/iresourcewithconnectionstring.md))
  Resource to which connection string generation is redirected.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

This method is not available in polyglot app hosts.

## ATS metadata

### Ignored by ATS

- Reason: Raw IResourceWithConnectionString interface parameter -- not ATS-compatible. ReferenceExpression overload is exported.

## WithContainerFilesSource(IResourceBuilder<T>, string)

- Name: `WithContainerFilesSource(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L1952-L1958)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The resource builder instance with the container files source annotation applied.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

> **Experimental:** ASPIREEXTENSION001 - [Learn more](/diagnostics/aspireextension001/)

- Name: `WithDebugSupport(IResourceBuilder<T>, Func<string, TLaunchConfiguration>, string, Action<CommandLineArgsCallbackContext>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3819-L3838)

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

```csharp
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)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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.

## ATS metadata

### Ignored by ATS

- Reason: Generic debug launch configuration support is not part of the ATS surface.

## WithDeveloperCertificateTrust(IResourceBuilder<TResource>, bool)

- Name: `WithDeveloperCertificateTrust(IResourceBuilder<TResource>, bool)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<TResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3101-L3114)

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.

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

## 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.

```csharp
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.

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

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithEndpoint(IResourceBuilder<T>, string, Action<EndpointAnnotation>, bool)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L1266-L1294)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

The [ResourceBuilderExtensions.WithEndpoint(IResourceBuilder<T>, string, Action<EndpointAnnotation>, bool)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withendpoint-iresourcebuilder-t-string-action-endpointannotation-bool) 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](/reference/api/csharp/aspire.hosting/endpointannotation/properties.md#protocol) property of the endpoint annotation in the callback will not automatically change the [EndpointAnnotation.UriScheme](/reference/api/csharp/aspire.hosting/endpointannotation/properties.md#urischeme). All values should be set in the callback if the defaults are not acceptable.

Configure an endpoint to use UDP.

```csharp
var builder = DistributedApplication.Create(args);
var container = builder.AddContainer("mycontainer", "myimage")
                       .WithEndpoint("myendpoint", e => {
                         e.Port = 9998;
                         e.TargetPort = 9999;
                         e.Protocol = ProtocolType.Udp;
                         e.UriScheme = "udp";
                       });
```

This method is not available in polyglot app hosts. Use the callback-based endpoint mutation export instead.

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the internal withEndpointCallback export, which exposes EndpointUpdateContext instead of EndpointAnnotation.

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

- Name: `WithEndpoint(IResourceBuilder<T>, int?, int?, string?, string?, string?, bool, bool?, ProtocolType?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L1356-L1410)

Exposes an endpoint on a resource. A reference to this endpoint can be retrieved using [ResourceBuilderExtensions.GetEndpoint(IResourceBuilder<T>, string, NetworkIdentifier)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#getendpoint-iresourcebuilder-t-string-networkidentifier). The endpoint name will be the scheme name if not specified.

```csharp
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)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- [DistributedApplicationException](/reference/api/csharp/aspire.hosting/distributedapplicationexception.md) -- Throws an exception if an endpoint with the same name already exists on the specified resource.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithEndpoint(IResourceBuilder<T>, int?, int?, string?, string?, string?, bool, bool?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L1467)

Exposes an endpoint on a resource. This endpoint reference can be retrieved using [ResourceBuilderExtensions.GetEndpoint(IResourceBuilder<T>, string, NetworkIdentifier)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#getendpoint-iresourcebuilder-t-string-networkidentifier). The endpoint name will be the scheme name if not specified.

```csharp
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)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- [DistributedApplicationException](/reference/api/csharp/aspire.hosting/distributedapplicationexception.md) -- Throws an exception if an endpoint with the same name already exists on the specified resource.

## Remarks

This method is not available in polyglot app hosts. Use the overload with ProtocolType parameter instead.

If an endpoint with the same name already exists, the existing endpoint is updated with any non-null parameter values.

## ATS metadata

### Ignored by ATS

- Reason: Subset of the full WithEndpoint overload which is already exported.

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

- Name: `WithEnvironment(IResourceBuilder<T>, string, string?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

Adds an environment variable to the resource.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `name` (`string`)
  The name of the environment variable.
- `value` (`string?`)
  The value of the environment variable.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the internal withEnvironment dispatcher export.

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

- Name: `WithEnvironment(IResourceBuilder<T>, string, ExpressionInterpolatedStringHandler)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

Adds an environment variable to the resource.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `name` (`string`)
  The name of the environment variable.
- `value` ([ExpressionInterpolatedStringHandler](/reference/api/csharp/aspire.hosting/expressioninterpolatedstringhandler.md))
  The value of the environment variable.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

This method is not available in polyglot app hosts. Use the ReferenceExpression overload instead.

## ATS metadata

### Ignored by ATS

- Reason: ExpressionInterpolatedStringHandler is a C# compiler-specific type -- not ATS-compatible.

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

- Name: `WithEnvironment(IResourceBuilder<T>, string, ReferenceExpression)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

Adds an environment variable to the resource with a reference expression value.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `name` (`string`)
  The name of the environment variable.
- `value` ([ReferenceExpression](/reference/api/csharp/aspire.hosting/referenceexpression.md))
  A ReferenceExpression that will be evaluated at runtime.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

This overload enables polyglot hosts to set environment variables using dynamic expressions that reference endpoints, parameters, and other value providers.

Usage from TypeScript:

```csharp
const redis = await builder.addRedis("cache");
const endpoint = await redis.getEndpoint("tcp");
const expr = refExpr`redis://${endpoint}:6379`;
await api.withEnvironment("REDIS_URL", expr);
```

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the internal withEnvironment dispatcher export.

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

- Name: `WithEnvironment(IResourceBuilder<T>, string, Func<string>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L156-L160)

Adds an environment variable to the resource.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

This method is not available in polyglot app hosts.

## ATS metadata

### Ignored by ATS

- Reason: Raw Func<string> delegate -- not ATS-compatible.

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

- Name: `WithEnvironment(IResourceBuilder<T>, Action<EnvironmentCallbackContext>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

Allows for the population of environment variables on a resource.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the async callback overload.

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

- Name: `WithEnvironment(IResourceBuilder<T>, Func<EnvironmentCallbackContext, Task>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

Allows for the population of environment variables on a resource.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### ATS export

- Capability ID: `Aspire.Hosting/withEnvironmentCallback`

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

- Name: `WithEnvironment(IResourceBuilder<T>, string, EndpointReference)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L207-L216)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `name` (`string`)
  The name of the environment variable.
- `endpointReference` ([EndpointReference](/reference/api/csharp/aspire.hosting/endpointreference.md))
  The endpoint from which to extract the url.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the internal withEnvironment dispatcher export.

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

- Name: `WithEnvironment(IResourceBuilder<T>, string, IResourceBuilder<ExternalServiceResource>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L232-L259)

Adds an environment variable to the resource with the URL from the [ExternalServiceResource](/reference/api/csharp/aspire.hosting/externalserviceresource.md).

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `name` (`string`)
  The name of the environment variable.
- `externalService` (`IResourceBuilder<ExternalServiceResource>`)
  The external service.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

This method is not available in polyglot app hosts. Use [ResourceBuilderExtensions.WithReference(IResourceBuilder<TDestination>, IResourceBuilder<IResourceWithConnectionString>, string?, bool)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withreference-iresourcebuilder-tdestination-iresourcebuilder-iresourcewithconnectionstring-string-bool) instead.

## ATS metadata

### Ignored by ATS

- Reason: Specialized overload -- withReference covers this use case.

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

- Name: `WithEnvironment(IResourceBuilder<T>, string, IResourceBuilder<ParameterResource>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L273-L282)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `name` (`string`)
  Name of environment variable.
- `parameter` (`IResourceBuilder<ParameterResource>`)
  Resource builder for the parameter resource.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the internal withEnvironment dispatcher export.

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

- Name: `WithEnvironment(IResourceBuilder<T>, string, IResourceBuilder<IResourceWithConnectionString>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L300-L309)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the internal withEnvironment dispatcher export.

## WithEnvironment(IResourceBuilder<T>, string, IExpressionValue)

- Name: `WithEnvironment(IResourceBuilder<T>, string, IExpressionValue)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

Adds an environment variable to the resource with a value that provides both a runtime value and a manifest expression.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `name` (`string`)
  The name of the environment variable.
- `value` ([IExpressionValue](/reference/api/csharp/aspire.hosting/iexpressionvalue.md))
  The value that provides both runtime values and manifest expressions.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

This method is not available in polyglot app hosts. Use the unified `withEnvironment` overload instead.

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the internal withEnvironment dispatcher export.

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

- Name: `WithEnvironment(IResourceBuilder<T>, string, TValue)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

Adds an environment variable to the resource with a value that implements both [IValueProvider](/reference/api/csharp/aspire.hosting/ivalueprovider.md) and [IManifestExpressionProvider](/reference/api/csharp/aspire.hosting/imanifestexpressionprovider.md).

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

This method is not available in polyglot app hosts.

## ATS metadata

### Ignored by ATS

- Reason: Uses open generic TValue which is not ATS-compatible.

## WithExplicitStart(IResourceBuilder<T>)

- Name: `WithExplicitStart(IResourceBuilder<T>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L2273)

Adds a [ExplicitStartupAnnotation](/reference/api/csharp/aspire.hosting/explicitstartupannotation.md) annotation to the resource so it doesn't automatically start with the app host startup.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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.

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

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithExternalHttpEndpoints(IResourceBuilder<T>)

- Name: `WithExternalHttpEndpoints(IResourceBuilder<T>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L1529-L1544)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithHealthCheck(IResourceBuilder<T>, string)

- Name: `WithHealthCheck(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L2362-L2372)

Adds a [HealthCheckAnnotation](/reference/api/csharp/aspire.hosting/healthcheckannotation.md) to the resource annotations to associate a resource with a named health check managed by the health check service.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `key` (`string`)
  The key for the health check.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

The [ResourceBuilderExtensions.WithHealthCheck(IResourceBuilder<T>, string)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withhealthcheck-iresourcebuilder-t-string) method is used in conjunction with the [ResourceBuilderExtensions.WaitFor(IResourceBuilder<T>, IResourceBuilder<IResource>)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#waitfor-iresourcebuilder-t-iresourcebuilder-iresource) to associate a resource registered in the application hosts dependency injection container. The [ResourceBuilderExtensions.WithHealthCheck(IResourceBuilder<T>, string)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withhealthcheck-iresourcebuilder-t-string) 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.

```csharp
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.
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithHttpCommand(IResourceBuilder<TResource>, string, string, string?, string?, HttpCommandOptions?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<TResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L2731-L2738)

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

```csharp
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)
    {
        // ...
    }
}
```

## 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?](/reference/api/csharp/aspire.hosting/httpcommandoptions.md)) `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](/reference/api/csharp/aspire.hosting/httpcommandoptions/properties.md#method) is not specified, `POST` will be used.

Specifying [HttpCommandOptions.HttpClientName](/reference/api/csharp/aspire.hosting/httpcommandoptions/properties.md#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](/reference/api/csharp/aspire.hosting/httpcommandoptions/properties.md#httpclientname) is not specified, the default `Http.HttpClient` will be used.

The [HttpCommandOptions.PrepareRequest](/reference/api/csharp/aspire.hosting/httpcommandoptions/properties.md#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](/reference/api/csharp/aspire.hosting/httpcommandoptions/properties.md#getcommandresult) callback will be invoked after the response is received to determine the result of the command invocation. If this callback is not specified, the command will be considered successful if the response status code is in the 2xx range. Set [HttpCommandOptions.ResultMode](/reference/api/csharp/aspire.hosting/httpcommandoptions/properties.md#resultmode) to flow the HTTP response body back to the command caller.

Adds a command to the project resource that when invoked sends an HTTP POST request to the path `/clear-cache`.

```csharp
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.

```csharp
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;
                        }
                     });
```

This method is not available in polyglot app hosts.

## ATS metadata

### Ignored by ATS

- Reason: Use the ATS-specific withHttpCommand export.

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

- Name: `WithHttpCommand(IResourceBuilder<TResource>, string, string, Func<EndpointReference>, string?, HttpCommandOptions?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<TResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L2808-L2889)

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

```csharp
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)
    {
        // ...
    }
}
```

## 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?](/reference/api/csharp/aspire.hosting/httpcommandoptions.md)) `optional`
  Optional configuration for the command.

## Returns

`IResourceBuilder<TResource>` -- The `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- [DistributedApplicationException](/reference/api/csharp/aspire.hosting/distributedapplicationexception.md)

## Remarks

The command will be added to the resource represented by `builder`.

If no [HttpCommandOptions.EndpointSelector](/reference/api/csharp/aspire.hosting/httpcommandoptions/properties.md#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](/reference/api/csharp/aspire.hosting/httpcommandoptions/properties.md#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](/reference/api/csharp/aspire.hosting/httpcommandoptions/properties.md#method) is not specified, `POST` will be used.

Specifying a [HttpCommandOptions.HttpClientName](/reference/api/csharp/aspire.hosting/httpcommandoptions/properties.md#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](/reference/api/csharp/aspire.hosting/httpcommandoptions/properties.md#httpclientname) is specified, the default `Http.HttpClient` will be used.

The [HttpCommandOptions.PrepareRequest](/reference/api/csharp/aspire.hosting/httpcommandoptions/properties.md#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](/reference/api/csharp/aspire.hosting/httpcommandoptions/properties.md#getcommandresult) callback will be invoked after the response is received to determine the result of the command invocation. If this callback is not specified, the command will be considered successful if the response status code is in the 2xx range. Set [HttpCommandOptions.ResultMode](/reference/api/csharp/aspire.hosting/httpcommandoptions/properties.md#resultmode) to flow the HTTP response body back to the command caller.

Adds commands to a project resource that when invoked sends an HTTP POST request to an endpoint on a separate load generator resource, to generate load against the resource the command was executed against.

```csharp
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);
```

This method is not available in polyglot app hosts.

## ATS metadata

### Ignored by ATS

- Reason: Use the ATS-specific withHttpCommand export.

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

- Name: `WithHttpEndpoint(IResourceBuilder<T>, int?, int?, string?, string?, bool)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L1490-L1492)

Exposes an HTTP endpoint on a resource, or updates the existing HTTP endpoint if one with the same name already exists. This endpoint reference can be retrieved using [ResourceBuilderExtensions.GetEndpoint(IResourceBuilder<T>, string, NetworkIdentifier)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#getendpoint-iresourcebuilder-t-string-networkidentifier). The endpoint name will be "http" if not specified.

```csharp
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)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

If an endpoint with the same name already exists on the resource, the existing endpoint is updated with any non-null parameter values. Parameters left as `null` will not modify the existing endpoint's values.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithHttpHealthCheck(IResourceBuilder<T>, string?, int?, string?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L2407-L2413)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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.

```csharp
var builder = DistributedApplication.CreateBuilder(args);
var backend = builder.AddProject<Projects.Backend>("backend")
                     .WithHttpHealthCheck("/health");
builder.AddProject<Projects.Frontend>("frontend")
       .WithReference(backend).WaitFor(backend);
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithHttpHealthCheck(IResourceBuilder<T>, Func<EndpointReference>, string?, int?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L2449-L2498)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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.

```csharp
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);
```

This method is not available in polyglot app hosts. Use the endpointName-based overload instead.

## ATS metadata

### Ignored by ATS

- Reason: Func<EndpointReference> delegate -- not ATS-compatible.

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

> **Experimental:** ASPIREPROBES001 - [Learn more](/diagnostics/aspireprobes001/)

- Name: `WithHttpProbe(IResourceBuilder<T>, ProbeType, string?, int?, int?, int?, int?, int?, string?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3879-L3885)

Adds a HTTP probe to the resource.

```csharp
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)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  Resource builder.
- `type` ([ProbeType](/reference/api/csharp/aspire.hosting/probetype.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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:

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

Is the same of writing:

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

This method is not available in polyglot app hosts. The parameter name 'type' is a reserved keyword in Go and Rust.

## ATS metadata

### Ignored by ATS

- Reason: Use the ATS export stub with renamed probeType parameter instead.

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

> **Experimental:** ASPIREPROBES001 - [Learn more](/diagnostics/aspireprobes001/)

- Name: `WithHttpProbe(IResourceBuilder<T>, ProbeType, Func<EndpointReference>, string?, int?, int?, int?, int?, int?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3938-L3955)

Adds a HTTP probe to the resource.

```csharp
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)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  Resource builder.
- `type` ([ProbeType](/reference/api/csharp/aspire.hosting/probetype.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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:

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

Is the same of writing:

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

This method is not available in polyglot app hosts. Use the endpointName-based overload instead.

## ATS metadata

### Ignored by ATS

- Reason: Func<EndpointReference> delegate -- not ATS-compatible.

## WithHttpsCertificate(IResourceBuilder<TResource>, X509Certificate2, IResourceBuilder<ParameterResource>)

> **Experimental:** ASPIRECERTIFICATES001 - [Learn more](/diagnostics/aspirecertificates001/)

- Name: `WithHttpsCertificate(IResourceBuilder<TResource>, X509Certificate2, IResourceBuilder<ParameterResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<TResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3262-L3270)

Adds a [HttpsCertificateAnnotation](/reference/api/csharp/aspire.hosting/httpscertificateannotation.md) 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.

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

## 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:

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

This method is not available in polyglot app hosts. Use [ResourceBuilderExtensions.WithHttpsDeveloperCertificate(IResourceBuilder<TResource>, IResourceBuilder<ParameterResource>)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withhttpsdevelopercertificate-iresourcebuilder-tresource-iresourcebuilder-parameterresource) instead.

## ATS metadata

### Ignored by ATS

- Reason: Uses X509Certificate2 which is not ATS-compatible.

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

> **Experimental:** ASPIRECERTIFICATES001 - [Learn more](/diagnostics/aspirecertificates001/)

- Name: `WithHttpsCertificateConfiguration(IResourceBuilder<TResource>, Func<HttpsCertificateConfigurationCallbackAnnotationContext, Task>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<TResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3331-L3336)

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

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

## 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.

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

This method is not available in polyglot app hosts.

## ATS metadata

### Ignored by ATS

- Reason: HttpsCertificateConfigurationCallbackAnnotationContext exposes IServiceProvider and IResource -- not usable from polyglot hosts.

## WithHttpsDeveloperCertificate(IResourceBuilder<TResource>, IResourceBuilder<ParameterResource>)

> **Experimental:** ASPIRECERTIFICATES001 - [Learn more](/diagnostics/aspirecertificates001/)

- Name: `WithHttpsDeveloperCertificate(IResourceBuilder<TResource>, IResourceBuilder<ParameterResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<TResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3226-L3234)

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.

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

## 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:

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

## ATS metadata

### ATS export

- Capability ID: `Aspire.Hosting/withParameterHttpsDeveloperCertificate`
- Generated method name override: `withHttpsDeveloperCertificate`

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

- Name: `WithHttpsEndpoint(IResourceBuilder<T>, int?, int?, string?, string?, bool)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L1515-L1517)

Exposes an HTTPS endpoint on a resource, or updates the existing HTTPS endpoint if one with the same name already exists. This endpoint reference can be retrieved using [ResourceBuilderExtensions.GetEndpoint(IResourceBuilder<T>, string, NetworkIdentifier)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#getendpoint-iresourcebuilder-t-string-networkidentifier). The endpoint name will be "https" if not specified.

```csharp
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)
    {
        // ...
    }
}
```

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

If an endpoint with the same name already exists on the resource, the existing endpoint is updated with any non-null parameter values. Parameters left as `null` will not modify the existing endpoint's values.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

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

- Name: `WithHttpsHealthCheck(IResourceBuilder<T>, string?, int?, string?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L2533-L2535)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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.

```csharp
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)

- Name: `WithIconName(IResourceBuilder<T>, string, IconVariant)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3780-L3783)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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](/reference/api/csharp/aspire.hosting/iconvariant.md)) `optional`
  The variant of the icon (Regular or Filled). Defaults to Filled.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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:

```csharp
var redis = builder.AddContainer("redis", "redis:latest")
    .WithIconName("Database");
```

Set a custom service to use a specific icon with Regular variant:

```csharp
var service = builder.AddProject<Projects.MyService>("service")
    .WithIconName("CloudArrowUp", IconVariant.Regular);
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

> **Experimental:** ASPIREPIPELINES003 - [Learn more](/diagnostics/aspirepipelines003/)

- Name: `WithImagePushOptions(IResourceBuilder<T>, Action<ContainerImagePushOptionsCallbackContext>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `callback` (`Action<ContainerImagePushOptionsCallbackContext>`)
  The callback to configure push options.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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](/reference/api/csharp/aspire.hosting/containerimagepushoptionscallbackcontext.md) that provides access to the resource and the [ContainerImagePushOptions](/reference/api/csharp/aspire.hosting/containerimagepushoptions.md) 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:

```csharp
var container = builder.AddContainer("myapp", "myapp:latest")
    .WithImagePushOptions(context =>
    {
        context.Options.RemoteImageName = "myorg/myapp";
        context.Options.RemoteImageTag = "v1.0.0";
    });
```

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the async callback overload.

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

> **Experimental:** ASPIREPIPELINES003 - [Learn more](/diagnostics/aspirepipelines003/)

- Name: `WithImagePushOptions(IResourceBuilder<T>, Func<ContainerImagePushOptionsCallbackContext, Task>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `callback` (`Func<ContainerImagePushOptionsCallbackContext, Task>`)
  The asynchronous callback to configure push options.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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](/reference/api/csharp/aspire.hosting/containerimagepushoptionscallbackcontext.md) that provides access to the resource and the [ContainerImagePushOptions](/reference/api/csharp/aspire.hosting/containerimagepushoptions.md) 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:

```csharp
var container = builder.AddContainer("myapp", "myapp:latest")
    .WithImagePushOptions(async context =>
    {
        var config = await GetConfigurationAsync();
        context.Options.RemoteImageName = config.ImageName;
        context.Options.RemoteImageTag = config.ImageTag;
    });
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithManifestPublishingCallback(IResourceBuilder<T>, Action<ManifestPublishingContext>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `callback` (`Action<ManifestPublishingContext>`)
  Callback method which takes a [ManifestPublishingContext](/reference/api/csharp/aspire.hosting/manifestpublishingcontext.md) which can be used to inject JSON into the manifest.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

This method is not available in polyglot app hosts.

## ATS metadata

### Ignored by ATS

- Reason: ManifestPublishingContext exposes Utf8JsonWriter and DistributedApplicationExecutionContext -- .NET runtime types not usable from polyglot hosts.

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

- Name: `WithManifestPublishingCallback(IResourceBuilder<T>, Func<ManifestPublishingContext, Task>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `callback` (`Func<ManifestPublishingContext, Task>`)
  Callback method which takes a [ManifestPublishingContext](/reference/api/csharp/aspire.hosting/manifestpublishingcontext.md) which can be used to inject JSON into the manifest.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

This method is not available in polyglot app hosts.

## ATS metadata

### Ignored by ATS

- Reason: ManifestPublishingContext exposes Utf8JsonWriter and DistributedApplicationExecutionContext -- .NET runtime types not usable from polyglot hosts.

## WithoutHttpsCertificate(IResourceBuilder<TResource>)

> **Experimental:** ASPIRECERTIFICATES001 - [Learn more](/diagnostics/aspirecertificates001/)

- Name: `WithoutHttpsCertificate(IResourceBuilder<TResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<TResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3293-L3301)

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

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

## Parameters

- `builder` (`IResourceBuilder<TResource>`)
  The resource builder.

## Returns

`IResourceBuilder<TResource>` -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

Disable HTTPS certificate configuration for a Redis resource:

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

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithParentRelationship(IResourceBuilder<T>, IResourceBuilder<IResource>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

Adds a [ResourceRelationshipAnnotation](/reference/api/csharp/aspire.hosting/resourcerelationshipannotation.md) to the resource annotations to add a parent-child relationship.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `parent` (`IResourceBuilder<IResource>`)
  The parent of `builder`.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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.

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

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

## ATS metadata

### ATS export

- Capability ID: `Aspire.Hosting/withBuilderParentRelationship`
- Generated method name override: `withParentRelationship`

## WithParentRelationship(IResourceBuilder<T>, IResource)

- Name: `WithParentRelationship(IResourceBuilder<T>, IResource)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

Adds a [ResourceRelationshipAnnotation](/reference/api/csharp/aspire.hosting/resourcerelationshipannotation.md) to the resource annotations to add a parent-child relationship.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `parent` ([IResource](/reference/api/csharp/aspire.hosting/iresource.md))
  The parent of `builder`.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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.

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

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

This method is not available in polyglot app hosts. Use the IResourceBuilder overload instead.

## ATS metadata

### Ignored by ATS

- Reason: Raw IResource interface -- not ATS-compatible.

## WithReference(IResourceBuilder<TDestination>, IResourceBuilder<IResourceWithConnectionString>, string?, bool)

- Name: `WithReference(IResourceBuilder<TDestination>, IResourceBuilder<IResourceWithConnectionString>, string?, bool)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<TDestination>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L907-L945)

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(CancellationToken)](/reference/api/csharp/aspire.hosting/iresourcewithconnectionstring/methods.md#getconnectionstringasync-cancellationtoken).

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.

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

## 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](/reference/api/csharp/aspire.hosting/distributedapplicationexception.md) -- 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.

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the internal withReference dispatcher export.

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

- Name: `WithReference(IResourceBuilder<TDestination>, IResourceBuilder<IResourceWithServiceDiscovery>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<TDestination>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L1004-L1008)

Injects service discovery and endpoint information as environment variables from the source resource into the destination resource, using the source resource's name as the service name. Each non-excluded endpoint (where [EndpointAnnotation.ExcludeReferenceEndpoint](/reference/api/csharp/aspire.hosting/endpointannotation/properties.md#excludereferenceendpoint) is `false`) defined on the source resource will be injected using the format defined by the [ReferenceEnvironmentInjectionAnnotation](/reference/api/csharp/aspire.hosting/referenceenvironmentinjectionannotation.md) on the destination resource, i.e. either "services__{sourceResourceName}__{endpointScheme}__{endpointIndex}={uriString}" for .NET service discovery, or "{RESOURCE_ENDPOINT}={uri}" for endpoint injection.

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

## 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`.

## Remarks

All endpoints are included in the default reference set unless explicitly excluded. Resource authors can opt out individual endpoints by setting [EndpointAnnotation.ExcludeReferenceEndpoint](/reference/api/csharp/aspire.hosting/endpointannotation/properties.md#excludereferenceendpoint) to `true` (for example, using `.WithEndpoint("endpointName", e => e.ExcludeReferenceEndpoint = true)`) to exclude them from this method's behavior. Endpoints that have been excluded (such as management or health check endpoints) can still be referenced explicitly using [ResourceBuilderExtensions.WithReference(IResourceBuilder<TDestination>, IResourceBuilder<IResourceWithConnectionString>, string?, bool)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withreference-iresourcebuilder-tdestination-iresourcebuilder-iresourcewithconnectionstring-string-bool) with [ResourceBuilderExtensions.GetEndpoint(IResourceBuilder<T>, string, NetworkIdentifier)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#getendpoint-iresourcebuilder-t-string-networkidentifier).

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the generic withReference export.

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

- Name: `WithReference(IResourceBuilder<TDestination>, IResourceBuilder<IResourceWithServiceDiscovery>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<TDestination>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L1036-L1040)

Injects service discovery and endpoint information as environment variables from the source resource into the destination resource, using the source resource's name as the service name. Each non-excluded endpoint (where [EndpointAnnotation.ExcludeReferenceEndpoint](/reference/api/csharp/aspire.hosting/endpointannotation/properties.md#excludereferenceendpoint) is `false`) defined on the source resource will be injected using the format defined by the [ReferenceEnvironmentInjectionAnnotation](/reference/api/csharp/aspire.hosting/referenceenvironmentinjectionannotation.md) on the destination resource, i.e. either "services__{name}__{endpointScheme}__{endpointIndex}={uriString}" for .NET service discovery, or "{name}_{ENDPOINT}={uri}" for endpoint injection.

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

## 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`.

## Remarks

All endpoints are included in the default reference set unless explicitly excluded. Resource authors can opt out individual endpoints by setting [EndpointAnnotation.ExcludeReferenceEndpoint](/reference/api/csharp/aspire.hosting/endpointannotation/properties.md#excludereferenceendpoint) to `true` (for example, using `.WithEndpoint("endpointName", e => e.ExcludeReferenceEndpoint = true)`) to exclude them from this method's behavior. Endpoints that have been excluded (such as management or health check endpoints) can still be referenced explicitly using [ResourceBuilderExtensions.WithReference(IResourceBuilder<TDestination>, IResourceBuilder<IResourceWithConnectionString>, string?, bool)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withreference-iresourcebuilder-tdestination-iresourcebuilder-iresourcewithconnectionstring-string-bool) with [ResourceBuilderExtensions.GetEndpoint(IResourceBuilder<T>, string, NetworkIdentifier)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#getendpoint-iresourcebuilder-t-string-networkidentifier).

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the generic withReference export.

## WithReference(IResourceBuilder<TDestination>, string, Uri)

- Name: `WithReference(IResourceBuilder<TDestination>, string, Uri)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<TDestination>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L1057-L1095)

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](/reference/api/csharp/aspire.hosting/referenceenvironmentinjectionannotation.md) on the destination resource, i.e. either "services__{name}__default__0={uri}" for .NET service discovery, or "{name}={uri}" for endpoint injection.

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

## 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`.

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the generic withReference dispatcher export.

## WithReference(IResourceBuilder<TDestination>, IResourceBuilder<ExternalServiceResource>)

- Name: `WithReference(IResourceBuilder<TDestination>, IResourceBuilder<ExternalServiceResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<TDestination>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L1110-L1170)

Injects service discovery information as environment variables from the [ExternalServiceResource](/reference/api/csharp/aspire.hosting/externalserviceresource.md) into the destination resource, using the name as the service name. The uri will be injected using the format "services__{name}__default__0={uri}."

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

## 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`.

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts can use the generic withReference dispatcher with an ExternalServiceResource builder.

## WithReference(IResourceBuilder<TDestination>, EndpointReference)

- Name: `WithReference(IResourceBuilder<TDestination>, EndpointReference)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<TDestination>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L1186-L1190)

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](/reference/api/csharp/aspire.hosting/referenceenvironmentinjectionannotation.md) on the destination resource, i.e. either "services__{name}__{endpointScheme}__{endpointIndex}={uriString}" for .NET service discovery, or "{NAME}_{ENDPOINT}={uri}" for endpoint injection.

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

## Parameters

- `builder` (`IResourceBuilder<TDestination>`)
  The resource where the service discovery information will be injected.
- `endpointReference` ([EndpointReference](/reference/api/csharp/aspire.hosting/endpointreference.md))
  The endpoint from which to extract the url.

## Returns

`IResourceBuilder<TDestination>` -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the generic withReference dispatcher export.

## WithReferenceEnvironment(IResourceBuilder<TDestination>, ReferenceEnvironmentInjectionFlags)

- Name: `WithReferenceEnvironment(IResourceBuilder<TDestination>, ReferenceEnvironmentInjectionFlags)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<TDestination>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L684-L686)

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

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

## Parameters

- `builder` (`IResourceBuilder<TDestination>`)
  The resource to configure.
- `flags` ([ReferenceEnvironmentInjectionFlags](/reference/api/csharp/aspire.hosting/referenceenvironmentinjectionflags.md))
  The injection flags determining which reference information is emitted.

## Returns

`IResourceBuilder<TDestination>` -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

This method is not available in polyglot app hosts.

## ATS metadata

### Ignored by ATS

- Reason: Advanced internal configuration -- ReferenceEnvironmentInjectionFlags enum not intentionally part of public ATS surface.

## WithReferenceRelationship(IResourceBuilder<T>, IResource)

- Name: `WithReferenceRelationship(IResourceBuilder<T>, IResource)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3533-L3536)

Adds a [ResourceRelationshipAnnotation](/reference/api/csharp/aspire.hosting/resourcerelationshipannotation.md) to the resource annotations to add a reference to another resource.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `resource` ([IResource](/reference/api/csharp/aspire.hosting/iresource.md))
  The resource that the relationship is to.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- A resource builder.

## Remarks

This method is not available in polyglot app hosts.

## ATS metadata

### Ignored by ATS

- Reason: Raw IResource interface -- not ATS-compatible.

## WithReferenceRelationship(IResourceBuilder<T>, ReferenceExpression)

- Name: `WithReferenceRelationship(IResourceBuilder<T>, ReferenceExpression)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3552-L3557)

Walks the reference expression and adds [ResourceRelationshipAnnotation](/reference/api/csharp/aspire.hosting/resourcerelationshipannotation.md) s for all resources found in the expression.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `expression` ([ReferenceExpression](/reference/api/csharp/aspire.hosting/referenceexpression.md))
  The reference expression.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- A resource builder.

## Remarks

This method is not available in polyglot app hosts.

## ATS metadata

### Ignored by ATS

- Reason: Low-level relationship tracking -- raw IResource interface, not intended for polyglot use.

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

- Name: `WithReferenceRelationship(IResourceBuilder<T>, IResourceBuilder<IResource>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3613-L3616)

Adds a [ResourceRelationshipAnnotation](/reference/api/csharp/aspire.hosting/resourcerelationshipannotation.md) to the resource annotations to add a reference to another resource.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `resourceBuilder` (`IResourceBuilder<IResource>`)
  The resource builder that the relationship is to.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- A resource builder.

## Remarks

This method is not available in polyglot app hosts.

## ATS metadata

### Ignored by ATS

- Reason: Low-level relationship tracking -- raw IResource interface, not intended for polyglot use.

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

- Name: `WithRelationship(IResourceBuilder<T>, IResource, string)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3493-L3497)

Adds a [ResourceRelationshipAnnotation](/reference/api/csharp/aspire.hosting/resourcerelationshipannotation.md) to the resource annotations to add a relationship.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `resource` ([IResource](/reference/api/csharp/aspire.hosting/iresource.md))
  The resource that the relationship is to.
- `type` (`string`)
  The relationship type.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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.

```csharp
var builder = DistributedApplication.CreateBuilder(args);
var backend = builder.AddProject<Projects.Backend>("backend");
var manager = builder.AddProject<Projects.Manager>("manager")
                     .WithRelationship(backend.Resource, "Manager");
```

This method is not available in polyglot app hosts.

## ATS metadata

### Ignored by ATS

- Reason: Raw IResource interface -- not ATS-compatible.

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

- Name: `WithRelationship(IResourceBuilder<T>, IResourceBuilder<IResource>, string)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3514-L3517)

Adds a relationship to another resource using its builder.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `resourceBuilder` (`IResourceBuilder<IResource>`)
  The resource builder that the relationship is to.
- `type` (`string`)
  The relationship type.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- A resource builder.

## ATS metadata

### ATS export

- Capability ID: `Aspire.Hosting/withBuilderRelationship`
- Generated method name override: `withRelationship`

## WithRemoteImageName(IResourceBuilder<T>, string)

> **Experimental:** ASPIREPIPELINES003 - [Learn more](/diagnostics/aspirepipelines003/)

- Name: `WithRemoteImageName(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L4096-L4102)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `remoteImageName` (`string`)
  The remote image name (e.g., "myapp" or "myorg/myapp").

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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](/reference/api/csharp/aspire.hosting/containerimagepushoptions/properties.md#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(IResourceBuilder<T>, string)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withremoteimagetag-iresourcebuilder-t-string) to fully customize the image reference.

## Examples

Set a custom remote image name for a container:

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

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithRemoteImageTag(IResourceBuilder<T>, string)

> **Experimental:** ASPIREPIPELINES003 - [Learn more](/diagnostics/aspirepipelines003/)

- Name: `WithRemoteImageTag(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L4132-L4138)

Sets the remote image tag for container push operations.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The resource builder.
- `remoteImageTag` (`string`)
  The remote image tag (e.g., "latest", "v1.0.0").

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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](/reference/api/csharp/aspire.hosting/containerimagepushoptions/properties.md#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(IResourceBuilder<T>, string)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withremoteimagename-iresourcebuilder-t-string) to fully customize the image reference.

## Examples

Set a specific version tag for a container:

```csharp
var container = builder.AddContainer("myapp", "myapp:latest")
    .WithRemoteImageTag("v1.0.0");
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithUrl(IResourceBuilder<T>, string, string?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

Adds a URL to be displayed for the resource.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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(IResourceBuilder<T>, string, Action<ResourceUrlAnnotation>)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withurlforendpoint-iresourcebuilder-t-string-action-resourceurlannotation).

## Examples

### Example 1

Add a static URL to be displayed for the resource:

```csharp
var frontend = builder.AddProject<Projects.Frontend>("frontend")
                      .WithUrl("https://example.com/", "Home");
```

### Example 2

Update all displayed URLs to use the specified path and (optional) display text:

```csharp
var frontend = builder.AddProject<Projects.Frontend>("frontend")
                      .WithUrl("/home", "Home");
```

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the internal withUrl dispatcher export.

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

- Name: `WithUrl(IResourceBuilder<T>, ExpressionInterpolatedStringHandler, string?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

Adds a URL to be displayed for the resource.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The builder for the resource.
- `url` ([ExpressionInterpolatedStringHandler](/reference/api/csharp/aspire.hosting/expressioninterpolatedstringhandler.md))
  The interpolated string that produces the URL.
- `displayText` (`string?`) `optional`
  The display text to show when the link is displayed.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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.

This method is not available in polyglot app hosts. Use the ReferenceExpression overload instead.

## ATS metadata

### Ignored by ATS

- Reason: ExpressionInterpolatedStringHandler is a C# compiler-specific type -- not ATS-compatible.

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

- Name: `WithUrl(IResourceBuilder<T>, ReferenceExpression, string?)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

Adds a URL to be displayed for the resource.

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The builder for the resource.
- `url` ([ReferenceExpression](/reference/api/csharp/aspire.hosting/referenceexpression.md))
  A [ReferenceExpression](/reference/api/csharp/aspire.hosting/referenceexpression.md) that will produce the URL.
- `displayText` (`string?`) `optional`
  The display text to show when the link is displayed.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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.

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the internal withUrl dispatcher export.

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

- Name: `WithUrlForEndpoint(IResourceBuilder<T>, string, Action<ResourceUrlAnnotation>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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(IResourceBuilder<T>, string, Action<ResourceUrlAnnotation>)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withurlforendpoint-iresourcebuilder-t-string-action-resourceurlannotation).

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":

```csharp
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:

```csharp
var frontend = builder.AddProject<Projects.Frontend>("frontend")
                      .WithUrlForEndpoint("https", url => url.Url = "/home");
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithUrlForEndpoint(IResourceBuilder<T>, string, Func<EndpointReference, ResourceUrlAnnotation>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  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>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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(IResourceBuilder<T>, string, Action<ResourceUrlAnnotation>)](/reference/api/csharp/aspire.hosting/resourcebuilderextensions/methods.md#withurlforendpoint-iresourcebuilder-t-string-action-resourceurlannotation).

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":

```csharp
var frontend = builder.AddProject<Projects.Frontend>("frontend")
                      .WithUrlForEndpoint("https", ep => new() { Url = "/admin", DisplayText = "Admin" });
```

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the Action<ResourceUrlAnnotation> overload for withUrlForEndpoint.

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

- Name: `WithUrls(IResourceBuilder<T>, Action<ResourceUrlsCallbackContext>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The builder for the resource.
- `callback` (`Action<ResourceUrlsCallbackContext>`)
  The callback that will customize URLs for the resource.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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:

```csharp
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:

```csharp
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();
                              }
                          }
                      });
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithUrls(IResourceBuilder<T>, Func<ResourceUrlsCallbackContext, Task>)`
- Modifiers: `extension`
- Returns: [IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/bd20f904cde09ecb9c9ae5116a6f13614bf2d7c2/src/Aspire.Hosting/ResourceBuilderExtensions.cs)

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

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

## Parameters

- `builder` ([IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md))
  The builder for the resource.
- `callback` (`Func<ResourceUrlsCallbackContext, Task>`)
  The async callback that will customize URLs for the resource.

## Returns

[IResourceBuilder<T>](/reference/api/csharp/aspire.hosting/iresourcebuilder-1.md) -- 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.

## ATS metadata

### Ignored by ATS

- Reason: Polyglot app hosts use the synchronous Action<> overload via withUrlsCallback.