{"id":228304,"date":"2020-02-12T10:19:02","date_gmt":"2020-02-12T18:19:02","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/visualstudio\/?p=228304"},"modified":"2020-11-04T14:29:45","modified_gmt":"2020-11-04T22:29:45","slug":"creating-net-core-global-tools-on-macos","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/visualstudio\/creating-net-core-global-tools-on-macos\/","title":{"rendered":"Creating .NET Core global tools on macOS"},"content":{"rendered":"

One of the really cool aspects about .NET Core is the support for global tools<\/a>. You can use global tools to simplify common tasks during your development workflow. For example, you can create tools to minify image assets, simplify working with source control, or perform any other task that you can automate with the command line. After developing your tool, you can distribute it on NuGet.org<\/a>, or any other NuGet repository, to share the tool with others. Since .NET Core is cross platform, your global tools will also work cross platform, assuming your code doesn\u2019t contain any platform specific code. You can find existing global tools here<\/a>. You can also create local tools, those that are associated with specific projects and not available globally. For more info on local tools see the .NET Core Tools \u2014 local installation<\/em> section in Announcing .NET Core 3.0<\/a>.<\/p>\n

In this post we will discuss how you can create global tools when developing on macOS as well as how to prepare them to distribute using NuGet. Let\u2019s get started with our first global tool. Today, we will be using Visual Studio for Mac, but you can follow similar steps if you are using a different IDE or editor. To ensure you have everything you need to follow this tutorial, download Visual Studio for Mac<\/a>. The code we will be reviewing in this post is available on GitHub, a link is at the end of this post.<\/p>\n

Hello World<\/h2>\n

Let\u2019s create a very basic global tool that will print \u201cHello World\u201d to the user. To create our tool, we will work through the following steps:<\/p>\n

    \n
  1. Create the project<\/li>\n
  2. Modify the project file to make it a global tool<\/li>\n
  3. Implement our code<\/li>\n
  4. Test our new global tool<\/li>\n<\/ol>\n

    The first thing you\u2019ll want to do when creating a global tool is to create a project. Since global tools are console applications, we will use the console project template to get started. After launching Visual Studio for Mac you\u2019ll see the dialog below, click New to begin creating the project. If you already have Visual Studio open, you could also use the \u21e7\u2318N shortcut to open the new project dialog.<\/p>\n

    \"Image<\/p>\n

     <\/p>\n

    From here we will create a .NET Core Console project by going to .NET Core > App > Console Application<\/em>.<\/p>\n

    \"visual<\/p>\n

    After selecting Console Application, click Next to select the version of .NET Core. I have selected .NET Core 3.1. Click Next after selecting that, and then provide the name and location for the project. I have named the project HelloTool.<\/p>\n

     <\/p>\n

    Customize the project for NuGet<\/h2>\n

    Now that we\u2019ve created the project, the first thing to do is to customize the project file to add properties that will make this a global tool. To edit the project file, right click on the project in the Solution Pad and select Tools > Edit File<\/em>. This is demonstrated in the following image.<\/p>\n

    \"visual<\/p>\n

    Note: the menu option to edit the project file is moving to the top level in the context menu as Edit Project File soon.<\/em><\/p>\n

    The .csproj file, an MSBuild file that defines the project, will be opened in the editor. To make the project into a global tool, we must enable the project to be packed into a NuGet package. You can do this by adding a property named PackAsTool<\/em> and setting it to true <\/em>in the .csproj file. If you are planning to publish the package to NuGet.org you will also want to specify some additional properties that NuGet.org will surface to users. You can see the full list of NuGet related properties that can be set over at NuGet metadata properties<\/a>. Let\u2019s look at the properties I typically set when creating a global tool. I\u2019ve pasted the .csproj file below.<\/p>\n

    <Project\u00a0Sdk=\"Microsoft.NET.Sdk\">\r\n\u00a0\u00a0<PropertyGroup>\r\n\u00a0\u00a0\u00a0\u00a0<OutputType>Exe<\/OutputType>\r\n\u00a0\u00a0\u00a0\u00a0<TargetFramework>netcoreapp3.1<\/TargetFramework>\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\r\n\u00a0\u00a0\u00a0\u00a0<!--\u00a0global\u00a0tool\u00a0related\u00a0properties\u00a0-->\r\n\u00a0\u00a0\u00a0\u00a0<PackAsTool>true<\/PackAsTool>\r\n\u00a0\u00a0\u00a0\u00a0<ToolCommandName>hellotool<\/ToolCommandName>\r\n\u00a0\u00a0\u00a0\u00a0<PackageOutputPath>.\/nupkg<\/PackageOutputPath>\r\n\u00a0\u00a0\u00a0\u00a0\r\n\u00a0\u00a0\u00a0\u00a0<!--\u00a0nuget\u00a0related\u00a0properties\u00a0-->\r\n\u00a0\u00a0\u00a0\u00a0<Authors>Sayed\u00a0Ibrahim\u00a0Hashimi<\/Authors>\r\n\u00a0\u00a0\u00a0\u00a0<Description>My\u00a0hello\u00a0world\u00a0global\u00a0tool<\/Description>\r\n\u00a0\u00a0\u00a0\u00a0<Version>1.0.0<\/Version>\r\n\u00a0\u00a0\u00a0\u00a0<Copyright>Copyright\u00a02020\u00a0\u00a9\u00a0Sayed\u00a0Ibrahim\u00a0Hashimi.\u00a0All\u00a0rights\u00a0reserved.<\/Copyright>\r\n\u00a0\u00a0\u00a0\u00a0<PackageLicenseExpression>Apache-2.0<\/PackageLicenseExpression>\r\n\u00a0\u00a0\u00a0\u00a0<RepositoryUrl>https:\/\/github.com\/sayedihashimi\/global-tool-sample<\/RepositoryUrl>\r\n\u00a0\u00a0\u00a0\u00a0<RepositoryType>git<\/RepositoryType>\r\n\u00a0\u00a0\u00a0\u00a0<PackageType>DotNetCliTool<\/PackageType>\r\n\u00a0\u00a0<\/PropertyGroup>\r\n<\/Project><\/pre>\n
    There are two sections of properties that I have added here. Below you\u2019ll find a description of each of these properties.<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
    Property Name<\/strong><\/td>\nDescription<\/strong><\/td>\n<\/tr>\n
    PackAsTool<\/td>\nSet this to true for all global tools, this will enable packing the project into a NuGet package.<\/td>\n<\/tr>\n
    ToolCommandName<\/td>\nOptional name for the tool.<\/td>\n<\/tr>\n
    PackageOutputPath<\/td>\nPath to where the .nupkg file should be placed.<\/td>\n<\/tr>\n
    Authors<\/td>\nName of the author(s) of the project.<\/td>\n<\/tr>\n
    Description<\/td>\nDescription that will be shown in nuget.org and other places.<\/td>\n<\/tr>\n
    Version<\/td>\nVersion of the NuGet package. For each release to nuget.org this must be unique.<\/td>\n<\/tr>\n
    Copyright<\/td>\nCopyright declaration.<\/td>\n<\/tr>\n
    PackageLicenseExpression<\/td>\nAn SPDX license identifier<\/a> or expression.<\/td>\n<\/tr>\n
    RepositoryUrl<\/td>\nSpecifies the URL for the repository where the source code for the package resides and\/or from which it’s being built.<\/td>\n<\/tr>\n
    RepositoryType<\/td>\nRepository type. Examples: git, tfs.<\/td>\n<\/tr>\n
    PackageType<\/td>\nFor tools specify this as DotNetCliTool<\/em>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
     <\/p>\n
    It\u2019s a good idea to specify these properties now, so that you can focus on the code for the global tool. If you\u2019re just creating a tool to play around, or for personal use, I recommend just setting PackAsTool<\/span><\/span><\/span><\/em>,\u00a0<\/span><\/span>ToolCommandName<\/span><\/span><\/span><\/em>\u00a0and\u00a0<\/span><\/span>PackageOutputPath<\/span><\/span><\/span><\/em>. Now let\u2019s take a closer look at the code.<\/p>\n
    In the Program.cs file you\u2019ll find that the following code was added when we created the project.<\/p>\n
    using System;\r\n\r\nnamespace HelloWorld {\r\n    class Program {\r\n        static void Main(string[] args) {\r\n            Console.WriteLine(\"Hello World!\");\r\n       }\r\n    }\r\n}<\/pre>\n
    Since the code is already printing \u201cHello World!\u201d, we can use this as is with no modifications for now. Let\u2019s move on to try executing this as a global tool at the command line. We will first need to package this as a NuGet package.<\/p>\n
    Pack and Test the tool<\/h2>\n
    To create a NuGet package from this project you can use the built in Pack command offered by Visual Studio for Mac. To get there, right-click your project and then select Pack as seen in the next image.<\/p>\n
    \"visual<\/p>\n
    After you invoke the Pack command, the NuGet package (.nupkg file) will be created in the directory we specified in the PackageOutputPath<\/em> property. In our case it will go into a folder named nupkg<\/em> in the project folder. Now that we have created a NuGet package from the project, we will register the global tool and try it from the command line.<\/p>\n
    To install and test the global tool, first open the Terminal app, or your favorite alternative. You\u2019ll want to change directory into the project directory and run the commands from there. You will need to register the package as a tool using the following command.<\/p>\n
    dotnet tool install --global --add-source .\/nupkg HelloTool<\/pre>\n
    Here we are calling dotnet tool<\/em> with the install<\/em> command to install the tool. By passing \u2013global<\/em>, the tool will be available from any folder on your machine. We passed \u2013add-source<\/em> with the location to the folder where the .nupkg file is located so that our new tool can be located and installed. After executing this command, you should see output like the following:<\/p>\n
    You can invoke the tool using the following command: hellotool\r\n\r\nTool 'hellotool' (version '1.0.0') was successfully installed.<\/pre>\n
    Let\u2019s try to invoke the tool with hellotool<\/em> to see if it\u2019s working.<\/p>\n
    \"output<\/p>\n
    If you run into a command not found error, you may need to modify your PATH variable. You should ensure that the full path to ~\/.dotnet\/tools<\/em> is include in the PATH variable. By full path, I mean the ~ should be expanded, for example \/Users\/sayedhashimi\/.dotnet\/tools<\/em> in my case. Now that we have seen how to get started with a tool, let\u2019s do something more interesting by adding some code to the project.<\/p>\n
    Adding parameters using DragonFruit<\/h2>\n
    To make this more realistic we want to add some features like; adding support for parameters, displaying help and more. We could implement all of this directly by using System.CommandLine<\/a>, but the .NET Core team is working on a layer that will simplify it for us called DragonFruit<\/a>. We will use the DragonFruit to help us create this command quickly.<\/p>\n
    Note: DragonFruit is currently an experimental app model for System.CommandLine. This information is subject to change as it is being developed.<\/strong><\/p>\n
    Now we want to add a couple of parameters to the app to make it more realistic. Before we do that, let\u2019s first add the DragonFruit NuGet package to the project and then go from there. To add the NuGet package right click on your app and select Manage NuGet Packages<\/em>.<\/p>\n
    \"visual<\/p>\n
    When the Manage NuGet Packages dialog appears, first check the checkbox to Show pre-release packages<\/em> in the lower left, and the search for System.CommandLine.DragonFruit<\/em>. After that click on the Add Package<\/em> button to add the package to your project. See the following image.<\/p>\n
    \"visual<\/p>\n
    Now that we have added the package, we are ready to add some parameters to the global tool. With DragonFruit it\u2019s really easy to add parameters to your tools, you just declare the parameters as arguments in the main method itself. Let\u2019s add a name and age parameter to this global tool. The updated code for Program.cs is shown below.<\/p>\n
    using System;\r\n\r\nnamespace HelloTool {\r\n\u00a0\u00a0\u00a0 class Program {\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 static void Main(string name = \"World\", int age = 0) {\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 string message = age <= 0 ? $\"Hello there {name}!\" : $\"Hello there {name}, who is {age} years old\";\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Console.WriteLine(message);\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 }\r\n\u00a0\u00a0\u00a0 }\r\n}<\/pre>\n
    In the code above we have added the parameters as arguments in the Main method, and then we craft a new message using those values. Now we want to test that the changes that we have made are working correctly before making further changes. If you want to just run the app you can use Run > Start without Debugging<\/em>, or Run > Start Debugging<\/em> from the menu bar to run it as a vanilla console app. What we want to do is to test it as a .NET Core global tool as well. To do that we will follow the steps below.<\/p>\n
      \n
    1. Pack the project in Visual Studio for Mac<\/li>\n
    2. Uninstall the global tool<\/li>\n
    3. Install the global tool<\/li>\n
    4. Run the tool<\/li>\n<\/ol>\n
      Since we will need to install\/uninstall the tool often, we can simplify that by creating a new Custom Tool in Visual Studio for Mac to facilitate this. To get started go to Tools > Add Custom Tool<\/em>.<\/p>\n
      \"visual<\/p>\n
      This will bring up a new dialog where we can create the two custom tools to handle install\/uninstall. To start, click the Add button and then configure each tool.<\/p>\n
      \"visual<\/p>\n
      We want to create two tools with the following values:<\/p>\n
      Install Tool<\/u><\/p>\n