Dotnet Tool Integration

Aspire.slnx

@@ -172,6 +172,9 @@
   <Folder Name="/playground/CustomResources/">
     <Project Path="playground/CustomResources/CustomResources.AppHost/CustomResources.AppHost.csproj" />
   </Folder>
+  <Folder Name="/playground/DotnetTool/">
+    <Project Path="playground/DotnetTool/DotnetTool.AppHost/DotnetTool.AppHost.csproj" />
+  </Folder>
   <Folder Name="/playground/DatabaseMigration/">
     <Project Path="playground/DatabaseMigration/DatabaseMigration.ApiModel/DatabaseMigration.ApiModel.csproj" />
     <Project Path="playground/DatabaseMigration/DatabaseMigration.ApiService/DatabaseMigration.ApiService.csproj" />
@@ -415,6 +418,7 @@
     <Project Path="tests/Aspire.Hosting.Azure.Tests/Aspire.Hosting.Azure.Tests.csproj" />
     <Project Path="tests/Aspire.Hosting.Containers.Tests/Aspire.Hosting.Containers.Tests.csproj" />
     <Project Path="tests/Aspire.Hosting.DevTunnels.Tests/Aspire.Hosting.DevTunnels.Tests.csproj" />
+    <Project Path="tests/Aspire.Hosting.DotnetTool.Tests/Aspire.Hosting.DotnetTool.Tests.csproj" />
     <Project Path="tests/Aspire.Hosting.Docker.Tests/Aspire.Hosting.Docker.Tests.csproj" />
     <Project Path="tests/Aspire.Hosting.Garnet.Tests/Aspire.Hosting.Garnet.Tests.csproj" />
     <Project Path="tests/Aspire.Hosting.GitHub.Models.Tests/Aspire.Hosting.GitHub.Models.Tests.csproj" />

playground/DotnetTool/DotnetTool.AppHost/AppHost.cs

@@ -0,0 +1,122 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+using Microsoft.Extensions.DependencyInjection;
+#pragma warning disable ASPIREDOTNETTOOL // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
+
+var builder = DistributedApplication.CreateBuilder(args);
+
+var simpleUsage = builder.AddDotnetTool("simpleUsage", "dotnet-ef");
+
+var wildcardVersion = builder.AddDotnetTool("wildcard", "dotnet-ef")
+    .WithToolVersion("10.0.*")
+    .WithParentRelationship(simpleUsage);
+
+var preRelease = builder.AddDotnetTool("prerelease", "dotnet-ef")
+    .WithToolPrerelease()
+    .WithParentRelationship(simpleUsage);
+
+// Multiple versions
+var differentVersion = builder.AddDotnetTool("sameToolDifferentVersion1", "dotnet-dump")
+    .WithArgs("--version")
+    .WithToolVersion("9.0.652701");
+builder.AddDotnetTool("sameToolDifferentVersion2", "dotnet-dump")
+    .WithToolVersion("9.0.621003")
+    .WithArgs("--version")
+    .WithParentRelationship(differentVersion);
+
+// Concurrency
+IResourceBuilder<DotnetToolResource>? concurrencyParent = null;
+for (int i = 0; i < 5; i++)
+{
+    var concurrency = builder.AddDotnetTool($"sametoolconcurrency-{i}", "dotnet-trace")
+        .WithArgs("--version");
+
+    if (concurrencyParent == null)
+    {
+        concurrencyParent = concurrency;
+    }
+    else
+    {
+        concurrency.WithParentRelationship(concurrencyParent);
+    }
+}
+
+// Substitution
+var substituted = builder.AddDotnetTool("substituted", "dotnet-ef")
+    .WithCommand("calc")
+    .WithIconName("Calculator")
+    .WithExplicitStart();
+foreach(var toolAnnotation in substituted.Resource.Annotations.OfType<DotnetToolAnnotation>().ToList())
+{
+    substituted.Resource.Annotations.Remove(toolAnnotation);
+}
+
+// Fake Offline by using "empty" package feeds
+var fakeSourcesPath = Path.Combine(Path.GetTempPath(), "does-not-exist", Guid.NewGuid().ToString());
+var offline = builder.AddDotnetTool("offlineSimpleUsage", "dotnet-ef")
+    .WithToolSource(fakeSourcesPath)
+    .WithToolIgnoreExistingFeeds()
+    .WithToolIgnoreFailedSources()
+    ;
+
+builder.AddDotnetTool("offlineWildcard", "dotnet-ef")
+    .WithToolVersion("10.0.*")
+    .WithParentRelationship(offline)
+    .WithToolSource(fakeSourcesPath)
+    .WithToolIgnoreExistingFeeds()
+    .WithToolIgnoreFailedSources();
+
+builder.AddDotnetTool("offlinePrerelease", "dotnet-ef")
+    .WithToolPrerelease()
+     .WithParentRelationship(offline)
+    .WithToolSource(fakeSourcesPath)
+    .WithToolIgnoreExistingFeeds()
+    .WithToolIgnoreFailedSources();
+
+var secret = builder.AddParameter("secret", "Shhhhhhh", secret: true);
+
+// Secrets
+builder.AddDotnetTool("secretArg", "dotnet-ef")
+    .WithArgs("--version")
+    .WithArgs(secret);
+
+// Some issues only show up when installing for first time, rather than using existing downloaded versions
+// Use a specific NUGET_PACKAGES path for these playground tools, so we can easily reset them
+builder.Eventing.Subscribe<BeforeStartEvent>(async (evt, _) =>
+{
+    var nugetPackagesPath = Path.Join(evt.Services.GetRequiredService<IAspireStore>().BasePath, "nuget");
+
+    foreach (var resource in builder.Resources.OfType<DotnetToolResource>())
+    {
+        builder.CreateResourceBuilder(resource)
+            .WithEnvironment("NUGET_PACKAGES", nugetPackagesPath)
+            .WithCommand("reset", "Reset Packages", ctx =>
+            {
+                try
+                {
+                    Directory.Delete(nugetPackagesPath, true);
+                    return Task.FromResult(CommandResults.Success());
+                }
+                catch (Exception ex)
+                {
+                    return Task.FromResult(CommandResults.Failure(ex));
+                }
+            }, new CommandOptions
+            {
+                IconName = "Delete"
+            });
+    }
+});
+
+#if !SKIP_DASHBOARD_REFERENCE
+// This project is only added in playground projects to support development/debugging
+// of the dashboard. It is not required in end developer code. Comment out this code
+// or build with `/p:SkipDashboardReference=true`, to test end developer
+// dashboard launch experience, Refer to Directory.Build.props for the path to
+// the dashboard binary (defaults to the Aspire.Dashboard bin output in the
+// artifacts dir).
+builder.AddProject<Projects.Aspire_Dashboard>(KnownResourceNames.AspireDashboard);
+#endif
+
+builder.Build().Run();
+

