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 2.1 or higher.

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

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 accomodate 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 global tools.

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

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

</Project>

Enabling SourceLink with Tools

You can make tools debuggable with sourcelink 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>

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.

Note: The approach used in Directory.build.props conditionalizes sourcelink properties and PackageReference to the ContinuousIntegrationBuild property being set. There is no problem running SourceLink on every build, however, it isn't necessary.

Use ContinuousIntegrationBuild when producing official builds. If you don't, the sourcelink information will be wrong. The simplest way to do that is by packing with an additional property set, as follows.

dotnet pack /p:ContinuousIntegrationBuild=true

Make sure to build official packages from branches/repositories with stable commit hashes. If you build from a branch whose commits are later squashed, then the commit hashs will not be found and sourcelink will not work correctly.

SourceLink 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 sourcelink repo.

Debug Tools with Visual Studio

You can debug sourcelink-enabled .NET Core Global 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.