NuGet pack and restore as MSBuild targets

NuGet 4.0+

With the PackageReference format, NuGet 4.0+ can store all manifest metadata directly within a project file rather than using a separate .nuspec file.

With MSBuild 15.1+, NuGet is also a first-class MSBuild citizen with the pack and restore targets as described below. These targets allow you to work with NuGet as you would with any other MSBuild task or target. For instructions creating a NuGet package using MSBuild, see Create a NuGet package using MSBuild. (For NuGet 3.x and earlier, you use the pack and restore commands through the NuGet CLI instead.)

Target build order

Because pack and restore are MSBuild targets, you can access them to enhance your workflow. For example, let's say you want to copy your package to a network share after packing it. You can do that by adding the following in your project file:

<Target Name="CopyPackage" AfterTargets="Pack">
  <Copy
    SourceFiles="$(OutputPath)..\$(PackageId).$(PackageVersion).nupkg"
    DestinationFolder="\\myshare\packageshare\"
    />
</Target>

Similarly, you can write an MSBuild task, write your own target and consume NuGet properties in the MSBuild task.

pack target

For .NET projects that use the PackageReference format, using msbuild -t:pack draws inputs from the project file to use in creating a NuGet package.

The following table describes the MSBuild properties that can be added to a project file within the first <PropertyGroup> node. You can make these edits easily in Visual Studio 2017 and later by right-clicking the project and selecting Edit {project_name} on the context menu. For convenience, the table is organized by the equivalent property in a .nuspec file.

pack target inputs

pack scenarios

Suppressing dependencies

To suppress package dependencies from generated NuGet package, set SuppressDependenciesWhenPacking to true which will allow skipping all the dependencies from generated nupkg file.

PackageIconUrl

PackageIconUrl is deprecated in favor of the PackageIcon property. Starting with NuGet 5.3 and Visual Studio 2019 version 16.3, pack raises the NU5048 warning if the package metadata only specifies PackageIconUrl.

PackageIcon

Packing an icon image file

When packing an icon image file, use PackageIcon property to specify the icon file path, relative to the root of the package. In addition, make sure that the file is included in the package. Image file size is limited to 1 MB. Supported file formats include JPEG and PNG. We recommend an image resolution of 128x128.

For example:

<PropertyGroup>
    ...
    <PackageIcon>icon.png</PackageIcon>
    ...
</PropertyGroup>

<ItemGroup>
    ...
    <None Include="images\icon.png" Pack="true" PackagePath="\"/>
    ...
</ItemGroup>

Package Icon sample.

For the nuspec equivalent, take a look at nuspec reference for icon.

PackageReadmeFile

Supported with NuGet 5.10.0 preview 2 / .NET SDK 5.0.300 and above

When packing a readme file, you need to use the PackageReadmeFile property to specify the package path, relative to the root of the package. In addition to this, you need to make sure that the file is included in the package. Supported file formats include only Markdown (.md).

For example:

<PropertyGroup>
    ...
    <PackageReadmeFile>readme.md</PackageReadmeFile>
    ...
</PropertyGroup>

<ItemGroup>
    ...
    <None Include="docs\readme.md" Pack="true" PackagePath="\"/>
    ...
</ItemGroup>

For the nuspec equivalent, take a look at nuspec reference for readme.

Output assemblies

nuget pack copies output files with extensions .exe, .dll, .xml, .winmd, .json, and .pri. The output files that are copied depend on what MSBuild provides from the BuiltOutputProjectGroup target.

There are two MSBuild properties that you can use in your project file or command line to control where output assemblies go:

• IncludeBuildOutput: A boolean that determines whether the build output assemblies should be included in the package.
• BuildOutputTargetFolder: Specifies the folder in which the output assemblies should be placed. The output assemblies (and other output files) are copied into their respective framework folders.

Package references

See Package References in Project Files.

Project to project references

Project to project references are considered by default as NuGet package references. For example:

