Change the .NET tool tutorial by adegeo · Pull Request #52952 · dotnet/docs

adegeo · 2026-04-08T21:57:20Z

Summary

TODO

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-how-to-use.md	"Tutorial: Install and use a .NET global tool"
docs/core/tools/local-tools-how-to-use.md	Tutorial: Install and use a .NET local tool using the .NET CLI

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

Rename microsoft.botsay to �otsay across the three-part .NET tool tutorial series to avoid teaching users to create packages with reserved company name prefixes on NuGet.org. - global-tools-how-to-create.md: rename project/folder/namespace/package references; add NOTE about avoiding company-owned NuGet prefixes - global-tools-how-to-use.md: update all install/uninstall/dnx commands and output blocks - local-tools-how-to-use.md: update folder, install, manifest JSON, output blocks, and tool list output Fixes #43983 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Replace the novelty `botsay` ASCII robot tool with `dotnet-env`, a practical tool that reports .NET runtime info, OS details, and key environment variable settings. Changes span the three-part tutorial series and add proper snippet files. - global-tools-how-to-create.md: replace all botsay code and prose with dotnet-env implementation; add snippet reference via :::code:::; add verified dotnet run output block - global-tools-how-to-use.md: update all install/uninstall/dnx commands; fix "may" → "might"; fix "Nuget.org" → "NuGet.org" - local-tools-how-to-use.md: update all commands, manifest JSON, output blocks; remove stale .NET Core 2.1 prerequisite - snippets/global-tools-how-to-create/csharp/Program.cs: new snippet file with four region markers (full-program, main-method, show-info-method, using-directives) - snippets/global-tools-how-to-create/csharp/dotnet-env.csproj: new project file for snippet verification Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Update all 'applies to' banners from .NET Core 2.1/.NET Core 3.0 to .NET 8 - Update prerequisites link and prose from .NET SDK 6.0 to .NET 8 - Update dotnet new -f flag from net6.0 to net8.0 - Update multi-target example from net8.0;net6.0 to net9.0;net8.0 - Update sample output Runtime section from 6.0.36 to 8.0.14 - Update project file TargetFramework from net6.0 to net8.0 in both article and snippet Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- dotnet new command: -f net8.0 -> -f net10.0 - Prerequisites: link and prose updated to .NET SDK 10.0 - NOTE text: 'targets .NET 8' -> 'targets .NET 10' - Multi-target example: net9.0;net8.0 -> net10.0;net8.0 - Project file XML in prose: net8.0 -> net10.0 - Sample output: updated to real .NET 10.0.4 / win-x64 output (verified via dotnet run) - Snippet .csproj: net8.0 -> net10.0 - Minimum requirement ('applies to' banner and historical notes) unchanged Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…ed repos)" This reverts commit 53b549a.

Copilot

Pull request overview

Updates the .NET tool tutorial series to use a new sample tool (dotnet-env) and refreshes the tutorials for newer .NET versions.

Changes:

Replaces the prior microsoft.botsay sample with a new dotnet-env tool and updates commands/output throughout the global and local tool tutorials.
Adds new C# snippet sources for the tool (Program.cs) and packing configuration (dotnet-env.csproj) and references them from the create tutorial.
Refreshes tutorial metadata (dates, applies-to), and modernizes some wording.

Reviewed changes

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

Show a summary per file

File	Description
docs/core/tools/snippets/global-tools-how-to-create/csharp/Program.cs	Adds the new sample tool implementation used by the tutorial.
docs/core/tools/snippets/global-tools-how-to-create/csharp/dotnet-env.csproj	Adds tool packing settings and snippet regions referenced by the tutorial.
docs/core/tools/global-tools-how-to-create.md	Switches the “create” tutorial to the new `dotnet-env` sample and snippet-based code inclusion.
docs/core/tools/global-tools-how-to-use.md	Updates global tool usage steps to the new sample and includes `dnx`-based run guidance.
docs/core/tools/local-tools-how-to-use.md	Updates local tool usage steps to the new sample and new command examples.

Comments suppressed due to low confidence (1)

docs/core/tools/global-tools-how-to-use.md:21

The article says it applies to .NET 8 SDK and later, but the tutorial content relies on .NET 10 (dnx starting with .NET 10.0.100). Align the applies to line with the actual minimum SDK needed for the steps, or clearly split steps into .NET 8-compatible vs .NET 10-only.

**This article applies to:** ✔️ .NET 8 SDK and later versions

This tutorial teaches you how to install and use a global tool. You use a tool that you create in the [first tutorial of this series](global-tools-how-to-create.md).

## Prerequisites

* Complete the [first tutorial of this series](global-tools-how-to-create.md).
* .NET 10.0.100 SDK or later (for `dnx`) - optional but recommended.

## Run the tool without installation (recommended)

Starting with .NET 10.0.100, you can run .NET tools without permanent installation using [`dnx`](dotnet-tool-exec.md):

Copilot · 2026-04-10T21:50:07Z

docs/core/tools/global-tools-how-to-create.md

+**This article applies to:** ✔️ .NET 8 SDK and later versions

 This tutorial teaches you how to create and package a .NET tool. The .NET CLI lets you create a console application as a tool, which others can install and run. .NET tools are NuGet packages that are installed from the .NET CLI. For more information about tools, see [.NET tools overview](global-tools.md).

