Edit in GitHub or Give Feedback

Nuspec Reference

Page generated on 9/25/2016

A .nuspec file is a manifest that uses XML to describe a package. NuGet uses the manifest to build a package and then stores it in the package after the package is built. For information about how to build a package, see the Creating a Package page.

At the minimum, you need the following elements in in the metadata of your .nuspec file.

Element Description
id

The unique identifier for the package. This is the package name that is shown when packages are listed using the Package Manager Console. These are also used when installing a package using the Install-Package command within the Package Manager Console. Package IDs may not contain any spaces or characters that are invalid in an URL. In general, they follow the same rules as .NET namespaces do. So Foo.Bar is a valid ID, Foo! and Foo Bar are not.

Package IDs are treating as case-insensitive strings. NuGet.Core is considered equivalent to nuget.core. However, for display purposes, the original case in the .nuspec is used.

version The version of the package, in a format like 1.2.3.
title The human-friendly title of the package displayed in the NuGet.org Gallery and older versions of the Manage NuGet Packages dialog in Visual Studio. If no title is specified, the ID is used instead.
authors A comma-separated list of authors of the package code.
description A long description of the package. This shows up in the right pane of the Add Package dialog as well as in the Package Manager Console when listing packages using the Get-Package command.
owners A comma-separated list of the package creators. This is often the same list as in authors. This is ignored when uploading the package to the NuGet.org Gallery.

However, for you package to work great and provide enough contextual information to you consumers, you should consider filling in the rest of the elements in the following list.

Element Description
releaseNotes v1.5 A description of the changes made in each release of the package. This field only shows up when the Updates tab is selected and the package is an update to a previously installed package. It is displayed where the Description would normally be displayed.
summary A short description of the package. If specified, this shows up in the middle pane of the Add Package Dialog. If not specified, a truncated version of the description is used instead.
language The locale ID for the package, such as en-us.
projectUrl A URL for the home page of the package.
iconUrl A URL for the image to use as the icon for the package in the Manage NuGet Packages dialog box. This should be a 64x64-pixel .png file that has a transparent background.
licenseUrl A link to the license that the package is under.
copyright v1.5 Copyright details for the package.
requireLicenseAcceptance A boolean value that specifies whether the client needs to ensure that the package license (described by licenseUrl) is accepted before the package is installed.
dependencies The list of dependencies for the package. For more information, see Specifying Dependencies later in this document.
references v1.5 Names of assemblies under lib that are added as project references. If unspecified, all references in lib are added as project references. When specifying a reference, only specify the name and not the path inside the package.
frameworkAssemblies v1.2 The list of .NET Framework assembly references that this package requires. These are references to assemblies that exist in the .NET Framework and thus should already be in the GAC for any machine. Specifying framework assembly references ensures these references are added when installing the package.
tags A space-delimited list of tags and keywords that describe the package. This information is used to help make sure users can find the package using searches in the Add Package Reference dialog box or filtering in the Package Manager Console window.
developmentDependency v2.8 A Boolean value that specifies whether the package will be marked as a development-only dependency in the packages.config. This will cause the package to be excluded from the dependency list when the referencing project itself is later packaged.
contentFiles v3.3A collection of files that should be referenced in the consuming project. These files can be specified with a set of attributes that instruct the project system how they should be used in the project.
minClientVersion v2.5 Specifies the minimum version of the NuGet client that can install this package. This requirement is enforced by both the NuGet Visual Studio extension and nuget.exe program.
packageTypes v3.5 Specifies the type of the package. This is important if the package is something other than a traditional dependency package. For more information, see the package type documentation.

Replacement Tokens

When you create a package from a project file, replacement tokens might appear as values within the Metadata section of the .nuspec file.

For example, when you use the following command:

nuget pack MyProject.csproj

The myproject.nuspec file adjacent to the myproject.csproj file may contain the following replacement tokens which are populated by the values within the project. The file may also contain other replacement tokens that will be specified using the nuget pack -Properties feature.

TokenSource
$id$ The Assembly name
$version$ The assembly version as specified in the assembly's AssemblyVersionAttribute. If the assembly's AssemblyInformationalVersionAttribute is specified, that one is used instead.
$author$ The company as specified in the AssemblyCompanyAttribute.
$description$ The description as specified in the AssemblyDescriptionAttribute.
$references$ This element contains a set of reference elements, each of which specifies an assembly that will be referenced by the project. The existence of this element overrides the convention of pulling everything in the lib folder. More info below.

