Expose Dockerfile builder APIs to polyglot apphosts

src/Aspire.Hosting.CodeGeneration.Java/AtsJavaCodeGenerator.cs

@@ -1663,7 +1663,12 @@ private IReadOnlyList<JavaHandleType> BuildHandleTypes(AtsContext context)
             _classNames[typeId] = CreateClassName(typeId);
         }
 
-        var handleTypeMap = context.HandleTypes.ToDictionary(t => t.AtsTypeId, StringComparer.Ordinal);
+        var handleTypeMap = context.HandleTypes
+            .GroupBy(t => t.AtsTypeId, StringComparer.Ordinal)
+            .ToDictionary(
+                g => g.Key,
+                g => g.OrderByDescending(t => t.IsResourceBuilder).First(),
+                StringComparer.Ordinal);
         var results = new List<JavaHandleType>();
         foreach (var typeId in handleTypeIds)
         {

src/Aspire.Hosting.CodeGeneration.Python/AtsPythonCodeGenerator.cs

@@ -1751,6 +1751,30 @@ private List<BuilderModel> CreateBuilderModels(IReadOnlyList<AtsCapabilityInfo>
     /// </summary>
     private static List<BuilderModel> TopologicalSortBuilders(List<BuilderModel> builders)
     {
+        builders = builders
+            .GroupBy(b => b.TypeId, StringComparer.Ordinal)
+            .Select(g =>
+            {
+                if (g.Count() == 1)
+                {
+                    return g.First();
+                }
+
+                var first = g.First();
+                return new BuilderModel
+                {
+                    TypeId = g.Key,
+                    BuilderClassName = first.BuilderClassName,
+                    Capabilities = g.SelectMany(b => b.Capabilities)
+                        .GroupBy(c => c.CapabilityId, StringComparer.Ordinal)
+                        .Select(cg => cg.First())
+                        .ToList(),
+                    IsInterface = first.IsInterface,
+                    TargetType = g.Select(b => b.TargetType).FirstOrDefault(t => t is not null)
+                };
+            })
+            .ToList();
+
         var buildersByTypeId = builders.ToDictionary(b => b.TypeId, StringComparer.Ordinal);
         var result = new List<BuilderModel>();
         var visited = new HashSet<string>(StringComparer.Ordinal);

src/Aspire.Hosting/ApplicationModel/Docker/ContainerFilesExtensions.cs

@@ -19,6 +19,7 @@ public static class ContainerFilesExtensions
     /// <param name="resource">The resource containing container files to be added to the Dockerfile. Cannot be null.</param>
     /// <param name="logger">An optional logger used to record warnings if container image names cannot be determined for source resources.</param>
     /// <returns>The same DockerfileBuilder instance with additional instructions for container files, enabling method chaining.</returns>
+    [AspireExportIgnore(Reason = "Polyglot-facing wrappers are exported from DockerfileBuilderExports with a curated signature.")]
     [Experimental("ASPIREDOCKERFILEBUILDER001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
     public static DockerfileBuilder AddContainerFilesStages(this DockerfileBuilder builder, IResource resource, ILogger? logger)
     {
@@ -76,6 +77,7 @@ public static DockerfileBuilder AddContainerFilesStages(this DockerfileBuilder b
     /// such as copying static assets from a frontend build container into a backend API container.
     /// </para>
     /// </remarks>
+    [AspireExportIgnore(Reason = "Polyglot-facing wrappers are exported from DockerfileBuilderExports with a curated signature.")]
     [Experimental("ASPIREDOCKERFILEBUILDER001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
     public static DockerfileStage AddContainerFiles(this DockerfileStage stage, IResource resource, string rootDestinationPath, ILogger? logger)
     {

src/Aspire.Hosting/ApplicationModel/Docker/DockerfileBuilder.cs

@@ -8,6 +8,7 @@ namespace Aspire.Hosting.ApplicationModel.Docker;
 /// <summary>
 /// Builder for creating Dockerfiles programmatically.
 /// </summary>
+[AspireExport]
 [Experimental("ASPIREDOCKERFILEBUILDER001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
 public class DockerfileBuilder
 {

src/Aspire.Hosting/ApplicationModel/Docker/DockerfileStage.cs

@@ -8,6 +8,7 @@ namespace Aspire.Hosting.ApplicationModel.Docker;
 /// <summary>
 /// Represents a stage within a multi-stage Dockerfile.
 /// </summary>
+[AspireExport]
 [Experimental("ASPIREDOCKERFILEBUILDER001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
 public class DockerfileStage : DockerfileStatement
 {

src/Aspire.Hosting/ApplicationModel/DockerfileBuilderCallbackContext.cs

@@ -9,6 +9,7 @@ namespace Aspire.Hosting.ApplicationModel;
 /// <summary>
 /// Provides context information for Dockerfile build callbacks.
 /// </summary>
+[AspireExport(ExposeProperties = true)]
 [Experimental("ASPIREDOCKERFILEBUILDER001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
 public class DockerfileBuilderCallbackContext
 {
@@ -46,4 +47,4 @@ public DockerfileBuilderCallbackContext(IResource resource, DockerfileBuilder bu
     /// Gets the cancellation token to observe while waiting for the task to complete.
     /// </summary>
     public CancellationToken CancellationToken { get; }
-}
+}

src/Aspire.Hosting/Ats/DockerfileBuilderExports.cs

@@ -0,0 +1,145 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+#pragma warning disable ASPIREDOCKERFILEBUILDER001 // Type is for evaluation purposes only and is subject to change or removal in future updates.
+
+using Aspire.Hosting.ApplicationModel;
+using Aspire.Hosting.ApplicationModel.Docker;
+using Microsoft.Extensions.Logging;
+
+namespace Aspire.Hosting.Ats;
+
+/// <summary>
+/// ATS exports for the Dockerfile builder DSL.
+/// </summary>
+internal static class DockerfileBuilderExports
+{
+    [AspireExport("dockerfileBuilderArg", MethodName = "arg", Description = "Adds a global ARG statement to the Dockerfile")]
+    public static DockerfileBuilder Arg(this DockerfileBuilder builder, string name, string? defaultValue = null)
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+
+        return defaultValue is null ? builder.Arg(name) : builder.Arg(name, defaultValue);
+    }
+
+    [AspireExport("dockerfileBuilderFrom", MethodName = "from", Description = "Adds a FROM statement to start a Dockerfile stage")]
+    public static DockerfileStage From(this DockerfileBuilder builder, string image, string? stageName = null)
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+
+        return stageName is null ? builder.From(image) : builder.From(image, stageName);
+    }
+
+    [AspireExport("dockerfileStageArg", MethodName = "arg", Description = "Adds an ARG statement to a Dockerfile stage")]
+    public static DockerfileStage Arg(this DockerfileStage stage, string name, string? defaultValue = null)
+    {
+        ArgumentNullException.ThrowIfNull(stage);
+
+        return defaultValue is null ? stage.Arg(name) : stage.Arg(name, defaultValue);
+    }
+
+    [AspireExport(Description = "Adds a WORKDIR statement to a Dockerfile stage")]
+    public static DockerfileStage WorkDir(this DockerfileStage stage, string path)
+    {
+        ArgumentNullException.ThrowIfNull(stage);
+        return stage.WorkDir(path);
+    }
+
+    [AspireExport("dockerfileStageRun", MethodName = "run", Description = "Adds a RUN statement to a Dockerfile stage")]
+    public static DockerfileStage Run(this DockerfileStage stage, string command)
+    {
+        ArgumentNullException.ThrowIfNull(stage);
+        return stage.Run(command);
+    }
+
+    [AspireExport("dockerfileStageCopy", MethodName = "copy", Description = "Adds a COPY statement to a Dockerfile stage")]
+    public static DockerfileStage Copy(this DockerfileStage stage, string source, string destination, string? chown = null)
+    {
+        ArgumentNullException.ThrowIfNull(stage);
+
+        return chown is null ? stage.Copy(source, destination) : stage.Copy(source, destination, chown);
+    }
+
+    [AspireExport("dockerfileStageCopyFrom", MethodName = "copyFrom", Description = "Adds a COPY --from statement to a Dockerfile stage")]
+    public static DockerfileStage CopyFrom(this DockerfileStage stage, string from, string source, string destination, string? chown = null)
+    {
+        ArgumentNullException.ThrowIfNull(stage);
+
+        return chown is null ? stage.CopyFrom(from, source, destination) : stage.CopyFrom(from, source, destination, chown);
+    }
+
+    [AspireExport(Description = "Adds an ENV statement to a Dockerfile stage")]
+    public static DockerfileStage Env(this DockerfileStage stage, string name, string value)
+    {
+        ArgumentNullException.ThrowIfNull(stage);
+        return stage.Env(name, value);
+    }
+
+    [AspireExport(Description = "Adds an EXPOSE statement to a Dockerfile stage")]
+    public static DockerfileStage Expose(this DockerfileStage stage, int port)
+    {
+        ArgumentNullException.ThrowIfNull(stage);
+        return stage.Expose(port);
+    }
+
+    [AspireExport(Description = "Adds a CMD statement to a Dockerfile stage")]
+    public static DockerfileStage Cmd(this DockerfileStage stage, string[] command)
+    {
+        ArgumentNullException.ThrowIfNull(stage);
+        return stage.Cmd(command);
+    }
+
+    [AspireExport(Description = "Adds an ENTRYPOINT statement to a Dockerfile stage")]
+    public static DockerfileStage Entrypoint(this DockerfileStage stage, string[] command)
+    {
+        ArgumentNullException.ThrowIfNull(stage);
+        return stage.Entrypoint(command);
+    }
+
+    [AspireExport(Description = "Adds a RUN statement with mounts to a Dockerfile stage")]
+    public static DockerfileStage RunWithMounts(this DockerfileStage stage, string command, string[] mounts)
+    {
+        ArgumentNullException.ThrowIfNull(stage);
+        return stage.RunWithMounts(command, mounts);
+    }
+
+    [AspireExport(Description = "Adds a USER statement to a Dockerfile stage")]
+    public static DockerfileStage User(this DockerfileStage stage, string user)
+    {
+        ArgumentNullException.ThrowIfNull(stage);
+        return stage.User(user);
+    }
+
+    [AspireExport(Description = "Adds an empty line to a Dockerfile stage")]
+    public static DockerfileStage EmptyLine(this DockerfileStage stage)
+    {
+        ArgumentNullException.ThrowIfNull(stage);
+        return stage.EmptyLine();
+    }
+
+    [AspireExport(Description = "Adds a comment to a Dockerfile stage")]
+    public static DockerfileStage Comment(this DockerfileStage stage, string comment)
+    {
+        ArgumentNullException.ThrowIfNull(stage);
+        return stage.Comment(comment);
+    }
+
+    [AspireExport("dockerfileBuilderAddContainerFilesStages", MethodName = "addContainerFilesStages", Description = "Adds Dockerfile stages for published container files")]
+    public static DockerfileBuilder AddContainerFilesStages(this DockerfileBuilder builder, IResource resource, ILogger? logger = null)
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+        ArgumentNullException.ThrowIfNull(resource);
+
+        return ContainerFilesExtensions.AddContainerFilesStages(builder, resource, logger);
+    }
+
+    [AspireExport("dockerfileStageAddContainerFiles", MethodName = "addContainerFiles", Description = "Adds COPY --from statements for published container files")]
+    public static DockerfileStage AddContainerFiles(this DockerfileStage stage, IResource resource, string rootDestinationPath, ILogger? logger = null)
+    {
+        ArgumentNullException.ThrowIfNull(stage);
+        ArgumentNullException.ThrowIfNull(resource);
+        ArgumentException.ThrowIfNullOrEmpty(rootDestinationPath);
+
+        return ContainerFilesExtensions.AddContainerFiles(stage, resource, rootDestinationPath, logger);
+    }
+}

src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs

@@ -924,8 +924,7 @@ public static IResourceBuilder<ContainerResource> AddDockerfileFactory(this IDis
     /// </code>
     /// </example>
     /// </remarks>
-    /// <remarks>This method is not available in polyglot app hosts. Use <see cref="AddDockerfile"/> instead.</remarks>
-    [AspireExportIgnore(Reason = "DockerfileBuilderCallbackContext is not an ATS-exported callback context.")]
+    [AspireExport(Description = "Adds a container resource built from a programmatically generated Dockerfile")]
     [Experimental("ASPIREDOCKERFILEBUILDER001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
     public static IResourceBuilder<ContainerResource> AddDockerfileBuilder(this IDistributedApplicationBuilder builder, [ResourceName] string name, string contextPath, Func<DockerfileBuilderCallbackContext, Task> callback, string? stage = null)
     {
@@ -972,8 +971,8 @@ public static IResourceBuilder<ContainerResource> AddDockerfileBuilder(this IDis
     /// </code>
     /// </example>
     /// </remarks>
-    /// <remarks>This method is not available in polyglot app hosts. Use <see cref="AddDockerfile"/> instead.</remarks>
-    [AspireExportIgnore(Reason = "DockerfileBuilderCallbackContext is not an ATS-exported callback context.")]
+    /// <remarks>This synchronous overload is not available in polyglot app hosts. Use the overload that accepts a <see cref="Func{T, TResult}"/>.</remarks>
+    [AspireExportIgnore(Reason = "This synchronous overload is excluded from the polyglot surface; only the async callback overload is exported.")]
     [Experimental("ASPIREDOCKERFILEBUILDER001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
     public static IResourceBuilder<ContainerResource> AddDockerfileBuilder(this IDistributedApplicationBuilder builder, [ResourceName] string name, string contextPath, Action<DockerfileBuilderCallbackContext> callback, string? stage = null)
     {
@@ -1430,8 +1429,7 @@ public static IResourceBuilder<T> WithEndpointProxySupport<T>(this IResourceBuil
     /// </code>
     /// </example>
     /// </remarks>
-    /// <remarks>This method is not available in polyglot app hosts. Use <see cref="WithDockerfile{T}"/> instead.</remarks>
-    [AspireExportIgnore(Reason = "DockerfileBuilderCallbackContext is not an ATS-exported callback context.")]
+    [AspireExport(Description = "Configures the resource to use a programmatically generated Dockerfile")]
     [Experimental("ASPIREDOCKERFILEBUILDER001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
     public static IResourceBuilder<T> WithDockerfileBuilder<T>(this IResourceBuilder<T> builder, string contextPath, Func<DockerfileBuilderCallbackContext, Task> callback, string? stage = null) where T : ContainerResource
     {
@@ -1535,8 +1533,8 @@ public static IResourceBuilder<T> WithDockerfileBuilder<T>(this IResourceBuilder
     /// </code>
     /// </example>
     /// </remarks>
-    /// <remarks>This method is not available in polyglot app hosts. Use <see cref="WithDockerfile{T}"/> instead.</remarks>
-    [AspireExportIgnore(Reason = "DockerfileBuilderCallbackContext is not an ATS-exported callback context.")]
+    /// <remarks>This synchronous overload is not available in polyglot app hosts. Use the overload that accepts a <see cref="Func{T, TResult}"/>.</remarks>
+    [AspireExportIgnore(Reason = "This synchronous overload is excluded from the polyglot surface; only the async callback overload is exported.")]
     [Experimental("ASPIREDOCKERFILEBUILDER001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
     public static IResourceBuilder<T> WithDockerfileBuilder<T>(this IResourceBuilder<T> builder, string contextPath, Action<DockerfileBuilderCallbackContext> callback, string? stage = null) where T : ContainerResource
     {