Click here to Skip to main content
14,774,647 members
Articles » Platforms, Frameworks & Libraries » .NET Framework » How To
Tip/Trick
Posted 9 Jul 2020

Stats

4.1K views
6 bookmarked

How to Create a NuGet Package that Runs your Console App as an MSBuild Task

Rate me:
Please Sign up or sign in to vote.
4.75/5 (3 votes)
9 Jul 2020CPOL
Tutorial using the Build Task NuGet Package Template with GitHub or `dotnet new`
By following this article, you will learn how to create NuGet Packages that utilize MSBuild ExecTask to run your Before or After specific Build Targets. This article (and the templates) only address C#, but can easily be applied to any .NET language because the important bits are language agnostic. The templates are written for .NET Core 3.1, but can easily be adapted to legacy .NET Frameworks or .NET 5. This is the same method used by NuGetDefense.

Introduction

The Build Task NuGet Package Template sets up a cross-platform msbuild task that runs at build.

Background

I started looking for a way to run a task at build when I started work on NuGetDefense. I needed to run a console app and emit warnings/errors to MSBuild as part of the Build. I found several articles detailing the pitfalls of trying to write a cross-platform task and settled instead on an MSBuild ExecTask run using a nuget Targets file.

Using the Code

Using the repository is as simple as installing the template and then writing your app.

dotnet new --install BuildTaskNuGetPackage.Template::*
dotnet new nugetbuildtask -n ProjectName -A "FirstName LastName" 

OR:

If you prefer to use GitHub, you can start with the template repository.

  1. Click the Use This Template button
  2. Fill out the page including your repository name. DO NOT check the Include all branches this would include the branch used to create the dotnet new template as well.

Regardless of which method you use, you will need to write your console app and update the nuspec to include any dependencies that are needed for your app to run.

This is how the files are included for NuGetDefense.

<files>
   <!-- <file src="Src/bin/Release/net461/NuGetDefense.exe"
              target="tools/net461/NuGetDefense.exe" /> -->
   <file src="build/nugetdefense.targets" target="build/nugetdefense.targets" />
   <file src="bin/Release/netcoreapp3.1/NuGetDefense.deps.json"
         target="tools/netcoreapp3.1/NuGetDefense.deps.json" />
   <file src="bin/Release/netcoreapp3.1/NuGetDefense.dll"
         target="tools/netcoreapp3.1/NuGetDefense.dll" />
   <file src="bin/Release/netcoreapp3.1/NuGetDefense.Core.dll"
         target="tools/netcoreapp3.1/NuGetDefense.Core.dll" />
   <file src="bin/Release/netcoreapp3.1/NuGetDefense.NVD.dll"
         target="tools/netcoreapp3.1/NuGetDefense.NVD.dll" />
   <file src="bin/Release/netcoreapp3.1/NuGetDefense.OSSIndex.dll"
         target="tools/netcoreapp3.1/NuGetDefense.OSSIndex.dll" />
   <file src="bin/Release/netcoreapp3.1/NuGetDefense.runtimeconfig.json"
         target="tools/netcoreapp3.1/NuGetDefense.runtimeconfig.json" />
   <file src="bin/Release/netcoreapp3.1/MessagePack.dll"
         target="tools/netcoreapp3.1/MessagePack.dll" />
   <file src="bin/Release/netcoreapp3.1/MessagePack.Annotations.dll"
         target="tools/netcoreapp3.1/MessagePack.Annotations.dll" />
   <file src="bin/Release/netcoreapp3.1/Microsoft.Bcl.AsyncInterfaces.dll"
         target="tools/netcoreapp3.1/Microsoft.Bcl.AsyncInterfaces.dll" />
   <file src="bin/Release/netcoreapp3.1/NuGet.Versioning.dll"
         target="tools/netcoreapp3.1/NuGet.Versioning.dll" />
   <file src="bin/Release/netcoreapp3.1/System.Text.Json.dll"
         target="tools/netcoreapp3.1/System.Text.Json.dll" />
   <file src="bin/Release/netcoreapp3.1/VulnerabilityData.bin"
         target="tools/netcoreapp3.1/VulnerabilityData.bin" />
   <file src="lib/net461/_._" target="lib/net461/_._" />
   <file src="lib/netcoreapp3.1/_._" target="lib/netcoreapp3.1/_._" />
   <file src="lib/netstandard2.0/_._" target="lib/netstandard2.0/_._" />
 </files>

The Hard Way

So you want to do it the hard way? Maybe you like a challenge or want a deeper understanding of the code you're using.

Get the Console App

This should be fairly basic. You can use Visual Studio or the dotnet cli to create a new console app or use one that already exists. For the sake of this tutorial, I'm going to assume it's written in .NET Core 3.1 (so it is cross-platform) but with a few tweaks, you can use anything. Make sure to build the project so you have a list of all the files and dependencies required to run the app.

Create the Nuspec

