Skip to content

[TypeScript AppHost] Expose WithContainerBuildOptions / ContainerTargetPlatform for cross-architecture container builds #17939

Closed

Description

Summary

The C# AppHost exposes WithContainerBuildOptions(o => o.TargetPlatform = ContainerTargetPlatform.LinuxArm64) (and the ContainerTargetPlatform enum) to control per-resource container build settings — most importantly the --platform flag for cross-compilation. These APIs are not exposed in the TypeScript AppHost bindings as of 13.4.

Verified with the Aspire CLI docs (13.4.0):

  • aspire docs api search "withContainerBuildOptions" --language typescript → no results.
  • aspire docs api search "containerTargetPlatform" --language typescript → no results.
  • aspire docs api search "targetPlatform" --language typescript → no results (only unrelated MAUI types).
  • Both WithContainerBuildOptions and ContainerTargetPlatform are returned under --language csharp.
  • The full ContainerResource TS member list (per aspire docs api get typescript/aspire.hosting/containerresource) contains: withBindMount, withBuildArg, withBuildSecret, withContainerCertificatePaths, withContainerName, withContainerNetworkAlias, withContainerRuntimeArgs, withDockerfile, withDockerfileBuilder, withDockerfileFactory, withEntrypoint, withImage, withImagePullPolicy, withImageRegistry, withImageSHA256, withImageTag, withLifetime, withVolume — no withContainerBuildOptions.
  • The TS withDockerfile(contextPath, dockerfilePath?, stage?) signature has no platform / build-options parameter either.

Repro / scenario

I have a TypeScript AppHost (apphost.mts) that builds container images via addContainer(...).withDockerfile(...) and publishes a Docker Compose deployment. The target host is a Raspberry Pi (linux/arm64) and the build host is linux/amd64, so I need to cross-compile.

In C# the casaloom AppHost does this cleanly with:

api.WithContainerBuildOptions(o => o.TargetPlatform = ContainerTargetPlatform.LinuxArm64);
web.WithContainerBuildOptions(o => o.TargetPlatform = ContainerTargetPlatform.LinuxArm64);
admin.WithContainerBuildOptions(o => o.TargetPlatform = ContainerTargetPlatform.LinuxArm64);

In TS there is no equivalent. My current workaround is to set DOCKER_DEFAULT_PLATFORM=linux/arm64 globally when invoking aspire deploy, which buildx honors for every image in the build. That works for my single-target case but:

  • It's all-or-nothing — can't have one resource build for amd64 and another for arm64 in the same publish.
  • It's invisible in the AppHost, so devs reading the code don't see the platform decision.
  • It doesn't compose well with mixed-architecture deployments (e.g. multi-arch manifests).

Ask

Port WithContainerBuildOptions and the ContainerTargetPlatform enum to the TypeScript AppHost API surface (Aspire.Hosting TS bindings, ContainerResource.withContainerBuildOptions(...)), with the same shape as the C# version. A minimal first cut would be just the targetPlatform setting; the full ContainerBuildOptionsCallbackContext surface can follow.

Suggested TS signature:

interface ContainerResource {
  withContainerBuildOptions(
    configure: (ctx: ContainerBuildOptionsCallbackContext) => void | Promise<void>
  ): ContainerResource;
}

enum ContainerTargetPlatform {
  LinuxAmd64 = "linux/amd64",
  LinuxArm64 = "linux/arm64",
  LinuxArm   = "linux/arm",
}

Environment

  • Aspire CLI / SDK: 13.4.0 (13.4.2 stable channel)
  • AppHost language: TypeScript (apphost.mts)
  • Publisher: Docker Compose (addDockerComposeEnvironment)

Thanks!

