Add article for RID-specific, self-contained and AOT .NET tools

[Copilot]

Summary

Adds comprehensive documentation for RID-specific and AOT-enabled .NET tools introduced in SDK 10.0.100-preview.6, enabling platform-specific distribution of native, trimmed tools.

Changes

New Article: rid-specific-tools.md

Documents the complete workflow for creating platform-specific tools:

• Opt-in configuration: RuntimeIdentifiers or ToolPackageRuntimeIdentifiers MSBuild properties
• Packaging workflows:
  • Non-AOT: Single dotnet pack generates N+1 packages (one per RID + pointer)
  • AOT: Requires per-platform dotnet pack -r <RID> on target systems
• Package types: DotnetTool (metadata) vs DotnetToolRidPackage (binaries)
• Installation: CLI automatically selects appropriate RID package from metadata
• Complete AOT example: End-to-end implementation with multi-platform packaging

Cross-references

• Added links from global-tools-how-to-create.md and global-tools.md

Example Configuration

<PropertyGroup>
  <PackAsTool>true</PackAsTool>
  <ToolCommandName>mytool</ToolCommandName>
  <RuntimeIdentifiers>win-x64;linux-x64;osx-arm64</RuntimeIdentifiers>
  <PublishAot>true</PublishAot>
</PropertyGroup>

Produces packages: mytool.1.0.0.nupkg, mytool.win-x64.1.0.0.nupkg, mytool.linux-x64.1.0.0.nupkg, mytool.osx-arm64.1.0.0.nupkg

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[New article]: dotnet tools support RID-specific and AOT packages</issue_title>
<issue_description>### Proposed topic or title

dotnet tools can be RID-specific, self-contained, or AOT applications now

Location in table of contents.

No response

Reason for the article

In .NET SDK 10.0.100-preview.6 we added support for a new way of authoring tools that enables packaging them for specific platforms and architectures. This makes it much simpler to easily distribute native, fast, trimmed .NET applications for use cases like MCP servers.

Article abstract

• How to opt in to the new behaviors
  • set RuntimeIdentifiers or ToolPackageRuntimeIdentifiers MSBuild properties to a semicolon-delimited list of RID values (win-x64;osx-arm64, etc).
• How the tooling reacts to the new model
  • If you're not doing AOT - dotnet pack on the tool will create N+1 NuGet packages - one for each RID called <packageName>.<RID>.<packageVersion>.nupkg, and as a RID-less pointer called <packageName>.<packageVersion>.nupkg like today.
  • If you are doing AOT, then you need to dotnet pack once for the top-level package, but then on separate platforms call dotnet pack -r <RID> to make the RID-specific packages manually
  • The top-level package has the same PackageType (DotnetTool), but the RID-specific packages have a new PackageType (DotnetToolRidPackage)
  • The top-level package contains metadata signalling that it is a RID-specific tool, and what the RID-specific packages are
  • Push all of these to NuGet.org
  • on dotnet tool install, if the top-level package's metadata signals that it is a RID-specific tool, the CLI will find and install the most relevant package for the user's current platform and invoke that
• Sample application

There is no design for this feature.
Initial implementation at dotnet/sdk#48575, follow-up usability tweaks at dotnet/sdk#49288

---

Document Details

⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.

• ID: b7e47565-cc59-b1a6-24be-0143c550c0b2
• Version Independent ID: c6859ca6-e2b1-3645-872c-60390ffd429a
• Platform ID: 71f88ad0-c497-bd84-bcae-a271c6be9107
• Content: .NET CLI
• Content Source: docs/core/tools/index.md
• Service: dotnet-fundamentals
• GitHub Login: @tdykstra
• Microsoft Alias: tdykstra

---

Associated WorkItem - 503206</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [New article]: dotnet tools support RID-specific and AOT packages #46801

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

---

Internal previews

📄 File	🔗 Preview link
docs/core/tools/global-tools-how-to-create.md	Tutorial: Create a .NET tool using the .NET CLI
docs/core/tools/global-tools.md	How to manage .NET tools
docs/core/tools/rid-specific-tools.md	Create RID-specific, self-contained, and AOT .NET tools
docs/navigate/tools-diagnostics/toc.yml	docs/navigate/tools-diagnostics/toc

[Copilot]

Pull Request Overview

This PR adds comprehensive documentation for RID-specific and AOT-enabled .NET tools, a feature introduced in .NET SDK 10.0.100-preview.6. The documentation enables tool authors to package and distribute platform-specific, native, and trimmed .NET tools.

• New article rid-specific-tools.md documenting the complete workflow for creating RID-specific tools
• Cross-reference links added to existing tool documentation
• TOC entry added for the new article

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 8 comments.

File	Description
docs/core/tools/rid-specific-tools.md	New comprehensive guide covering RID-specific tool configuration, packaging workflows for AOT and non-AOT scenarios, package structure, and complete examples
docs/core/tools/global-tools.md	Added cross-reference link to new RID-specific tools article
docs/core/tools/global-tools-how-to-create.md	Added "See also" section with link to RID-specific tools article
docs/navigate/tools-diagnostics/toc.yml	Added TOC entry for new RID-specific tools article

[meaghanlewis]

@baronfel this is ready for your review. Let me know if there's any details I can clarify or add.

[baronfel]

What do you think about linking to https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot here for further guidance about NAOT publishing? I was thinking of a call to action like

Learn more about the prerequisites for Native AOT compilation at Native AOT deployment.

What do you think?

[baronfel]

Specifying each package is possible, but I find people often just do

dotnet nuget push path/to/package/root/*.nupkg

[baronfel]

Can we highlight dnx instead of tool installation in this section?

## Run a RID-specific tool

Users run RID-specific tools the same way as platform-agnostic tools:

> dnx mytool

1. Downloads the top-level package.
1. Reads the RID-specific metadata.
1. Identifies the most appropriate package for the current platform.
1. Downloads and runs the RID-specific package.

...