dotnet-core/samples/dotnetsay

dotnetsay .NET Tool Sample

This sample demonstrates how to use and create .NET Tools. It works on Windows, macOS and Linux.

You must have the .NET SDK installed. .NET Core 3.1 is recommended.

Installation

You can quickly install and try the dotnetsay:

dotnet tool install -g dotnetsay
dotnetsay

Note: You may need to open a new command/terminal window the first time you install a tool.

You can uninstall the tool using the following command.

dotnet tool uninstall -g dotnetsay

Also see dotnet-runtimeinfo.

Build the Tool from source

You can build and package the tool using the following commands. The instructions assume that you are in the root of the repository.

cd samples
cd dotnetsay
dotnet pack -c Release -o nupkg
dotnet tool install --add-source .\nupkg -g dotnetsay
dotnetsay

Note: On macOS and Linux, .\nupkg will need be switched to ./nupkg to accommodate for the different slash directions.

You can uninstall the tool using the following command.

dotnet tool uninstall -g dotnetsay

The PackAsTool property in the project file enables packing a console application as a global tool, as you can see in the following simplified example. Applications must target .NET Core 2.1 or higher for .NET Tools.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp2.1</TargetFramework>
    <PackAsTool>true</PackAsTool>
  </PropertyGroup>

</Project>

Enabling Source Link with Tools

You can make tools and libraries debuggable with Source Link by adding the following properties and PackageReference. The example is specific to git and GitHub. See dotnet/sourcelink for other options.

<PropertyGroup>
  <PublishRepositoryUrl>true</PublishRepositoryUrl>
  <DebugType>embedded</DebugType>
  <EmbedUntrackedSources>true</EmbedUntrackedSources>
</PropertyGroup>

<ItemGroup>
  <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.0.0" PrivateAssets="All"/>
</ItemGroup>

When you or your users debug your binaries with Source Link, the debugger will attempt to retrieve content (like .cs files) from the recorded git commit in your binaries. The given commit needs to be published to a public or accessible private repo in order for that to work. This means that you should build from a branch whose commits are stable and already published. You can build from a PR branch, but the commits may not remain stable for long, as the PRs may be squashed on merge.

For official builds, we recommend that you enable ContinuousIntegrationBuild, so that the built artifacts are reproducible and deterministic (same outcome independent of build machine or time).

The dotnetsay project doesn't add these properties or the PackageReference but relies on the same information in the Directory.Build.props in the parent directory. The use of a Directory.Build.props is recommended for Source Link, to avoid maintaining these settings in multiple project files.

Source Link will fail if it cannot find a .git directory. This can happen if you build projects in containers at solution root and not repo root for example. There are solutions to that problem described at the dotnet/sourcelink repo.

Debug Tools with Visual Studio

You can debug Source Link enabled .NET Tools with Visual Studio, using the Developer Command Prompt for VS 2017. The following example launches dotnetsay for debugging:

devenv /debugexe c:\Users\rich\.dotnet\tools\dotnetsay.exe

Set Debugger Type to Managed (CoreCLR) in Properties. Then Step Into new instance from the Debug menu.

You will be asked if you want to download source from GitHub. After that, you will then be able to step through the execution of the tool.