Dotnet Tool Integration by afscrome · Pull Request #13168 · dotnet/aspire

afscrome · 2025-11-24T19:42:24Z

Description

This Pr contains a dotnet tool resource type, currently marked as experimental. (Based on my initial work, and some of copilots work from #13169.).

Fixes #13077

It builds upon the Executable resource ultimately calling into dotnet tool exec - similar to how ProjectResource builds on top of ExecutableResource, and calls dotnet run or dotnet watch. Although I've avoided teaching dcp or the application orchestrator anything specific about dotnet tools.

Basic Use:

builder.AddDotnetTool("tool", "dotnet-ef")
            .WithArgs("--help");

With some helper methods on the resource builder for arguments on dotnet tool exec

.WithToolVersion("9.0.1");
.WithToolPrerelease();
.WithToolSource("./fake-package-feed");
.WithToolIgnoreExistingFeeds();
.WithToolIgnoreFailedSources();

Which are just wrappers over the DotnetToolAnnotation attached to the resource.

The resource sets custom resource properties so the dashboard renders the Source column for tools more natively, without focusing on the implementation details of dotnet tool exec
Without:

After:

Tool have a dedicated resource type, so you can filter to just tools

And also includes some tool specific properties. (Although these are only visible by choosing "show all properties"

Limitations / Known Issues

Requires the .Net 10 SDK be installed
- The tool's working directory must not be in the context of a a global.json file forcing an older sdk version.
If multiple instances of the same tool start concurrently, and the tool is not yet in the package cache, the dotnet sdk may fail with concurrency bugs - Concurrent Tool Installation can fail sdk#51831
There are some bugs in the dotnet sdk which may cause tools to be unavailable if you don't have access to the upstream feeds. (Even if the tool is in your local cache) dnx doesn't fall back to local cache when network is unavailable sdk#50579

Checklist

Is this feature complete?
- Yes. Ready to ship.
- No. Follow-up changes expected.
Are you including unit tests for the changes and scenario tests if relevant?
- Yes
- No
Did you add public API?
- Yes
  - If yes, did you have an API Review for it?
    - Yes
    - No
  - Did you add <remarks /> and <code /> elements on your triple slash comments?
    - Yes
    - No
- No
Does the change make any security assumptions or guarantees?
- Yes
  - If yes, have you done a threat model and had a security review?
    - Yes
    - No
- No
Does the change require an update in our Aspire docs?
- Yes
  - Link to aspire-docs issue (consider using one of the following templates):
- No

github-actions · 2025-11-24T19:42:33Z

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 13168

Or

Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 13168"

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

…ool.

…ence Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>

…ort allocation - Changed app URLs from 18001/18002 to 16179/16180 (standard app port range) - Updated OTLP endpoints from 18003/18005 to 17119/17120 (standard OTLP range) - Added MCP endpoints 18036/18037 (standard MCP range) - Updated Resource Service endpoints to match OTLP endpoints - Removed launchBrowser from generate-manifest profile for consistency Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>

- Removed DotnetToolInstaller.cs (leftover from dotnet tool install approach) - Created new test project Aspire.Hosting.DotnetTool.Tests with 22 tests - All tests pass and validate AddDotnetTool extension methods - Tests cover: basic usage, version specs, prerelease, custom sources, args, and manifest generation - Added using statements to playground files (needed for test linking) - Fixed DotnetToolResource to use "." as working directory (fixes manifest generation) - Added test project to solution file in alphabetical order Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>

Updated `ResourceSnapshotBuilder` to not override any custom resource types a consumer may have set. Updated `ApplicationOrchestrator` to also not set the resource type - we don't need two places in Aspire core setting the ResourceType

The implementation works, but isnt' great as it fights with DCP a lot.

afscrome · 2025-12-03T20:49:41Z

src/Aspire.Hosting/DotnetToolExtensions.cs

+            x.Args.Add("--");
+        }
+
+        static async Task StartSourceFixer(T resource, InitializeResourceEvent evt, CancellationToken ct)


This method is a hack and a half.

To make the source column show just the tool args, and not the internals of the dotnet command run, we need to set KnownProperties.Executable.Path and KnownProperties.Resource.AppArgs. The latter in turn also requires messing with KnownProperties.Resource.AppArgsSensitivity to ensure secrets are properly redacted.

However dcp will continually overwrite those properties every time an update occurs, so we need to respond to those and restore our values.

aspire/src/Aspire.Hosting/Dcp/ResourceSnapshotBuilder.cs

Lines 184 to 203 in 9c9755a

return previous with

{

ResourceType = KnownResourceTypes.Executable,

State = state,

ExitCode = executable.Status?.ExitCode,

Properties = previous.Properties.SetResourcePropertyRange([

new(KnownProperties.Executable.Path, executable.Spec.ExecutablePath),

new(KnownProperties.Executable.WorkDir, executable.Spec.WorkingDirectory),

new(KnownProperties.Executable.Args, executable.Status?.EffectiveArgs ?? []) { IsSensitive = true },

new(KnownProperties.Executable.Pid, executable.Status?.ProcessId),

new(KnownProperties.Resource.AppArgs, launchArguments?.Args) { IsSensitive = launchArguments?.IsSensitive ?? false },

new(KnownProperties.Resource.AppArgsSensitivity, launchArguments?.ArgsAreSensitive) { IsSensitive = launchArguments?.IsSensitive ?? false },

]),

EnvironmentVariables = environment,

CreationTimeStamp = executable.Metadata.CreationTimestamp?.ToUniversalTime(),

StartTimeStamp = executable.Status?.StartupTimestamp?.ToUniversalTime(),

StopTimeStamp = executable.Status?.FinishTimestamp?.ToUniversalTime(),

Urls = urls,

Relationships = relationships

};

So this method tries to respond to any update from DCP, and undo DCP's changes.

…ate`, without actually updating anything.

- Ensure tool source renders nicely before a resource starts - Add a property including the raw args to `dotnet tool exec` to help with troubleshooting if needed.

Enhances Aspire to treat dotnet tool resources as first-class citizens. - Adds KnownResourceTypes.Tool and updates DotnetToolResource to use it. - Sets tool package ID as the resource "Source" for dashboard clarity. - Adds IsTool and TryGetToolPackage extensions for resource model. - Updates dashboard to display tool package as source. - Refines argument handling: only tool-specific args are shown in dashboard, full args used for execution. - Refactors DotnetToolResourceExtensions and removes dashboard update workaround. - Removed unused `IResourceAnnotation` from AppLaunchArgumentAnnotation. - Adds and updates tests for tool resource handling. - Improves diagnostics with DebuggerDisplay and code cleanups.

Copilot

Pull request overview

This PR introduces experimental support for .NET tool resources in Aspire, allowing developers to run .NET global tools (like dotnet-ef, dotnet-dump, etc.) as Aspire resources using dotnet tool exec. This feature addresses the need for tool acquisition and execution without manual installation steps, building on the existing ExecutableResource infrastructure.

Key Changes:

New DotnetToolResource and DotnetToolAnnotation types for representing .NET tools as first-class resources
Extension methods for configuring tool version, prerelease support, custom NuGet sources, and feed behavior
Dashboard integration showing tools with a dedicated resource type and custom "Source" column display
Comprehensive test coverage including unit tests and functional tests

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 20 comments.

Show a summary per file

File	Description
src/Aspire.Hosting/ApplicationModel/DotnetToolResource.cs	New resource class representing .NET tool resources, inheriting from ExecutableResource
src/Aspire.Hosting/ApplicationModel/DotnetToolAnnotation.cs	New annotation class containing tool configuration (package ID, version, sources, flags)
src/Aspire.Hosting/DotnetToolResourceExtensions.cs	Extension methods for adding and configuring .NET tool resources with fluent API
src/Aspire.Hosting/Dcp/DcpExecutor.cs	Modified argument handling to distinguish between executable args and display args for tools
src/Aspire.Hosting/Dcp/ResourceSnapshotBuilder.cs	Updated to preserve ResourceType set via WithInitialState instead of overwriting
src/Aspire.Hosting/Orchestrator/ApplicationOrchestrator.cs	Removed ResourceType assignments as it's now set earlier via WithInitialState
src/Aspire.Hosting/ApplicationModel/AppLaunchArgumentAnnotation.cs	Removed IResourceAnnotation interface (internal implementation detail)
src/Shared/Model/KnownResourceTypes.cs	Added "Tool" resource type constant
src/Shared/Model/KnownProperties.cs	Added tool-specific properties (Package, Version, ExecArgs)
src/Aspire.Dashboard/Model/ResourceViewModelExtensions.cs	Added IsTool() and TryGetToolPackage() extension methods
src/Aspire.Dashboard/Model/ResourceSourceViewModel.cs	Updated source display logic to show tool package name in Source column
tests/Aspire.Hosting.DotnetTool.Tests/AddDotnetToolTests.cs	Comprehensive unit tests covering all configuration options and manifest generation
tests/Aspire.Hosting.DotnetTool.Tests/DotnetToolFunctionalTests.cs.cs	Functional tests verifying tool execution with successful and failed scenarios
tests/Aspire.Hosting.Tests/Dcp/DcpExecutorTests.cs	Added test for tool argument handling in DCP executor
tests/Aspire.Hosting.DotnetTool.Tests/Aspire.Hosting.DotnetTool.Tests.csproj	New test project for .NET tool resource tests
playground/DotnetTool/DotnetTool.AppHost/*	Sample AppHost demonstrating various tool configurations and edge cases
Aspire.slnx	Added references for new test project and playground app

src/Aspire.Hosting/ApplicationModel/DotnetToolAnnotation.cs

src/Aspire.Hosting/DotnetToolResourceExtensions.cs

tests/Aspire.Hosting.Tests/Dcp/DcpExecutorTests.cs

src/Aspire.Hosting/DotnetToolResourceExtensions.cs

src/Aspire.Hosting/ApplicationModel/DotnetToolAnnotation.cs

tests/Aspire.Hosting.DotnetTool.Tests/DotnetToolFunctionalTests.cs.cs

Copilot · 2026-01-01T21:03:14Z

src/Aspire.Hosting/DotnetToolResourceExtensions.cs

+    /// <summary>
+    /// Adds a .NET tool resource to the distributed application builder.
+    /// </summary>
+    /// <param name="builder">The <see cref="IDistributedApplicationBuilder"/>.</param>
+    /// <param name="name">The name of the resource.</param>
+    /// <param name="packageId">The package id of the tool.</param>
+    /// <returns>The <see cref="IResourceBuilder{T}"/>.</returns>


According to the XML documentation guidelines, public API extension methods should include an example showing practical usage. Consider adding an example section showing how to use AddDotnetTool.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

davidfowl

LGTM - clean implementation following Aspire patterns. Experimental flag is appropriate for new API.

davidfowl · 2026-01-15T07:19:39Z

Thanks for the contribution! This is a great addition to Aspire. 🎉

dotnet-policy-service bot added the community-contribution Indicates that the PR has been added by a community member label Nov 24, 2025

afscrome changed the title ~~Dotnettool~~ Dotnet Tool Integration Nov 24, 2025

afscrome force-pushed the dotnettool branch from 8e7fcb8 to 88c97dc Compare November 24, 2025 19:46

afscrome commented Nov 24, 2025

View reviewed changes

playground/DotnetTool/DotnetTool.AppHost/Properties/launchSettings.json Show resolved Hide resolved

Initial plan

5ec4c5d

Copilot AI mentioned this pull request Nov 24, 2025

Port .NET Tool Integration from PR #13168 #13169

Closed

14 tasks

afscrome mentioned this pull request Nov 24, 2025

Dotnet Tool Integration #13077

Closed

1 task

afscrome and others added 16 commits November 24, 2025 19:59

Initial playground using dotnet tool isntall and then running the t…

257a01e

…ool.

Rework to use dotnet tool exec

2c67f06

Port .NET Tool Integration from PR dotnet#13168 and fix package refer…

f60451b

…ence Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com>

Give tools their own resource type.

926c38c

Updated `ResourceSnapshotBuilder` to not override any custom resource types a consumer may have set. Updated `ApplicationOrchestrator` to also not set the resource type - we don't need two places in Aspire core setting the ResourceType

Format dotnet tools nicely in dashboard "source" column

434d1d7

The implementation works, but isnt' great as it fights with DCP a lot.

Remove verbosity argument.

52a95ba

Move dotnet tool implementation to Aspire.Hosting

5673ec9

Make dotnet tool apis experimental.

79ff8f8

Mark dotnet tool apis experimental.

e2e7a1d

Make secret tool example not fail.

fb569c9

Refactor to local functions to make slightly cleaner.

6efa250

Add properties to tool resources.

6247973

Add missing experimental supression in tests.

ebc8846

Fix formatting in tests

cedafb2

afscrome force-pushed the dotnettool branch from 88c97dc to cedafb2 Compare December 3, 2025 20:41

afscrome commented Dec 3, 2025

View reviewed changes

afscrome added 4 commits December 3, 2025 21:22

Missing docs.

0f3b1fb

Fix typos.

ca77ba1

Add functional tests.

6dab8e6

Refactored StartSourceFixer to minimise risk of calling `PublishUpd…

82559b5

…ate`, without actually updating anything.

afscrome and others added 8 commits December 4, 2025 17:24

Consistently use ArgumentSeperator

7834d5e

Renamed WithPackage* to WithTool*

a58e9ac

Tweaks.

dde6f90

Remove unused package.

d7a30ec

Small tweaks to tools

96dd4ec

- Ensure tool source renders nicely before a resource starts - Add a property including the raw args to `dotnet tool exec` to help with troubleshooting if needed.

Merge remote-tracking branch 'upstream/main' into dotnettool

f657a5a

Back to . as the initial working directory.

b0119ec

Merge remote-tracking branch 'upstream/main' into dotnettool

67e6dd5

afscrome mentioned this pull request Dec 18, 2025

ResourceSnapshotBuilder overwrites resource state, rather than merging with other customisations #13647

Open

1 task

afscrome added 2 commits December 23, 2025 09:31

Merge remote-tracking branch 'upstream/main' into dotnettool

c14ab62

Copilot AI review requested due to automatic review settings January 1, 2026 20:52

afscrome requested a review from mitchdenny as a code owner January 1, 2026 20:52

Copilot started reviewing on behalf of afscrome January 1, 2026 20:53 View session

Copilot AI reviewed Jan 1, 2026

View reviewed changes

afscrome and others added 4 commits January 1, 2026 21:12

Apply suggestions from code review

9fb3bc5

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

More PR feedback.

585f3a6

Fix rogue newline.

5329838

Self review

6e7f288

github-actions bot mentioned this pull request Jan 11, 2026

[pull requests] Review required #13834

Open

davidfowl approved these changes Jan 15, 2026

View reviewed changes

davidfowl merged commit cd3b5b9 into dotnet:main Jan 15, 2026
289 checks passed

dotnet-policy-service bot added this to the 13.2 milestone Jan 15, 2026

afscrome mentioned this pull request Jan 15, 2026

[13.2] Document Dotnet Tool support microsoft/aspire.dev#257

Closed

Copilot AI mentioned this pull request Jan 28, 2026

Document .NET tool support for Aspire 13.2 microsoft/aspire.dev#310

Merged

afscrome mentioned this pull request Jan 30, 2026

[main] Final logs for executable are lost #14262

Open

1 task

github-actions bot locked and limited conversation to collaborators Feb 14, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Dotnet Tool Integration#13168

Dotnet Tool Integration#13168
davidfowl merged 35 commits intodotnet:mainfrom
afscrome:dotnettool

afscrome commented Nov 24, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Nov 24, 2025 •

edited

Loading

Uh oh!

Uh oh!

afscrome Dec 3, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Jan 1, 2026

Uh oh!

davidfowl left a comment

Uh oh!

Uh oh!

davidfowl commented Jan 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	return previous with
	{
	ResourceType = KnownResourceTypes.Executable,
	State = state,
	ExitCode = executable.Status?.ExitCode,
	Properties = previous.Properties.SetResourcePropertyRange([
	new(KnownProperties.Executable.Path, executable.Spec.ExecutablePath),
	new(KnownProperties.Executable.WorkDir, executable.Spec.WorkingDirectory),
	new(KnownProperties.Executable.Args, executable.Status?.EffectiveArgs ?? []) { IsSensitive = true },
	new(KnownProperties.Executable.Pid, executable.Status?.ProcessId),
	new(KnownProperties.Resource.AppArgs, launchArguments?.Args) { IsSensitive = launchArguments?.IsSensitive ?? false },
	new(KnownProperties.Resource.AppArgsSensitivity, launchArguments?.ArgsAreSensitive) { IsSensitive = launchArguments?.IsSensitive ?? false },
	]),
	EnvironmentVariables = environment,
	CreationTimeStamp = executable.Metadata.CreationTimestamp?.ToUniversalTime(),
	StartTimeStamp = executable.Status?.StartupTimestamp?.ToUniversalTime(),
	StopTimeStamp = executable.Status?.FinishTimestamp?.ToUniversalTime(),
	Urls = urls,
	Relationships = relationships
	};

Conversation

afscrome commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Limitations / Known Issues

Checklist

Uh oh!

github-actions bot commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

afscrome Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Jan 1, 2026

Choose a reason for hiding this comment

Uh oh!

davidfowl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

davidfowl commented Jan 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

afscrome commented Nov 24, 2025 •

edited

Loading

github-actions bot commented Nov 24, 2025 •

edited

Loading

afscrome Dec 3, 2025 •

edited

Loading