<ProjectReference Include="..\UwpLibrary2\UwpLibrary2.csproj"/>

You can also add the following metadata to your project reference:

<IncludeAssets>
<ExcludeAssets>
<PrivateAssets>

Including content in a package

To include content, add extra metadata to the existing <Content> item. By default everything of type "Content" gets included in the package unless you override with entries like the following:

<Content Include="..\win7-x64\libuv.txt">
 <Pack>false</Pack>
</Content>

By default, everything gets added to the root of the content and contentFiles\any\<target_framework> folder within a package and preserves the relative folder structure, unless you specify a package path:

<Content Include="..\win7-x64\libuv.txt">
  <Pack>true</Pack>
  <PackagePath>content\myfiles\</PackagePath>
</Content>

If you want to copy all your content to only a specific root folder(s) (instead of content and contentFiles both), you can use the MSBuild property ContentTargetFolders, which defaults to "content;contentFiles" but can be set to any other folder names. Note that just specifying "contentFiles" in ContentTargetFolders puts files under contentFiles\any\<target_framework> or contentFiles\<language>\<target_framework> based on buildAction.

PackagePath can be a semicolon-delimited set of target paths. Specifying an empty package path would add the file to the root of the package. For example, the following adds libuv.txt to content\myfiles, content\samples, and the package root:

<Content Include="..\win7-x64\libuv.txt">
  <Pack>true</Pack>
  <PackagePath>content\myfiles;content\sample;;</PackagePath>
</Content>

There is also an MSBuild property $(IncludeContentInPack), which defaults to true. If this is set to false on any project, then the content from that project are not included in the nuget package.

Other pack specific metadata that you can set on any of the above items includes <PackageCopyToOutput> and <PackageFlatten> which sets CopyToOutput and Flatten values on the contentFiles entry in the output nuspec.

IncludeSymbols

When using MSBuild -t:pack -p:IncludeSymbols=true, the corresponding .pdb files are copied along with other output files (.dll, .exe, .winmd, .xml, .json, .pri). Note that setting IncludeSymbols=true creates a regular package and a symbols package.

IncludeSource

This is the same as IncludeSymbols, except that it copies source files along with .pdb files as well. All files of type Compile are copied over to src\<ProjectName>\ preserving the relative path folder structure in the resulting package. The same also happens for source files of any ProjectReference which has TreatAsPackageReference set to false.

If a file of type Compile, is outside the project folder, then it's just added to src\<ProjectName>\.

Packing a license expression or a license file

When using a license expression, use the PackageLicenseExpression property. For a sample, see License expression sample.

<PropertyGroup>
    <PackageLicenseExpression>MIT</PackageLicenseExpression>
</PropertyGroup>

To learn more about license expressions and licenses that are accepted by NuGet.org, see license metadata.

When packing a license file, use PackageLicenseFile property to specify the package path, relative to the root of the package. In addition, make sure that the file is included in the package. For example:

<PropertyGroup>
    <PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
</PropertyGroup>

<ItemGroup>
    <None Include="licenses\LICENSE.txt" Pack="true" PackagePath=""/>
</ItemGroup>

For a sample, see License file sample.

Packing a file without an extension

In some scenarios, like when packing a license file, you might want to include a file without an extension. For historical reasons, NuGet & MSBuild treat paths without an extension as directories.

  <PropertyGroup>
    <TargetFrameworks>netstandard2.0</TargetFrameworks>
    <PackageLicenseFile>LICENSE</PackageLicenseFile>
  </PropertyGroup>

  <ItemGroup>
    <None Include="LICENSE" Pack="true" PackagePath=""/>
  </ItemGroup>  

File without an extension sample.

IsTool

When using MSBuild -t:pack -p:IsTool=true, all output files, as specified in the Output Assemblies scenario, are copied to the tools folder instead of the lib folder. Note that this is different from a DotNetCliTool which is specified by setting the PackageType in .csproj file.