-The tool that you'll create is a console application that takes a message as input and displays the message along with lines of text that create the image of a robot.
+The tool that you'll create is a console application that takes information about the current .NET environment and displays it, including the .NET version, operating system details, and key environment variable settings.

 This is the first in a series of three tutorials. In this tutorial, you create and package a tool. In the next two tutorials you [use the tool as a global tool](global-tools-how-to-use.md) and [use the tool as a local tool](local-tools-how-to-use.md). The procedures for creating a tool are the same whether you use it as a global tool or as a local tool.

 ## Prerequisites

- [.NET SDK 6.0.100](https://dotnet.microsoft.com/download/dotnet/6.0) or a later version.
+- [.NET SDK 10.0](https://dotnet.microsoft.com/download/dotnet/10.0) or a later version.

-  This tutorial uses .NET SDK 6.0, but global tools are available starting in .NET Core SDK 2.1. Local tools are available starting in .NET Core SDK 3.0.
+  This tutorial uses .NET SDK 10.0. Global tools are available starting in .NET Core SDK 2.1, and local tools are available starting in .NET Core SDK 3.0.


The article says it applies to .NET 8 SDK and later, but the tutorial requires .NET SDK 10.0 and the included project targets net10.0. Align the applies to line with the actual minimum SDK/runtime (or retarget the tutorial to net8.0 if you want it to apply to .NET 8).

Copilot · 2026-04-10T21:50:08Z

docs/core/tools/global-tools-how-to-create.md

+   The program has two methods:

-   internal class Program
-   {
-       static void Main(string[] args)
-       {
-           Console.WriteLine("Hello World!");
-       }
-   }
-   ```
+   - `Main` checks whether any arguments were passed. With no arguments, it calls `ShowInfo()`. With any argument, it prints the tool version.
+   - `ShowInfo` displays three sections of information:


This section describes a Main method, but the sample uses top-level statements (no explicit Main method in the source). Update the wording to refer to the program's entry point/top-level statements, or change the sample to an explicit Main method so the description matches the code.

Copilot · 2026-04-10T21:50:08Z

docs/core/tools/global-tools-how-to-use.md

 ## Run the tool without installation (recommended)

 Starting with .NET 10.0.100, you can run .NET tools without permanent installation using [`dnx`](dotnet-tool-exec.md):

 1. Run the tool directly using dnx (simplified syntax):

   ```dotnetcli
-   dnx microsoft.botsay --add-source ./nupkg microsoft.botsay hello from the bot
+   dnx dotnet-env --add-source ./nupkg
   ```

   The `--add-source` parameter tells the .NET CLI to use the *./nupkg* directory as an additional source feed for NuGet packages when the tool is not available on NuGet.org.


dnx dotnet-env --add-source ./nupkg depends on the current working directory containing the nupkg folder. The tutorial doesn't explicitly say to run this from the dotnet-env project folder (where ./nupkg is created). Clarify the required directory or change the command to use the correct relative path from where the user is expected to be.

Copilot · 2026-04-10T21:50:08Z

docs/core/tools/local-tools-how-to-use.md

+**This article applies to:** ✔️ .NET 8 SDK and later versions

 This tutorial teaches you how to install and use a local tool. You use a tool that you create in the [first tutorial of this series](global-tools-how-to-create.md).

 ## Prerequisites

 * Complete the [first tutorial of this series](global-tools-how-to-create.md).
-* Install the .NET Core 2.1 runtime.
 * .NET 10.0.100 SDK or later (for `dnx`) - optional but recommended.



The article says it applies to .NET 8 SDK and later, but the tutorial uses .NET 10 features (dnx from .NET 10.0.100) and depends on the tool built in the first tutorial (which targets .NET 10). Align the applies to line with the real minimum requirements, or adjust the tutorial so it works on .NET 8.

Copilot · 2026-04-10T21:50:09Z

docs/core/tools/local-tools-how-to-use.md

 - Run the tool directly using `dnx`:

   ```dotnetcli
-   dnx microsoft.botsay --add-source ./nupkg hello from the bot
+   dnx dotnet-env --add-source ./nupkg
   ```


At this point in the tutorial you're in the repository folder (cd ..), so the packed tool isn't in ./nupkg; it's in ./dotnet-env/nupkg (based on the first tutorial's <PackageOutputPath>). Update the --add-source path (or instruct the user to run dnx from the dotnet-env folder) so the command works as written.

adegeo and others added 6 commits April 8, 2026 09:12

chore: ignore .squad/ directory (personal/local, not for shared repos)

53b549a

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

Remove main method from program

205d549

dotnetrepoman bot added this to the April 2026 milestone Apr 8, 2026

dotnet-policy-service bot added dotnet-fundamentals/svc dotnet-cli/subsvc labels Apr 8, 2026

adegeo added 3 commits April 8, 2026 15:58

Adjust snippet ids

82deab3

REALLY fix snippet id

6d46f2a

Revert "chore: ignore .squad/ directory (personal/local, not for shar…

421eafd

…ed repos)" This reverts commit 53b549a.

adegeo marked this pull request as ready for review April 10, 2026 21:46

adegeo requested review from a team and meaghanlewis as code owners April 10, 2026 21:46

adegeo requested review from Copilot and gewarren April 10, 2026 21:46

adegeo assigned gewarren Apr 10, 2026

Copilot started reviewing on behalf of adegeo April 10, 2026 21:47 View session

Copilot AI reviewed Apr 10, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Change the .NET tool tutorial#52952

Change the .NET tool tutorial#52952
adegeo wants to merge 9 commits intomainfrom
adegeo/43983/tool

adegeo commented Apr 8, 2026 •

edited by github-actions bot

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

adegeo commented Apr 8, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Internal previews

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

adegeo commented Apr 8, 2026 •

edited by github-actions bot

Loading