playground/DotnetTool/DotnetTool.AppHost/DotnetTool.AppHost.csproj

@@ -0,0 +1,19 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>$(DefaultTargetFramework)</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsAspireHost>true</IsAspireHost>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <Compile Include="$(SharedDir)KnownResourceNames.cs" Link="Utils\KnownResourceNames.cs" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <AspireProjectOrPackageReference Include="Aspire.Hosting.AppHost" />
+  </ItemGroup>
+
+</Project>

playground/DotnetTool/DotnetTool.AppHost/Properties/launchSettings.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "http://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "https://localhost:16179;http://localhost:16180",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "DOTNET_ENVIRONMENT": "Development",
+        "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:17119",
+        "ASPIRE_DASHBOARD_MCP_ENDPOINT_URL": "https://localhost:18036",
+        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:17119",
+        "ASPIRE_SHOW_DASHBOARD_RESOURCES": "true"
+      }
+    },
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "http://localhost:16180",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "DOTNET_ENVIRONMENT": "Development",
+        "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:17120",
+        "ASPIRE_DASHBOARD_MCP_ENDPOINT_URL": "http://localhost:18037",
+        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:17120",
+        "ASPIRE_SHOW_DASHBOARD_RESOURCES": "true",
+        "ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true"
+      }
+    },
+    "generate-manifest": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "commandLineArgs": "--publisher manifest --output-path aspire-manifest.json",
+      "applicationUrl": "http://localhost:16180",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "DOTNET_ENVIRONMENT": "Development",
+        "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:17120"
+      }
+    }
+  }
+}

playground/DotnetTool/DotnetTool.AppHost/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

playground/DotnetTool/DotnetTool.AppHost/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning",
+      "Aspire.Hosting.Dcp": "Warning"
+    }
+  }
+}

src/Aspire.Dashboard/Model/ResourceSourceViewModel.cs