Activity

  1. added
    needs-area-labelAn area label is needed to ensure this gets routed to the appropriate area owners
    on Jun 5, 2026
  2. joperezr commented on Jun 5, 2026

    @joperezr
    MemberAuthor
    🤖 Aspire triage pass — 2026-06-05 04:58 UTC

    Area: area-polyglot
    Kind: feature-request
    Repro: yes-minimal — see the aspire docs api search verifications and proposed TS signature in the issue body (no runtime crash; this is a missing API surface)
    Affected version(s): 13.4.0 / 13.4.2 (latest: 13.4.0). Not a regression — the TS bindings never exposed WithContainerBuildOptions.
    Severity: S3 — workaround exists (DOCKER_DEFAULT_PLATFORM=linux/arm64 at aspire deploy time), but it's all-or-nothing and not visible in the AppHost.

    Urgency: ⚪ backlog — no milestone
    Reason: feature-request for TS AppHost API parity with C#. S3, workaround exists, not a 13.4 regression — does not clear the 13.4.x servicing bar. Reasonable 13.5 candidate if the polyglot team wants to prioritize parity, but defaulting to backlog per the conservative bar.

    Suggested owner(s): Sébastien Ros (@sebastienros) (score 50), backup David Pine (@IEvangelist) (score 19)
    Evidence:

    Confidence: high
    Needs human?: no

    Dry-run mode — no labels or milestone applied. Reply /triage apply to promote, or edit and reapply.

  3. added
    area-polyglotIssues related to polyglot apphosts
    and removed
    needs-area-labelAn area label is needed to ensure this gets routed to the appropriate area owners
    on Jun 5, 2026
  4. added this to the 13.5 milestone on Jun 5, 2026
  5. sebastienros commented on Jun 17, 2026

    @sebastienros
    Contributor

    This is now available in main — the TypeScript AppHost bindings expose both withContainerBuildOptions(...) and the ContainerTargetPlatform enum. The work landed after this issue was filed against 13.4.

    Introducing PR

    TypeScript surface (generated)

    const api = await builder.addDockerfile("api", "./app");
    await api.withContainerBuildOptions(async (ctx) => {
        await ctx.targetPlatform.set(ContainerTargetPlatform.LinuxArm64);
    });
    
    enum ContainerTargetPlatform {
        LinuxAmd64, LinuxArm64, LinuxArm, Linux386, WindowsAmd64, WindowsArm64, AllLinux
    }

    This is per-resource (not all-or-nothing like DOCKER_DEFAULT_PLATFORM) and visible in the AppHost, addressing the mixed-architecture concern raised here. The callback context also exposes services, logger, executionContext (run vs. publish), destination, imageFormat, outputPath, localImageName, and localImageTag.

    Note: the generated enum uses C# member-name string values (LinuxArm64) rather than docker-style strings (linux/arm64); that's the standard ATS enum convention across all guest languages.

    Verification performed

    • ✅ TypeScript code-generation tests against the real Aspire.Hosting assembly — 99/99 passing (Aspire.Hosting.CodeGeneration.TypeScript.Tests), with snapshots covering ContainerResource.withContainerBuildOptions, ContainerTargetPlatform, and ContainerBuildOptionsCallbackContext.targetPlatform get/set.
    • ✅ Generated-binding runtime/transport tests — 149/149 passing (vitest JS tests).
    • ✅ Compile-level end-to-end: type-checked an apphost.mts using the exact cross-arch scenario above (addDockerfile(...).withContainerBuildOptions(ctx => ctx.targetPlatform.set(ContainerTargetPlatform.LinuxArm64))) against the real generated SDK — tsc clean; a negative control with an invalid enum member is correctly rejected.
    • The shipped TypeScript polyglot validation app host (tests/PolyglotAppHosts/Aspire.Hosting/TypeScript/apphost.mts) already exercises this API, and it's covered by the Linux CLI end-to-end suite.

    Closing as completed. Please reopen if you hit a gap on a current main/daily build.

  6. locked and limited conversation to collaborators on Jul 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

area-polyglotIssues related to polyglot apphoststriage:bot-seenAspire triage bot has seen this issue

Type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions