How do you turn a .NET 10 console project into an installable .NET tool with PackAsTool and ToolCommandName, and what changed for RID-specific tools?
answer
- OutputType Exe plus PackAsTool true
- ToolCommandName defaults to the target name
- package type DotnetTool
- dotnet- prefix enables dotnet <name>
- RuntimeIdentifiers now yield per-RID packages
basics
~20 sSet PackAsTool to true in an Exe project and optionally ToolCommandName; dotnet pack then builds a NuGet package of type DotnetTool that dotnet tool install accepts. In .NET 10, RuntimeIdentifiers or ToolPackageRuntimeIdentifiers produce RID-specific tool packages.
solid answer
~40 sA tool project is a normal console project (`<OutputType>Exe</OutputType>`, a `net*` target framework) with `<PackAsTool>true</PackAsTool>`. `dotnet pack` then produces a package whose type is `DotnetTool` and which carries a `DotnetToolSettings.xml` naming the command and entry point. `ToolCommandName` sets the command users type; when omitted it defaults to the project's target name, and since .NET 10 the SDK sets that default only when `PackAsTool` is true. Naming the command `dotnet-<name>` lets users run it as `dotnet <name>`. Also new in .NET 10: when the project lists `RuntimeIdentifiers` (or `ToolPackageRuntimeIdentifiers`), pack creates RID-specific packages, which can be self-contained or Native AOT, plus a primary package, and install picks the right one for the machine.
code
xml · 11 lines<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
<PackAsTool>true</PackAsTool>
<PackageId>PrintShop.Tools.Labels</PackageId>
<ToolCommandName>print-labels</ToolCommandName>
<!-- .NET 10: one package per platform, plus a primary package -->
<ToolPackageRuntimeIdentifiers>win-x64;linux-x64</ToolPackageRuntimeIdentifiers>
</PropertyGroup>
</Project>go deeper
Recall that PackAsTool true plus dotnet pack turns a console project into a tool package, and ToolCommandName sets the command.
Explain the defaults for the command name and package id, the dotnet- prefix convention, and how to install the package from a local folder to test it.
Show you know the .NET 10 changes: RID-specific, self-contained or AOT tool packages, the RuntimeIdentifiers packing behaviour change, and ToolCommandName no longer set for non-tool projects.
Decide how internal tools are distributed: framework-dependent for reach, RID-specific AOT for startup and no runtime dependency, and which feed and versioning policy teams consume them through.
## What makes a project a tool Any console application can become a **.NET tool**. The project needs: - `<OutputType>Exe</OutputType>`: tools are executables. - A .NET (`net*`) target framework: the SDK rejects tools that target .NET Framework or .NET Standard. - `<PackAsTool>true</PackAsTool>`: tells `dotnet pack` to lay the package out as a tool. `dotnet pack -c Release` (the packaging topic covers pack itself) produces a `.nupkg` whose **package type is `DotnetTool`**. Inside it the SDK writes `DotnetToolSettings.xml`, which records the command name, the entry point assembly and the runner. The `dotnet tool install` commands refuse packages that are not of a tool type, so an ordinary library package cannot be installed as a tool by accident. ## Naming the command | Property | Default | Purpose | |---|---|---| | `ToolCommandName` | the project's target name (assembly name) | the command users type | | `PackageId` | the assembly name | the id passed to `dotnet tool install` | | `ToolEntryPoint` | the built `.dll` (or native executable for platform-specific tools) | what the shim starts | Two naming choices matter: 1. If `ToolCommandName` starts with `dotnet-`, users can type `dotnet <rest>`: the EF Core tool's command is `dotnet-ef`, invoked as `dotnet ef`. 2. The package id and the command name are independent; a package `PrintShop.Tools.Labels` can expose the command `print-labels`. A **.NET 10 breaking change**: `ToolCommandName` used to be set for every project during build and pack. Now the SDK sets its default only when `PackAsTool` is `true`, so build logic in a non-tool project that read `$(ToolCommandName)` must set the property itself. ## Testing the package locally Install from the folder pack wrote to before publishing anywhere: - `dotnet tool install -g PrintShop.Tools.Labels --add-source ./bin/Release` installs globally from that folder. - Without `-g` it goes into the repository's manifest, which is how a team trials an internal tool. ## RID-specific tools in .NET 10 Classic tools are **framework-dependent and platform-agnostic**: one package with IL that runs wherever a compatible runtime is installed. The .NET 10 SDK adds **RID-specific tools**: - List the platforms in `RuntimeIdentifiers` or, to affect only tool packaging, `ToolPackageRuntimeIdentifiers` (for example `win-x64;linux-x64;osx-arm64`). - `dotnet pack` creates one **RID-specific package per runtime identifier** (package type `DotnetToolRidPackage`) plus a **primary package** that points to them. - Those packages can be self-contained, trimmed or Native AOT (`PublishAot`), so the tool can start fast and need no runtime installed. - `dotnet tool install` reads the primary package and installs the best match for the current machine. This is also a behaviour change: a `PackAsTool` project that already listed `RuntimeIdentifiers` for other reasons now produces RID-specific packages, so projects that want the old single package must stop listing them for packing. `PackAsToolShimRuntimeIdentifiers` is an older, separate feature: it bundles prebuilt launcher shims for the listed platforms (the EF Core tool ships Windows shims this way) while the tool itself stays framework-dependent. ## Common mistakes - Forgetting `OutputType` Exe: a library project with `PackAsTool` set does not produce a runnable tool. - Choosing a command name that collides with an existing tool or system command on users' machines; a `dotnet-` prefix or a company prefix avoids surprises. - Adding `RuntimeIdentifiers` for an unrelated reason to a tool project upgraded to .NET 10 and then wondering why pack produces several packages. - Testing only with `dotnet run`: an installed tool is started by the tools machinery (a generated shim for global tools), with the command name and entry point from the package, so install the packed package from a local folder before publishing it to a feed.
- Why would a tool author set RollForward to Major in the tool project?A framework-dependent tool otherwise needs the runtime major version it was built for. With `RollForward` set to `Major` it also starts on a newer major runtime, so users with only the latest runtime installed can run it; the EF Core tool's project does this.
- How does a user know a package is a tool before installing it?Tool packages carry the `DotnetTool` package type; `dotnet tool search` and the NuGet.org .NET tool filter list only those packages, and `dotnet tool install` rejects a package without a tool type.
- A class library can be packed as a tool if PackAsTool is set.
- The tool's command name always equals its package id.
- ToolCommandName is still populated for every project in .NET 10.
- Listing RuntimeIdentifiers has no effect on how a PackAsTool project packs.
- A RID-specific tool package installs on every operating system.
Assumes the .NET 10 SDK; RID-specific tool packages and ToolCommandName being set only for PackAsTool projects are .NET 10 changes.