@@ -16,11 +16,15 @@ public class ResourceSourceViewModel(string value, List<LaunchArgument>? content
     {
         var commandLineInfo = GetCommandLineInfo(resource);
 
-        // NOTE projects are also executables, so we have to check for projects first
+        // NOTE project and tools are also executables, so check for those first
         if (resource.IsProject() && resource.TryGetProjectPath(out var projectPath))
         {
             return CreateResourceSourceViewModel(Path.GetFileName(projectPath), projectPath, commandLineInfo);
         }
+        if (resource.IsTool() && resource.TryGetToolPackage(out var toolPackage))
+        {
+            return CreateResourceSourceViewModel(toolPackage, toolPackage, commandLineInfo);
+        }
 
         if (resource.TryGetExecutablePath(out var executablePath))
         {

src/Aspire.Dashboard/Model/ResourceViewModelExtensions.cs

@@ -19,6 +19,11 @@ public static bool IsProject(this ResourceViewModel resource)
         return StringComparers.ResourceType.Equals(resource.ResourceType, KnownResourceTypes.Project);
     }
 
+    public static bool IsTool(this ResourceViewModel resource)
+    {
+        return StringComparers.ResourceType.Equals(resource.ResourceType, KnownResourceTypes.Tool);
+    }
+
     public static bool IsExecutable(this ResourceViewModel resource, bool allowSubtypes)
     {
         if (StringComparers.ResourceType.Equals(resource.ResourceType, KnownResourceTypes.Executable))
@@ -48,6 +53,11 @@ public static bool TryGetProjectPath(this ResourceViewModel resource, [NotNullWh
     {
         return resource.TryGetCustomDataString(KnownProperties.Project.Path, out projectPath);
     }
+
+    public static bool TryGetToolPackage(this ResourceViewModel resource, [NotNullWhen(returnValue: true)] out string? projectPath)
+    {
+        return resource.TryGetCustomDataString(KnownProperties.Tool.Package, out projectPath);
+    }
 
     public static bool TryGetExecutablePath(this ResourceViewModel resource, [NotNullWhen(returnValue: true)] out string? executablePath)
     {

src/Aspire.Hosting/ApplicationModel/AppLaunchArgumentAnnotation.cs

@@ -9,7 +9,7 @@ namespace Aspire.Hosting.ApplicationModel;
 /// Represents a container or project application launch argument.
 /// </summary>
 [DebuggerDisplay("Type = {GetType().Name,nq}, Argument = {Argument}, IsSensitive = {IsSensitive}")]
-internal sealed class AppLaunchArgumentAnnotation(string argument, bool isSensitive) : IResourceAnnotation
+internal sealed class AppLaunchArgumentAnnotation(string argument, bool isSensitive)
 {
     /// <summary>
     /// The evaluated launch argument.

src/Aspire.Hosting/ApplicationModel/DotnetToolAnnotation.cs

@@ -0,0 +1,45 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Diagnostics.CodeAnalysis;
+
+namespace Aspire.Hosting.ApplicationModel;
+/// <summary>
+/// Represents an annotation for dotnet tool resources.
+/// </summary>
+[Experimental("ASPIREDOTNETTOOL", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
+public class DotnetToolAnnotation : IResourceAnnotation
+{
+    /// <summary>
+    /// The NuGet package ID of the .NET tool to execute. You can optionally specify a version using the <c>@</c> syntax, for example <c>dotnetsay@2.1</c>.
+    /// </summary>
+    public required string PackageId { get; set; }
+
+    /// <summary>
+    /// The version of the tool package to install.
+    /// </summary>
+    public string? Version { get; set; }
+
+    /// <summary>
+    /// Allows prerelease packages to be selected when resolving the version to install.
+    /// </summary>
+    public bool Prerelease { get; set; }
+
+    /// <summary>
+    /// NuGet package sources to use during installation
+    /// </summary>
+    public List<string> Sources { get; } = [];
+
+    /// <summary>
+    /// Are custom sources used in addition or instead of existing feeds.
+    /// </summary>
+    /// <remarks>
+    /// This value has no impact if <see cref="Sources"/> is empty.
+    /// </remarks>
+    public bool IgnoreExistingFeeds { get; set; }
+
+    /// <summary>
+    /// Treats package source failures as warnings.
+    /// </summary>
+    public bool IgnoreFailedSources { get; set; }
+}

src/Aspire.Hosting/ApplicationModel/DotnetToolResource.cs

@@ -0,0 +1,40 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
+
+namespace Aspire.Hosting.ApplicationModel;
+
+/// <summary>
+/// A resource that represents a specified dotnet tool.
+/// </summary>
+/// <remarks>
+/// This class is used to define and manage resources for .NET CLI tools. It associates a tool's name and
+/// command with its package ID, and ensures that the required metadata is properly annotated.
+/// </remarks>
+[Experimental("ASPIREDOTNETTOOL", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
+[DebuggerDisplay("Type = {GetType().Name,nq}, Name = {Name}, Tool = {ToolConfiguration?.PackageId}")]
+public class DotnetToolResource : ExecutableResource
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DotnetToolResource"/> class.
+    /// </summary>
+    /// <param name="name">The name of the resource.</param>
+    /// <param name="packageId">The package id of the tool.</param>
+    public DotnetToolResource(string name, string packageId)
+        : base(name, "dotnet", ".")
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(packageId, nameof(packageId));
+        Annotations.Add(new DotnetToolAnnotation { PackageId = packageId });
+    }
+
+    internal DotnetToolAnnotation? ToolConfiguration
+    {
+        get
+        {
+            this.TryGetLastAnnotation<DotnetToolAnnotation>(out var toolConfig);
+            return toolConfig;
+        }
+    }
+}