In addition to using replacement tokens to modify the metadata of the package, you an also use the tokens to resolve paths when you include files in the package. When you build the package by using MSBuild, the properties defined for the build propagate through to the package build as values for replacement tokens. They will have the same names as the properties in MSBuild, which makes it possible to select files to be included depending on the current build configuration. For instance:

<files>
    <file src="bin\$configuration$\$id$.pdb" target="lib\net40\" />
</files>

Assuming you are building the project that produces an assembly called Foo in release mode this will produce the following transformed xml:

<files>
    <file src="bin\Release\Foo.pdb" target="lib\net40" />
</files>

Dependencies

Package Dependencies

The dependencies element is a child element of the metadata element and contains a set of dependency elements. Each dependency element is a reference to another package that this package depends on.

<dependencies>
  <dependency id="RouteMagic" version="1.1.0" />
  <dependency id="RouteDebugger" version="1.0.0" />
</dependencies>

The following table lists attributes of the dependency element.

AttributeDescription
id The package id of the package that this package is dependent upon. The package specified by the dependency id is required by this package and NuGet will install it when installing the current package.
version The range of versions acceptable as a dependency. Typically this is just a version number which represents a minimum version. However a more explicit version range syntax is supported.

Specifying Dependencies in version 2.0 and above

Starting from version 2.0, package dependencies can be specified to vary according to the framework profile of the target project. The dependencies element contains a set of group elements. Each group contains zero or more dependency element and a target framework attribute. All dependencies inside a group are installed together if the target framework is compatible with the project's framework profile.

<dependencies> 
   <group>
      <dependency id="RouteMagic" version="1.1.0" />
   </group>

   <group targetFramework="net40">
      <dependency id="jQuery" />
      <dependency id="WebActivator" />
   </group>

   <group targetFramework="sl30">
   </group>
</dependencies>

The following table lists the attributes of a group element.

AttributeDescription
targetFramework Optional. The target framework of the group. If not set, the group acts as a fallback group, which behaves exactly as before version 2.0

The dependency element is the same as described in previous section.

A package can specify package dependencies in either two formats: either with a flat list of dependency as in pre-2.0, or in groups. However, mixing the two formats is disallowed. For example, the following snippet is invalid and will be rejected by NuGet.

<dependencies> 
   <dependency id="jQuery" />
   <dependency id="WebActivator" />

   <group>
      <dependency id="RouteMagic" version="1.1.0" />
   </group>
</dependencies>

Specifying Explicit Assembly References

Use the <references /> element to explicitly specify assemblies that the target project should reference.

For example, if you add the following:

<references>
  <reference file="xunit.dll" />
  <reference file="xunit.extensions.dll" />
</references>

Then only the xunit.dll and xunit.extensions.dll will be referenced from the appropriate framework/profile subdirectory of the lib folder even if there are other assemblies in the folder.

If this element is omitted or the <references/> element is empty, then the usual behavior applies, which is to reference every assembly in the lib folder.

What is this feature used for?

This feature supports design-time only assemblies. For example, when using Code Contracts, the contract assemblies need to be next to the runtime assemblies that they augment so that Visual Studio can find them, but the contract assemblies should not actually be referenced by the project and should not be copied into the bin folder.

Likewise, the feature can be used to for unit test frameworks such as XUnit which need its tools assemblies to be located next to the runtime assemblies, but excluded from project references.

Specifying Explicit Assembly References in version 2.5 and above

Starting from version 2.5, package assembly references can be specified to vary according to the framework profile of the target project. The references element contains a set of group elements. Each group contains zero or more reference element and a target framework attribute. All references inside a group are installed together if the target framework is compatible with the project's framework profile.

<references> 
  <group targetFramework="net45"> 
      <reference file="a.dll" />
  </group> 
  <group targetFramework="netcore45"> 
    <reference file="b.dll" /> 
  </group>
  <group>
    <reference file="c.dll" />
  </group>
</references>

The following table lists the attributes of a group element.

AttributeDescription
targetFramework Optional. The target framework of the group. If not set, the group acts as a fallback group, which behaves exactly as before version 2.5.

