.NET Core Global Tools for AWS

One of the exciting new features in .NET Core 2.1 are Global Tools. Global Tools provide the ability to distribute command line tools via a NuGet package and install them with the dotnet command line. Before Global Tools were released, .NET Core had the concept of project tools, which were tied to a specific project by referencing the NuGet package in the project file.

To share the deployment features we had for AWS Lambda, AWS Elastic Beanstalk, and Amazon Elastic Container Service (Amazon ECS) from the AWS Toolkit for Visual Studio, we created project tools for each of the services. For example, the same Lambda deployment feature that is available in the AWS Toolkit for Visual Studio can be executed from the command line like this.

dotnet lambda deploy-function ExampleFunction

Now with Global Tools being the new preferred tooling distribution for .NET Core, we have converted our project tools to be Global Tools. One of the biggest benefits this change provides is the ability to use these tools without needing any project source. This makes it easy to use these tools in release pipelines.

Here is a list of the current .NET Core tools offered today.

Versioning

NuGet is the distribution mechanism for both Global Tools and project tools, but a NuGet package cannot support both a Global Tool and a project tool in the same NuGet package. To distinguish which version of these packages is a Global Tool, the version number for each of these packages has been bumped to 3.0.0.0. Versions numbers earlier than 3.0.0.0 are older project tools. We highly recommend that you migrate to the Global Tools version because going forward, that is where we plan to do our development.

Installing Global Tools

To install a Global Tool, use the dotnet command line. Here is an example of installing the Lambda Global Tool.

dotnet tool install -g Amazon.Lambda.Tools

Here is an example of updating to the latest version of the Global Tool.

dotnet tool update -g Amazon.Lambda.Tools

Migrating

To migrate an existing project away from the older project tool, you need to edit your project file and remove the DotNetCliToolReference for the tool package. For example, let’s look at an existing Lambda project file.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
    <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>

    <-- The new property indicating to AWS Toolkit for Visual Studio this is a Lambda project -->
    <AWSProjectType>Lambda</AWSProjectType>
  </PropertyGroup>
  
  <ItemGroup>
    <-- This line needs to be removed -->
    <DotNetCliToolReference Include="Amazon.Lambda.Tools" Version="2.2.0" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Amazon.Lambda.Core" Version="1.0.0" />
    <PackageReference Include="Amazon.Lambda.Serialization.Json" Version="1.3.0" />
  </ItemGroup>
</Project>

To migrate this project, you need to delete the DotNetCliToolReference element, including Amazon.Lambda.Tools. If you don’t remove this line, the older project tool version of Amazon.Lambda.Tools will be used instead of an installed Global Tool.

The AWS Toolkit for Visual Studio before .NET Core 2.1 would look for the presence of Amazon.Lambda.Tools in the project file to determine whether to show the Lambda deployment menu item. Because we knew we were going to switch to Global Tools, and the reference to Amazon.Lambda.Tools in the project was going away, we added the AWSProjectType property to the project file. The current version of the AWS Toolkit for Visual Studio now looks for either the presence of Amazon.Lambda.Tools or the AWSProjectType set to Lambda. Make sure when removing the DotNetCliToolReference that your project file has the AWSProjectType property to continue deploying with the AWS Toolkit for Visual Studio.

Summary

All of these tools are open source and can be found in their GitHub repository. If you have never used these tools, they can be excellent for automating your deployments or working with .NET Core Lambda outside of Visual Studio.