The .nuspec file is the file that tells nuget how to put the package together. You can review the documentation for this file to see more of what it can do but we are only going to look at a few of the potential fields.

Create the file `yourProjectName.nuspec` somewhere in your repository. I generally put it right beside the project file, but you could potentially have it anywhere in your project/solution. Edit the contents to match the following:

<?xml version="1.0"?>
<package>
  <metadata>
    <id>mybuildtask</id>
    <title>MyBuildTask</title>
    <version>0.0.0.1</version>
    <authors>Owner Name(s)</authors>
    <owners>Owner Name(s)</owners>
    <requireLicenseAcceptance>true</requireLicenseAcceptance>
    <description>A Description of my Package</description>
    <license type="expression">MIT</license>
  </metadata>
</package>

You will want to replace the appropriate fields with values that match your project/organization. And you will want to keep the id as a lowercase value (some NuGet sources may be case-sensitive) to avoid edge-case issues.

Now you need to look at the bin/Release/ folder and decide which files need to be included. Typically, this will be every item in that folder. Once you have a list, Add them to a files collection at the bottom of the Nuspec:

<?xml version="1.0"?>
<package>
  <metadata>
    <id>mybuildtask</id>
    <title>MyBuildTask</title>
    <version>0.0.0.1</version>
    <authors>Owner Name(s)</authors>
    <owners>Owner Name(s)</owners>
    <requireLicenseAcceptance>true</requireLicenseAcceptance>
    <description>A Description of my Package</description>
    <license type="expression">MIT</license>
  </metadata>
  <files>
    <file src="build/MyBuildTask.targets" target="build/MyBuildTask.targets" />
    <file src="bin/Release/netcoreapp3.1/MyBuildTask.dll" 
          target="tools/netcoreapp3.1/MyBuildTask.dll" />
  </files>
</package>

Each <file> element describes a file that you want to include in the package. src is path to the file relative to the directory that contains the project file. target is the location in the package that the files wil end up in. All files that are part of the console app should be placed in the tools directory to ensure they are not referenced in the project that installs this package (could cause numerous issues).

Dig into the Project File

We want this to build itself, then pack itself, but only when we are not trying to debug it. As it stands, trying to run `dotnet pack` on this will fail if the project is built in any configuration other than Release. And on top of that, having to drop to a console after using a hotkey to build is absurd when we can trigger the pack automatically.

Add these two lines to your project file (in the same propertygroup that defines your target frameworks) to automatically pack the nuget package when built in Release.

<GeneratePackageOnBuild Condition="'$(Configuration)'=='RELEASE'">true</GeneratePackageOnBuild>
<NuspecFile>MyBuildTask.nuspec</NuspecFile>

Note: Many articles reference Replace Tokens to work around the configuration issue, but I've found that .NET Core on Linux replaces $Configuration$ with an empty string. If you working with Legacy .NET applications, or if this is fixed at a later date, you may wish to utilize that feature.

Create the Targets File and Add to the Nuspec

Create a directory name `build` and in this directory, create a file named `yourprojectname.targets`. It should look something like this:

<Project>
  <PropertyGroup>
    <MyBuildTaskExe Condition="'$(OS)' == Unix">
    dotnet "$(MSBuildThisFileDirectory)../tools/netcoreapp3.1/MyBuildTask.dll"
    </MyBuildTaskExe>
    <MyBuildTaskExe Condition="'$(OS)' == 'Windows_NT'">
    dotnet "$(MSBuildThisFileDirectory)..\tools\netcoreapp3.1\MyBuildTask.dll"
    </MyBuildTaskExe>
  </PropertyGroup>
  
  <Target Name="MyBuildTask" AfterTargets="Build">
    <Exec Command="$(MyBuildTaskExe) &quot;$(MSBuildProjectFullPath)&quot; 
     $(TargetFramework)" IgnoreExitCode="false" />
  </Target>
</Project>
  • MyBuildTaskExe is defined based on the OS (because the path separators cause a problem otherwise). Defines command we are going to run with the ExecTask (without the arguments)
  • MSBuildThisFileDirectory is the full path to the targets file.
  • MSBuildProjectFullPath is the path to the project file and can be used to find the directory and/or files for the build. It does not wrap itself in doube-quotes (so we wrap it with &quot;)
  • AfterTargets could be replaced with BeforeTargets and is used to determine when to run the task.

Points of Interest

Additional Resources

History

  • 9th July, 2020 - Initial publication

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

CodingCoyote
Software Developer Tech Friends Inc.
United States United States
Software Developer specializing in Build/Test Automation. Adept Linux User and Cross Platform Developer.

Comments and Discussions

 
QuestionThank you! Pin
honey the codewitch9-Jul-20 12:51
mvahoney the codewitch9-Jul-20 12:51 
AnswerRe: Thank you! Pin
CodingCoyote9-Jul-20 13:14
professionalCodingCoyote9-Jul-20 13:14 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.