The reference element is the same as described in previous section.

A package can specify package references in either two formats: either with a flat list of reference as in pre-2.5, or in groups. However, mixing the two formats is disallowed. For example, the following snippet is invalid and will be rejected by NuGet.

<references>
  <reference file="xunit.dll" />
  <reference file="xunit.extensions.dll" />
  <group>
    <reference file="c.dll" />
  </group>
</references>

Specifying Framework Assembly References GAC

In some cases, a package may depend on an assembly that's in the .NET Framework. Strictly speaking, it's not always necessary that the consumer of your package reference the framework assembly. But in some cases, it is important, such as when the developer needs to code against types in that assembly in order to use your package. The frameworkAssemblies element, a child element of the metadata element, allows you to specify a set of frameworkAssembly elements pointing to a Framework assembly in the GAC. Note the emphasis on Framework assembly. These assemblies are not included in your package as they are assumed to be on every machine as part of the .NET Framework.

<frameworkAssemblies>
  <frameworkAssembly assemblyName="System.ServiceModel" targetFramework="net40" />
  <frameworkAssembly assemblyName="System.SomethingElse"  />
</frameworkAssemblies>

The following table lists attributes of the frameworkAssembly element.

Attribute Description
assemblyName Required. The fully qualified assembly name.
targetFramework Optional. If specified, the specific target framework that this reference applies to. For example, if reference only applies to .NET 4, then the value should be "net40". If the reference applies to *all* frameworks, then omit this attribute.

Specifying Files to Include in the Package

If you follow the conventions described in Creating a Package, you do not have to explicitly specify a list of files in the .nuspec file. Note that if you specify any files, the conventions are ignored and only the files listed in the .nuspec file are included in the package.

The files element is an optional child element of the package element and contains a set of file elements. Each file element specifies the source and destination of a file to include in the package via the src attribute and target attribute respectively.

Element Description
src The location of the file or files to include. The path is relative to the NuSpec file unless an absolute path is specified. The wildcard character, *, is allowed. Using a double wildcard, **, implies a recursive directory search.
target This is a relative path to the directory within the package where the source files will be placed. The relative path should begin with 'lib', 'content' or 'tools'.
exclude The file or files to exclude. This is usually combined with a wildcard value in the src attribute. The exclude attribute can contain a semi-colon delimited list of files or a file pattern. Using a double wildcard, **, implies a recursive exclude pattern.

The following is an example of a files element.

<files>
  <file src="bin\Debug\*.dll" target="lib" /> 
  <file src="bin\Debug\*.pdb" target="lib" /> 
  <file src="tools\**\*.*" exclude="**\*.log" />
</files>

NuGet does not add references to any dlls that end with '.resources.dll'. Please refer to the following Codeplex discussion: http://nuget.codeplex.com/discussions/280566

File Element Examples

Let's look at some example usages of this element to gain a better understanding of how it's used.

Single Assembly

Copies a single assembly in the same folder as the NuSpec file into the package's lib folder.

Source Contains: foo.dll

<file src="foo.dll" target="lib" />

Packaged Result: lib\foo.dll

Single Assembly In a deep path

Copies a single assembly into the package's lib\net40 folder so that it only applies to projects targeting the .NET 4 framework.

Source Contains: foo.dll

<file src="assemblies\net40\foo.dll" target="lib\net40" />

Packaged Result: lib\net40\foo.dll

Set Of DLLs

Copies a set of assemblies within the bin\release folder into the package's lib folder.

Source contains:

  • bin\release\MyLib.dll
  • bin\release\CoolLib.dll

NuSpec File Element

<file src="bin\release\*.dll" target="lib" />

Packaged Result * lib\Mylib.dll * lib\coollib.dll

DLLs for different frameworks

Source contains:

  • lib\net40\foo.dll
  • lib\net20\foo.dll

NuSpec File Element:

<file src="lib\**" target="lib" />

Packaged Result:

  • lib\net40\foo.dll
  • lib\net20\foo.dll

Note: The double wildcard implies a recursive search in the source for matching files.

Content Files

Caution:
These instructions define a technique used in pre-3.0 versions of NuGet that include files in a package. Newer project systems will not add or manage these files in your project. NuGet recommends the newer contentFiles notation, described below.