Packing using a .nuspec file

Although it is recommended that you include all the properties that are usually in the .nuspec file in the project file instead, you can choose to use a .nuspec file to pack your project. For a non-SDK-style project that uses PackageReference, you must import NuGet.Build.Tasks.Pack.targets so that the pack task can be executed. You still need to restore the project before you can pack a nuspec file. (An SDK-style project includes the pack targets by default.)

The target framework of the project file is irrelevant and not used when packing a nuspec. The following three MSBuild properties are relevant to packing using a .nuspec:

1. NuspecFile: relative or absolute path to the .nuspec file being used for packing.
2. NuspecProperties: a semicolon-separated list of key=value pairs. Due to the way MSBuild command-line parsing works, multiple properties must be specified as follows: -p:NuspecProperties="key1=value1;key2=value2".
3. NuspecBasePath: Base path for the .nuspec file.

If using dotnet.exe to pack your project, use a command like the following:

dotnet pack <path to .csproj file> -p:NuspecFile=<path to nuspec file> -p:NuspecProperties=<> -p:NuspecBasePath=<Base path> 

If using MSBuild to pack your project, use a command like the following:

msbuild -t:pack <path to .csproj file> -p:NuspecFile=<path to nuspec file> -p:NuspecProperties=<> -p:NuspecBasePath=<Base path> 

Please note that packing a nuspec using dotnet.exe or msbuild also leads to building the project by default. This can be avoided by passing --no-build property to dotnet.exe, which is the equivalent of setting <NoBuild>true</NoBuild> in your project file, along with setting <IncludeBuildOutput>false</IncludeBuildOutput> in the project file.

An example of a .csproj file to pack a nuspec file is:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <NoBuild>true</NoBuild>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <NuspecFile>PATH_TO_NUSPEC_FILE</NuspecFile>
    <NuspecProperties>add nuspec properties here</NuspecProperties>
    <NuspecBasePath>optional to provide</NuspecBasePath>
  </PropertyGroup>
</Project>

Advanced extension points to create customized package

The pack target provides two extension points that run in the inner, target framework specific build. The extension points support including target framework specific content and assemblies into a package:

• TargetsForTfmSpecificBuildOutput target: Use for files inside the lib folder or a folder specified using BuildOutputTargetFolder.
• TargetsForTfmSpecificContentInPackage target: Use for files outside the BuildOutputTargetFolder.

TargetsForTfmSpecificBuildOutput

Write a custom target and specify it as the value of the $(TargetsForTfmSpecificBuildOutput) property. For any files that need to go into the BuildOutputTargetFolder (lib by default), the target should write those files into the ItemGroup BuildOutputInPackage and set the following two metadata values:

• FinalOutputPath: The absolute path of the file; if not provided, the Identity is used to evaluate source path.
• TargetPath: (Optional) Set when the file needs to go into a subfolder within lib\<TargetFramework> , like satellite assemblies that go under their respective culture folders. Defaults to the name of the file.

Example:

<PropertyGroup>
  <TargetsForTfmSpecificBuildOutput>$(TargetsForTfmSpecificBuildOutput);GetMyPackageFiles</TargetsForTfmSpecificBuildOutput>
</PropertyGroup>

<Target Name="GetMyPackageFiles">
  <ItemGroup>
    <BuildOutputInPackage Include="$(OutputPath)cs\$(AssemblyName).resources.dll">
        <TargetPath>cs</TargetPath>
    </BuildOutputInPackage>
  </ItemGroup>
</Target>

TargetsForTfmSpecificContentInPackage

Write a custom target and specify it as the value of the $(TargetsForTfmSpecificContentInPackage) property. For any files to include in the package, the target should write those files into the ItemGroup TfmSpecificPackageFile and set the following optional metadata:

