Clarify RID-specific .NET tools packaging and add hybrid pattern guidance

[Copilot]

• Add platform requirements section for Native AOT
• Clarify that SDK can cross-compile for architecture but not OS
• Document build options: local machine, containers, or federated builds
• Explain that RID-specific packages don't need to be built on same machine/time
• Reorganize AOT tools section with clearer subheadings

Original prompt

Update the Learn article docs/core/tools/rid-specific-tools.md in the dotnet/docs repo to reflect clarified guidance on RID-specific .NET tools packaging, especially around RuntimeIdentifiers, ToolPackageRuntimeIdentifiers, and PublishAot, and to add the dotnet10-hybrid-tool sample.

Context:

• The current file is at commit 5d411bae985b4fdec557469fbe39c216cf702edc and available at: https://github.com/dotnet/docs/blob/5d411bae985b4fdec557469fbe39c216cf702edc/docs/core/tools/rid-specific-tools.md
• The user (richlander) built a demo repo at richlander/dotnet10-hybrid-tool that demonstrates a hybrid packaging pattern (Native AOT for selected RIDs with a CoreCLR any fallback). The README for that repo (commit 8234f4e70cacd1240ec0dc5952be82f8a1780e38) explains the pattern and should be referenced but not copied.

Required changes to docs/core/tools/rid-specific-tools.md:

1. Clarify when to use RuntimeIdentifiers vs ToolPackageRuntimeIdentifiers

   • Under “Opt in to RID-specific packaging”, after the existing RuntimeIdentifiers and ToolPackageRuntimeIdentifiers subsections, add a new subsection:

   ### When to use `RuntimeIdentifiers` vs `ToolPackageRuntimeIdentifiers`
   
   Both `RuntimeIdentifiers` and `ToolPackageRuntimeIdentifiers` opt your tool into RID-specific packaging, but they serve slightly different purposes:
   
   - Use **`RuntimeIdentifiers`** when:
     - You want the project to **build and publish RID-specific apps in general** (not just as a tool).
     - You are primarily targeting **CoreCLR** (non-AOT) or you want the standard SDK behavior where a single `dotnet pack` can produce RID-specific packages.
     - You may conditionalize `PublishAot` for a subset of RIDs, but you still want a CoreCLR-based package for every RID in `RuntimeIdentifiers`.
   
   - Use **`ToolPackageRuntimeIdentifiers`** when:
     - You want to define **RID-specific behavior only for the tool packaging**, without changing how the project builds for other deployment scenarios.
     - You’re using **Native AOT** and plan to **manually build** AOT binaries per RID with `dotnet pack -r <RID>`.
     - You want a **hybrid model** where some RIDs get Native AOT and others fall back to a portable CoreCLR implementation.
   
   In all cases where `PublishAot` is **not** set, the set of RIDs in `ToolPackageRuntimeIdentifiers` should be equal to or a subset of the RIDs in `RuntimeIdentifiers`. When `PublishAot` is enabled, RID-specific packages are generated only when you build for a specific RID (for example, `dotnet pack -r linux-x64`).
   
   The top-level pointer package is informed by `ToolPackageRuntimeIdentifiers` or `RuntimeIdentifiers`, in that precedence order: if `ToolPackageRuntimeIdentifiers` is specified, it determines the tool RIDs; otherwise, `RuntimeIdentifiers` is used.

2. Make PublishAot behavior explicit in the AOT tools section

   • In the “AOT tools” section (after the existing bullets explaining dotnet pack and dotnet pack -r), add:

   When you set `<PublishAot>true</PublishAot>`, the packing behavior changes:
   
   - A regular `dotnet pack` with `PublishAot=true`:
     - Produces the **top-level pointer package** (package type `DotnetTool`).
     - Does **not** automatically produce RID-specific packages, because Native AOT requires building on (or for) a specific platform.
   
   - RID-specific AOT packages are produced only when you explicitly pass `-r <RID>`:
     - `dotnet pack -r linux-x64`
     - `dotnet pack -r osx-arm64`
     - and so on.
   
   With `PublishAot=true`:
   
   - `RuntimeIdentifiers` or `ToolPackageRuntimeIdentifiers` describe the set of RIDs your tool intends to support.
   - You are responsible for invoking `dotnet pack -r <RID>` for each of those RIDs on the appropriate build environment (for example, on Windows for `win-x64`).

3. Add a “Hybrid AOT + CoreCLR packaging pattern (example)” subsection

   • Still under “AOT tools”, after the explanation above, add a new subsection that explains the pattern and references the demo repo, with this content:

   ### Hybrid AOT + CoreCLR packaging pattern (example)
   
   Some tools want the best of both worlds:
   
   - **Native AOT** for a subset of high-priority platforms (for example, Linux and macOS).
   - A **portable CoreCLR fallback** that works on any platform, including those without an AOT build (for example, Windows when no AOT build is produced).
   
   You can achieve this “hybrid” model with the following pattern:
   
   1. **Configure the tool for Native AOT and tool-specific RIDs**
   
      In your project file, use `ToolPackageRuntimeIdentifiers` and enable `PublishAot`:
   
      ```xml
      <Project Sdk="Microsoft.NET.Sdk">
        <PropertyGroup>
          <OutputType>Exe</OutputType>
          <TargetFramework>net10.0</TargetFramework>
          <PackAsTool>true</PackAsTool>
          <ToolCommandName>yourtool</ToolCommandName>
   
          <!--...
   

This pull request was created from Copilot chat.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

---

Internal previews

📄 File	🔗 Preview link
docs/core/tools/rid-specific-tools.md	Create RID-specific, self-contained, and AOT .NET tools

[richlander]

Thanks for the fixes @gewarren!