Source Contains:

  • css\mobile\style1.css
  • css\mobile\style2.css

NuSpec File Element:

<file src="css\mobile\*.css" target="content\css\mobile" />

Packaged Result:

  • content\css\mobile\style1.css
  • content\css\mobile\style2.css

Content files with directory structure

Source Contains:

  • css\mobile\style.css
  • css\mobile\wp7\style.css
  • css\browser\style.css

NuSpec file element

<file src="css\**\*.css" target="content\css" />

Packaged Result:

  • content\css\mobile\style.css
  • content\css\mobile\wp7\style.css
  • content\css\browser\style.css

Content File with deep path

Source Contains: css\cool\style.css

<file src="css\cool\style.css" target="Content" />

Packaged Result: content\style.css

Content File copied to Folder with dot in name

<file src="images\Neatpic.png" target="Content\images\foo.bar" />

Packaged Result: content\images\foo.bar\neatpick.png

Note: Because the target "extension" doesn't match the src extension, NuGet treats it as a directory.

Content files without extensions

To make sure extensionless files are captured by wildcard match use ** or *

Source Contains: flags\installed

<file src="flags\**" target="flags" />

Packaged Result: flags\installed

Content file with deep path and deep target

<file src="css\cool\style.css" target="Content\css\cool" />

Packaged Result: content\css\cool\style.css

Note: This also works:

<file src="css\cool\style.css" target="Content\css\cool\style.css" />

In this case, because the file extensions of the source and target match, it's assumed that the target is not a directory but is the file name.

Content file copy and rename

<file src="ie\css\style.css" target="Content\css\ie.css" />

Packaged Result: content\css\ie.css

Excluding files in the NuSpec

The file element within a NuSpec file can be used to include a specific file or a set of files using a wildcard. When using a wildcard, there's no way to exclude a specific subset of the included files. For example, suppose you want all text files within a directory except a specific one.

<files>
    <file src="docs\*.txt" target="content\docs" exclude="docs\admin.txt" />
</files>

Use semicolons to specify multiple files.

<files>
    <file src="*.txt" target="content\docs" exclude="admin.txt;log.txt" />
</files>

Use a wildcard to exclude a set of files such as all backup files.

<files>
    <file src="tools\*.*" target="tools" exclude="tools\*.bak" />
</files>

Or use a double wildcard to exclude a set of files recursively across directories.

<files>
    <file src="tools\**\*.*" target="tools" exclude="**\*.log" />
</files>

ContentFiles with Visual Studio 2015 Update 1 and later

In order to provide a better experience and clearer definition of what files should be `` in a project, the new contentFiles element has been introduced to the nuspec. These files are designed to be immutable, and should not be modified by developers who install the package. This feature only applies to projects that are managed by project.json configuration files.

The contentFiles element contains a collection of files elements that define a mask of files and how those files should be references by a project. The files elements reference a location inside of the NuGet package whose content could be placed there by either packaging the files directly on disk or by using a files element as demonstrated above.

Files child-elements of contentFiles in the nuspec are applied from top to bottom, with the topmost elements taking precedence over lower elements in the collection. These elements apply to entries in the contentFiles folder of the package. Type of content that work very well in this model include:

  • Images that are embedded as resources
  • Source files that are compiled
  • PP files that are transformed to match the project they are included in
  • Directories of scripts that need to be copied to the output directory with the same folder structure.

Content shall be stored in the package in folders that match this pattern:

/contentFiles/{codeLanguage}/{TxM}/{any?}
  • codeLanguages may be cs, fs, vb, any or the lowercase equivalent of a given $(ProjectLanguage)
  • TxM is any legal target framework moniker that NuGet supports
  • Any folder structure may be appended to the end of this syntax.

Examples of legal folder locations include:

Language and framework agnostic: /coNtentFiles/any/any/config.xml net45 content for all languages: /coNtentFiles/any/net45/config.xml CSharp specific content for net45 and up: /coNtentFiles/cs/net45/sample.cs

Empty folders can use . to opt out of providing content for certain combinations of language and TxM:

/contentFiles/vb/any/code.vb
/contentFiles/cs/any/_._

NuSpec contentFiles or files attributes

