Searching docs using a .NET Core global tool

by Shayne Boyer

In 2016 at the MVP Summit hackathon I put together a .NET Core CLI Tool to search for docs on docs.microsoft.com and it worked well, but there were some shortcomings. It was scoped to the project, and there was no way to install the Nuget package using the command line tools or package manager.

<ItemGroup>
 <DotNetCliToolReference Include="dotnet-doc" Version="1.0.0" />
</ItemGroup>

Now with the availability of .NET Core Global tools, see announcement post here, where we can install the Nuget package globally like a node.js package npm install -g <package_name>, I took a few hours to update the project.

dotnet install tool -g dotnet-doc

Getting Started

Nate McMaster has a great intro on .NET Core Global Tools and Gotchas where he explains some ins/outs, a getting started template, packaging the tool and so on.

I am just converting the project from the project.json, whoa that's a bit ago, to a global tool project I just need to add a .csproj file and delete the project.json file. However, I could use the template from Nate's post too to start new.

dotnet new dotnet-doc --command-name docs

The dotnet-docs.csproj file has really one important entry stating that this is a global tool and one to state what the command name is, other than that it's JUST a console application.

<PropertyGroup>
  <ToolCommandName>docs</ToolCommandName>
  <PackAsTool>true</PackAsTool>
  <IsPackable>true</IsPackable>
  <OutputType>Exe</OutputType>
  <TargetFramework>netcoreapp2.0</TargetFramework>
  <Version>1.0.1</Version>
  <Description>Global tool for searching docs.microsoft.com</Description>

  <!-- Workaround only required for early previews of .NET Core tools. Can be removed when .NET Core 2.1 is released. -->    <NETCorePlatformsImplicitPackageVersion>2.0.1</NETCorePlatformsImplicitPackageVersion>
</PropertyGroup>

Package the application using dotnet pack.

dotnet pack --output ./

Tested the installation using the local package.

dotnet install tool -g dotnet-doc --source ./

Ran a few tests; help, searching, etc.

# help
docs -h

# search for 'mvc 5' content (launches default browser)
docs 'mvc 5'

# output to the console
docs '.NET Docker' --console --number 3
Items found: 14687

Introduction to .NET and Docker
https://docs.microsoft.com/en-us/dotnet/core/docker/intro-net-docker

Docker on .NET Framework
https://docs.microsoft.com/en-us/dotnet/framework/docker/

Docker and .NET Core
https://docs.microsoft.com/en-us/dotnet/core/docker/

Cleanup and publish

There is no uninstall, for now you'll need to manually remove the packages from the .dotnet folder as mentioned in Nate's post.

rm -rf $HOME/.dotnet/tools/docs
rm -rf $HOME/.dotnet/toolspkgs/dotnet-doc

Publish the package to Nuget and install officially.

dotnet install tool -g dotnet-doc

Code is available on Github, share, submit issues and PR's welcome!