Skip to content

Add documentation for RID-specific and AOT .NET tools #49874

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Add documentation for RID-specific and AOT .NET tools #49874

wants to merge 4 commits into from

Conversation

Copy link
Contributor

Copilot AI commented Nov 12, 2025 •
edited by meaghanlewis
Loading

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)

💬 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 AI changed the title [WIP] Add article on dotnet tools support for RID-specific and AOT packages Add documentation for RID-specific and AOT .NET tools Nov 12, 2025
Copilot AI requested a review from meaghanlewis November 12, 2025 23:46
Copilot finished work on behalf of meaghanlewis November 12, 2025 23:46
@meaghanlewis meaghanlewis marked this pull request as ready for review November 14, 2025 20:07
@meaghanlewis meaghanlewis requested a review from a team as a code owner November 14, 2025 20:07
Copilot AI review requested due to automatic review settings November 14, 2025 20:07
Copilot finished reviewing on behalf of meaghanlewis November 14, 2025 20:11
Copilot AI reviewed Nov 14, 2025
View reviewed changes
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

docs/core/tools/rid-specific-tools.md
<TargetFramework>net9.0</TargetFramework>
<PackAsTool>true</PackAsTool>
<ToolCommandName>mytool</ToolCommandName>
<RuntimeIdentifier>win-x64;linux-x64;osx-arm64</RuntimeIdentifier>
Copy link

Copilot AI Nov 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The property name should be RuntimeIdentifiers (plural) not RuntimeIdentifier (singular) when specifying multiple RID values. The plural form is required when you provide a semicolon-delimited list of RIDs.

Suggested change
<RuntimeIdentifier>win-x64;linux-x64;osx-arm64</RuntimeIdentifier>
<RuntimeIdentifiers>win-x64;linux-x64;osx-arm64</RuntimeIdentifiers>

Copilot uses AI. Check for mistakes.
docs/core/tools/rid-specific-tools.md
Comment on lines +110 to +111
- **DotnetTool**: The top-level package that contains metadata
- **DotnetToolRidPackage**: The RID-specific packages that contain the actual tool binaries
Copy link

Copilot AI Nov 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

List items with more than three words must end with periods. Add periods to the end of both list items.

Copilot generated this review using guidance from repository custom instructions.
docs/core/tools/rid-specific-tools.md

### ToolPackageRuntimeIdentifier property

Alternatively, use `ToolPackageRuntimeIdentifier` for tool-specific RID configuration:
Copy link

Copilot AI Nov 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The text should reference ToolPackageRuntimeIdentifiers (plural), not ToolPackageRuntimeIdentifier (singular), as the property accepts multiple RID values.

Copilot uses AI. Check for mistakes.
docs/core/tools/rid-specific-tools.md
@@ -0,0 +1,214 @@
---
title: Create RID-specific, self-contained, and AOT .NET tools
description: Learn how to create and package RID-specific, self-contained and AOT .NET tools for platform-specific distribution.
Copy link

Copilot AI Nov 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add an Oxford comma before "and" in the list. It should read: "RID-specific, self-contained, and AOT .NET tools".

Copilot generated this review using guidance from repository custom instructions.
docs/core/tools/rid-specific-tools.md
<TargetFramework>net9.0</TargetFramework>
<PackAsTool>true</PackAsTool>
<ToolCommandName>mytool</ToolCommandName>
<ToolPackageRuntimeIdentifier>win-x64;linux-x64;osx-arm64</ToolPackageRuntimeIdentifier>
Copy link

Copilot AI Nov 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The property name should be ToolPackageRuntimeIdentifiers (plural) not ToolPackageRuntimeIdentifier (singular) when specifying multiple RID values with a semicolon-delimited list.

Suggested change
<ToolPackageRuntimeIdentifier>win-x64;linux-x64;osx-arm64</ToolPackageRuntimeIdentifier>
<ToolPackageRuntimeIdentifiers>win-x64;linux-x64;osx-arm64</ToolPackageRuntimeIdentifiers>

Copilot uses AI. Check for mistakes.
docs/core/tools/rid-specific-tools.md

### RuntimeIdentifier property

Use `RuntimeIdentifier` to specify the platforms your tool supports:
Copy link

Copilot AI Nov 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The text should reference RuntimeIdentifiers (plural), not RuntimeIdentifier (singular), as the property accepts multiple RID values.

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@meaghanlewis meaghanlewis Awaiting requested review from meaghanlewis meaghanlewis is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

@meaghanlewis meaghanlewis

Copilot code review Copilot

Labels

dotnet-cli/subsvc dotnet-fundamentals/svc

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[New article]: dotnet tools support RID-specific and AOT packages

2 participants

@meaghanlewis