AttributeDescription
include [Required attribute] Include provides either a file path or a wild card path. All matching files from the contentFiles folder will have the attributes for that files node applied. Examples: **/*, **/*.cs, any/any/myfile.txt, **/net*/*.
exclude Exclude provides either a file path or a wild card path. All matching files will be excluded from the include.
buildAction Build action taken by msbuild for the content items. Examples: None, Compile
copyToOutput If True the content items will be copied to the build output folder
flatten If False the content items will be copied to the build output folder using the full folder structure from the nupkg. This path will be relative to the TxM folder. Example: cs/net45/config/data.xml -> config/data.xml

Attributes Defaults

Attribute Value
buildAction Compile
copyToOutput False
flatten False

Example contentFiles section

<contentFiles>
    <!-- Embed image resources -->
    <files include="any/any/images/dnf.png" buildAction="EmbeddedResource" />
    <files include="any/any/images/ui.png" buildAction="EmbeddedResource" />
    <!-- Embed all image resources under contentFiles/cs/ using a wild card -->
    <files include="cs/**/*.png" buildAction="EmbeddedResource" />
    <!-- Copy config.xml to the root of the output folder -->
    <files include="cs/uap10.0/config/config.xml" buildAction="None" copyToOutput="true" flatten="true" />
    <!-- Copy run.cmd to the output folder and keep the directory structure -->
    <!-- Include everything in the scripts folder except exe files -->
    <files include="cs/uap10.0/scripts/*" exclude="**/*.exe"  buildAction="None" copyToOutput="true" />
    <!-- All other files in shared are compiled and use the default options -->
</contentFiles>

The include and exclude properties on contentFiles/files elements support wildcards using the aspnet syntax. https://github.com/aspnet/FileSystem

If multiple entries match the same file all entries will be applied. The top most entry will override the lower entries if there is a conflict for the same attribute.

The contentFiles section is optional, by default all files in the nupkg contentFiles directory will use the default attribute values defined above.

Examples of .nuspec Files

The following example shows a simple .nuspec file that does not specify dependencies or files.

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
  <metadata>
    <id>sample</id>
    <version>1.2.3</version>
    <authors>Kim Abercrombie, Franck Halmaert</authors>
    <description>Sample exists only to show a sample .nuspec file.</description>
    <language>en-US</language>
    <projectUrl>http://xunit.codeplex.com/</projectUrl>
    <licenseUrl>http://xunit.codeplex.com/license</licenseUrl>
  </metadata>
</package>

The following example shows a .nuspec file that specifies dependencies.

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
  <metadata>
    <id>sample</id>
    <version>1.0.0</version>
    <authors>Microsoft</authors>
    <dependencies>
      <dependency id="another-package" version="3.0.0" />
      <dependency id="yet-another-package"/>
    </dependencies> 
  </metadata>
</package>

The following example shows a .nuspec file that specifies files.

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
  <metadata>
    <id>routedebugger</id>
    <version>1.0.0</version>
    <authors>Jay Hamlin</authors>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>Route Debugger is a little utility I wrote...</description>
  </metadata>
  <files>
    <file src="bin\Debug\*.dll" target="lib" />
  </files>
</package>

The following example shows a .nuspec file that specifies framework assemblies.

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
  <metadata>
    <id>PackageWithGacReferences</id>
    <version>1.0</version>
    <authors>Author here</authors>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>
        A package that has framework assemblyReferences depending 
        on the target framework.
    </description>
    <frameworkAssemblies>
      <frameworkAssembly assemblyName="System.Web" targetFramework="net40" />
      <frameworkAssembly assemblyName="System.Net" targetFramework="net40-client, net40" />
      <frameworkAssembly assemblyName="Microsoft.Devices.Sensors" targetFramework="sl4-wp" />
      <frameworkAssembly assemblyName="System.Json" targetFramework="sl3" />
    </frameworkAssemblies>
  </metadata>
</package>

Given the above package as an example, here is what will get installed for specific project targets:

  • Project targeting .NET4 -> System.Web, System.Net
  • Project targeting .NET4 Client Profile -> System.Net
  • Project targeting Silverlight 3 -> System.Json
  • Project targeting Silverlight 4 -> System.Windows.Controls.DomainServices
  • Project targeting WindowsPhone -> Microsoft.Devices.Sensors