• PackagePath: Path where the file should be output in the package. NuGet issues a warning if more than one file is added to the same package path.
• BuildAction: The build action to assign to the file, required only if the package path is in the contentFiles folder. Defaults to "None".

An example:

<PropertyGroup>
  <TargetsForTfmSpecificContentInPackage>$(TargetsForTfmSpecificContentInPackage);CustomContentTarget</TargetsForTfmSpecificContentInPackage>
</PropertyGroup>

<Target Name="CustomContentTarget">
  <ItemGroup>
    <TfmSpecificPackageFile Include="abc.txt">
      <PackagePath>mycontent/$(TargetFramework)</PackagePath>
    </TfmSpecificPackageFile>
    <TfmSpecificPackageFile Include="Extensions/ext.txt" Condition="'$(TargetFramework)' == 'net46'">
      <PackagePath>net46content</PackagePath>
    </TfmSpecificPackageFile>  
  </ItemGroup>
</Target>  

restore target

MSBuild -t:restore (which nuget restore and dotnet restore use with .NET Core projects), restores packages referenced in the project file as follows:

1. Read all project to project references
2. Read the project properties to find the intermediate folder and target frameworks
3. Pass MSBuild data to NuGet.Build.Tasks.dll
4. Run restore
5. Download packages
6. Write assets file, targets, and props

The restore target works for projects using the PackageReference format. MSBuild 16.5+ also has opt-in support for the packages.config format.

Restore properties

Additional restore settings may come from MSBuild properties in the project file. Values can also be set from the command line using the -p: switch (see Examples below).

The ExcludeRestorePackageImports property is an internal property used by NuGet. It should not be modified or set in any MSBuild files.

Examples

Command line:

msbuild -t:restore -p:RestoreConfigFile=<path>

Project file:

<PropertyGroup>
    <RestoreIgnoreFailedSources>true</RestoreIgnoreFailedSources>
</PropertyGroup>

Restore outputs

Restore creates the following files in the build obj folder:

Restoring and building with one MSBuild command

Due to the fact that NuGet can restore packages that bring down MSBuild targets and props, the restore and build evaluations are run with different global properties. This means that the following will have an unpredictable and often incorrect behavior.

msbuild -t:restore,build

Instead the recommended approach is:

msbuild -t:build -restore

The same logic applies to other targets similar to build.

Restoring PackageReference and packages.config projects with MSBuild

With MSBuild 16.5+, packages.config are also supported for msbuild -t:restore.

msbuild -t:restore -p:RestorePackagesConfig=true

Restoring with MSBuild static graph evaluation

msbuild -t:restore -p:RestoreUseStaticGraphEvaluation=true

Alternatively you can enable it by setting the property in a Directory.Build.Props.

<Project>
  <PropertyGroup>
    <RestoreUseStaticGraphEvaluation>true</RestoreUseStaticGraphEvaluation>
  </PropertyGroup>
</Project>

Static graph restore changes the msbuild part of restore, the project reading and evaluation, but not the restore algorithm! The restore algorithm is the same across all NuGet tools (NuGet.exe, MSBuild.exe, dotnet.exe and Visual Studio).

In very few scenarios, static graph restore may behave differently from current restore and certain declared PackageReferences or ProjectReferences might be missing.

To ease your mind, as a one time check, when migrating to static graph restore, consider running:

msbuild.exe -t:restore -p:RestoreUseStaticGraphEvaluation=true
msbuild.exe -t:restore

NuGet should not report any changes. If you do see a discrepancy, please file an issue at NuGet/Home.

Replacing one library from a restore graph

If a restore is bringing the wrong assembly, it's possible to exclude that packages default choice, and replace it with your own choice. First with a top level PackageReference, exclude all assets:

<PackageReference Include="Newtonsoft.Json" Version="9.0.1">
  <ExcludeAssets>All</ExcludeAssets>
</PackageReference>

Next, add your own reference to the appropriate local copy of the DLL:

<Reference Include="Newtonsoft.Json.dll" />