Package Manifest Reference
In previous chapters, you’ve seen NuGet package manifests, or .nuspec files, being created a number of times. When creating packages, NuGet uses a convention-over-configuration approach. These conventions are rather simple by default, but relying on them may not be enough to mold the package you wish to create. A NuGet package manifest describes the contents and metadata of your package. It is included in each NuGet package, or .nupkg, file, and it is the file you’ll need to create the actual package. In short, before you can create a package, you’ll need to describe it.
This appendix covers all details about available options in the XML of a package manifest. It is largely based on the information available on the official NuGet web site at http://docs.nuget.org/docs/reference/nuspec-reference. NuGet documentation (from the Outercurve Foundation) is licensed under Creative Commons license BY 3.0 (http://creativecommons.org/licenses/by/3.0/).
Note Editing .nuspec files in Visual Studio or any XML editor can be made easier by using the XSD schema of the package manifest. This can be installed into a Visual Studio project by using NuGet: Install-Package NuGet.Manifest.Schema.
Creating the Metadata Section
The package manifest metadata section is a mandatory section within the package manifest. The metadata section itself also has a set of mandatory elements. These required elements must be specified before you can create a package based on the .nuspec manifest. Here is the list of all required metadata fields:
- ID
- Version
- Description
- Authors
Package Manifest Metadata elements
The first pieces of metadata your package exposes are the package ID and the package version. This pair of fields will uniquely identify your package on any NuGet feed. The package description and authors are used to search in the NuGet Gallery.
Table A-1 lists the possible elements in the package manifest metadata section and their descriptions.
Table A-1. Elements in the Package Manifest Metadata Section
| Element | Required? | Description |
|---|---|---|
| id | Yes | The unique identifier for the package. This is the package name that is shown when packages are listed by using the Package Manager Console, and 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. |
| version | Yes | The version of the package in a format (for example, 1.2.3). |
| title | No | The human-friendly title of the package displayed in the Manage NuGet Packages dialog box. If none is specified, the ID is used instead. |
| authors | Yes | A comma-separated list of authors of the package code. |
| owners | No | 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 Gallery. |
| description | Yes | A long description of the package. This shows up in the right pane of the Manage NuGet Packages dialog box as well as in the Package Manager Console when listing packages by using the Get-Package command. |
| releaseNotes | No | A description of the changes made in each release of the package. This field shows up only 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 | No | A short description of the package. If specified, this shows up in the middle pane of the Add Package dialog box. If not specified, a truncated version of the description is used instead. |
| language | No | The locale ID for the package, such as en-us. |
| projectUrl | No | An URL for the home page of the package. |
| iconUrl | No | A URL for the image to use as the icon for the package in the Manage NuGet Packages dialog box. This should be a 32 × 32–pixel .png file that has a transparent background. |
| licenseUrl | No | A link to the license that the package is under. |
| copyright | No | Copyright details for the package. |
| requireLicenseAcceptance | No | 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 | No | The list of dependencies for the package. |
| references | No | Names of assemblies under lib that are added as project references. If unspecified, all assemblies in lib are added as project references. When specifying a reference, specify only the name, not the path inside the package. |
| frameworkAssemblies | No | 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 | No | 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 by using searches in the Add Package Reference dialog box or filtering in the Package Manager Console window. |
| minClientVersion | No | 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 the NuGet command line. Note that this attribute was introduced in NuGet 2.5 and has no effect in older versions. |
NuGet package manifests can be generated based on either a compiled assembly or a project file (for example, MyProject.csproj). NuGet populates some replacement tokens within the metadata section of a package manifest with the data defined in the project’s assembly name, AssemblyVersionAttribute, AssemblyCompanyAttribute, and AssemblyDescriptionAttribute. The MyProject.nuspec file adjacent to the MyProject.csproj file may contain the replacement tokens listed in Table A-2, which are populated by the values within the project.
Table A-2. Package Manifest Metadata Section Replacement Tokens
| Token | Description |
|---|---|
| $id$ | The assembly name of the project’s output |
| $version$ | The assembly (informational) version as specified in the project’s AssemblyVersionAttribute |
| $title$ | The assembly title as specified in AssemblyTitleAttribute |
| $author$ | The company as specified in AssemblyCompanyAttribute |
| $company$ | The company as specified in AssemblyCompanyAttribute |
| $description$ | The description as specified in 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. |
| e | The current configuration (for example, Debug or Release). |
If your NuGet package depends on other NuGet packages, the listing of these dependencies will be generated based on the packages.config file found in your project, if any. External assemblies referenced in your project will also be added to the NuGet manifest based on the files contained in the lib folder. Adding a <dependencies> element for NuGet package references or a <references> element to add external assembly references allows adding additional dependencies for the package.
Specifying 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. When installing a package that contains a list of package dependencies through NuGet, these package dependencies will be downloaded and installed as well. The following is an example list of dependencies:
<dependencies>
<dependency id="RouteMagic" version="1.1.0" />
<dependency id="RouteDebugger" version="1.0.0" />
</dependencies>
Note that dependencies can be specified for all target frameworks the package can be installed in, as well as on a per-framework basis using dependency groups. We will cover this later in this section.
Specifying Dependency Versions
NuGet supports using interval notation for specifying version ranges. This way, you can create a package that references another NuGet package based on a specific version, a range of versions, or any latest version of the package. Limiting the version ranges may limit dependency hell in your projects. The NuGet specification was inspired by the Maven Version Range Specification but is not identical to it. The following summarizes how to specify version ranges:
1.0 = 1.0 ≤ x
(,1.0] = x ≤ 1.0
(,1.0) = x < 1.0
[1.0] = x == 1.0
(1.0) = invalid
(1.0,) = 1.0 < x
(1.0,2.0) = 1.0 < x < 2.0
[1.0,2.0] = 1.0 ≤ x ≤ 2.0
empty = latest version (it's best to just omit the attribute in this case)
Working with Dependency Groups
Package dependencies can be specified to vary according to the framework profile of the target project. For example, when installed in a .NET 2.0 project, the package may have different package dependencies than when it would be installed in a .NET 4.5 project.
The <dependencies> element can contain a set of <group> elements. Each group contains zero or more <dependency> elements and a target framework attribute specifying the framework(s) in which the dependencies should be resolved. Here’s an example:
<dependencies>
<group>
<dependency id="jQuery" />
</group>
<group targetFramework="net40">
<dependency id="jQuery" />
<dependency id="WebActivator" />
</group>
<group targetFramework="net45">
<dependency id="jQuery" />
<dependency id="WebActivatorEx" />
</group>
</dependencies>
The preceding snippet specifies several dependencies. When the package is installed in the .NET 4 Framework, specified by the net40 value in the targetFramework attribute, the package requires the dependencies jQuery and WebActivator to be installed. For a .NET 4.5 target project (net45), the jQuery and WebActivatorEx packages are depended on and not the WebActivator package we had earlier. For all target project frameworks that are different, only the jQuery package is depended on. Table A-3 lists commonly used targetFramework attribute values.
Table A-3. targetFramework Values
| Target | targetFramework Value |
|---|---|
| .NET Framework 4.5.1 | net451 |
| .NET Framework 4.5 | net45 |
| .NET Framework 4.0 | net40 |
| .NET Framework 4.0 Client Profile | net40-client |
| .NET Framework 3.5 | net35 |
| .NET Framework 3.5 Client Profile | net35-client |
| .NET Framework 3.0 | net30 |
| .NET Framework 2.0 | net20 |
| .NET Framework 1.1 | net11 |
| .NET Framework 1.0 | net10 |
| .NET Framework (unspecified version) | net |
| .NET Compact Framework 3.5 | net35-cf |
| Windows 8 Store Apps | netcore45 |
| Silverlight 5.0 | sl5 |
| Silverlight for Windows Phone 7.0 | sl3-wp |
| Silverlight for Windows Phone 7.1 Mango | sl4-wp71 |
| Windows Phone 8 | wp8 |
| Portable class libraries | portable-{frameworks} (frameworks separated by +) |
| Native libraries | native |
Note that when working with dependency groups, the <dependencies> element can contain only <group> elements. Mixing <group> and <dependency> elements is not allowed. However, by omitting the targetFramework attribute, the group will act as a fallback dependency group, which will be used when the target project cannot be matched against the other dependency groups in the package manifest.
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, only the xunit.dll and xunit.extensions.dll will be referenced from the appropriate framework or profile subdirectory of the lib folder, even if there are other assemblies in the folder. If this element is omitted, the usual behavior applies, which is to reference every assembly in the lib folder.
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 unit test frameworks such as XUnit, which need its tool assemblies to be located next to the runtime assemblies, but excluded from project references.
<references>
<reference file="xunit.dll" />
<reference file="xunit.extensions.dll" />
</references>
Explicit assembly references can also be varied per target framework. Just as with package dependencies, the <references> element can contain one or more <group> elements that target a specific framework version. The <reference> and <group> elements cannot be mixed under the <references> element. A <group> element that omits the targetFramework attribute should be used in case a fallback is needed. Possible values for the targetFramework attribute can be found in Table A-3. Here’s an example:
<references>
<group>
<reference file="xunit.dll" />
</group>
<group targetFramework="net40">
<reference file="xunit.dll" />
<reference file="xunit.extensions.dll" />
</group>
</ references >
Specifying Framework Assembly References from the GAC
In some cases, a package may depend on an assembly that’s in the .NET Framework. For example, your package may depend on the Managed Extensibility Framework (MEF), which is a .NET Framework assembly that should be added as a reference to a project explicitly. When specifying framework assembly references, NuGet will explicitly add a reference to a framework assembly when installing your NuGet 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 Global Assembly Cache (GAC). Note the emphasis on framework assembly. These assemblies are not included in your package, because they are assumed to be on every machine as part of the .NET Framework.
<frameworkAssemblies>
<frameworkAssembly assemblyName="System.ServiceModel" targetFramework="net40" />
<frameworkAssembly assemblyName="System.Web" targetFramework="net40,net45" />
<frameworkAssembly assemblyName="System.SomethingElse" />
</frameworkAssemblies>
Table A-4 lists all attributes of the frameworkAssembly element.
Table A-4. Attributes for the framleworkAssembly Element
| Attribute | Required? | Description |
|---|---|---|
| assemblyName | Yes | The fully qualified assembly name. |
| targetFramework | No | If specified, the specific target framework that this reference applies to. Multiple target frameworks can be specified, separated with a comma. For example, if a reference applies to only .NET 4.0, the value should be "net40". Possible values for the targetFramework attribute can be found in Table A-3. If the reference applies to all frameworks, omit this attribute. |
Specifying Files to Include in a Package
By convention, you do not have to explicitly specify a list of files in the .nuspec file. In some cases, however, it may be useful to explicitly list the files in your project that should be included in the NuGet package. Do note that if you specify any files, the conventions are ignored, and only the files listed in the package manifest 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.
Table A-5 lists the possible attributes of the file element.
Table A-5. Attributes for the file Element
| Attribute | Required? | Description |
|---|---|---|
| src | Yes | 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 character (**) implies a recursive directory search. |
| target | Yes | This is a relative path to the directory within the package where the source files will be placed. |
| exclude | No | The file or files to exclude. This is usually combined with a wildcard value in the src attribute. The exclude attribute can contain a semicolon-delimited list of files or a file pattern. Using a double wildcard character (**) implies a recursive exclude pattern. |
Note that NuGet will never add assemblies that are named *.resources.dll. The reason for that is NuGet treats these as localization assemblies, in which case a localized package should be created.
Exploring File Element Examples
This section describes some example usages of the file element to give you a better understanding of how it’s used in NuGet. Most of these use cases have been copied from the NuGet documentation at docs.nuget.org, but we’ve added a few as well.
Copy a single assembly in the same folder as the .nuspec file into the package’s lib folder:
<file src="foo.dll" target="lib" />The source contains foo.dll.
The packaged result is libfoo.dll.
Single Assembly with a Deep Path
Copy a single assembly into the package’s lib et40 folder so that it applies to only projects targeting the .NET 4 Framework:
<file src="assemblies
et40foo.dll" target="lib
et40" />The source contains foo.dll.
The packaged result is lib et40foo.dll.
Copy a set of assemblies within the bin elease folder into the package’s lib folder:
<file src="bin
elease*.dll" target="lib" />The source contains one of these:
- bin eleasesMyLib.dll
- bin eleasesCoolLib.dll
The packaged result is one of these:
- libMyLib.dll
- libCoolLib.dll
Set of Assemblies, Excluding a Specific Assembly
Copy a set of assemblies within the bin elease folder into the package’s lib folder, omitting one assembly:
<file src="bin
elease*.dll" target="lib" exclude="bin
eleaseCoolLib.dll" />The source contains one of these:
- bin eleasesMyLib.dll
- bin eleasesCoolLib.dll
The packaged result is libMyLib.dll.
Assemblies for Different Frameworks
Copy a set of assemblies compiled for various versions of the .NET Framework:
<file src="lib**" target="lib" />Note that the double wildcard character implies a recursive search in the source for matching files.
The source contains one of these:
- lib et40foo.dll
- lib et20foo.dll
The packaged result is one of these:
- lib et40foo.dll
- lib et20foo.dll
Copy content files from a source folder into a specific folder in a NuGet package:
<file src="cssmobile*.css" target="contentcssmobile" />The source contains one of these:
- cssmobilestyle1.css
- cssmobilestyle2.css
The packaged result is one of these:
- contentcssmobilestyle1.css
- contentcssmobilestyle2.css
Content Files with a Directory Structure
Recursively copy content files from a source folder into a NuGet package:
<file src="css***.css" target="contentcss" />The source contains one of these:
- cssmobilestyle.css
- cssmobilewp7style.css
- cssrowserstyle.css
The packaged result is one of these:
- contentcssmobilestyle.css
- contentcssmobilewp7style.css
- contentcssrowserstyle.css
Content Files with a Deep Path
Copy content files from a source folder into a folder in a NuGet package that has a different folder hierarchy than the source files:
<file src="csscoolstyle.css" target="Content" />The source contains csscoolstyle.css.
The packaged result is contentstyle.css.
Content Files Copied to a Folder with Dot in Its Name
Copy content files from a source folder into a folder in a NuGet package that has a dot in its name:
<file src="imagesNeatpic.png" target="Contentimagesfoo.bar" />Note that, because the target extension doesn’t match the src extension, NuGet treats it as a directory.
The source contains imagesNeatpic.png.
Content File with a Deep Path and a Deep Target
Copy a content file from a source folder into a NuGet package by using either of the following two lines:
<file src="csscoolstyle.css" target="Contentcsscool" />
<file src="csscoolstyle.css" target="Contentcsscoolstyle.css" />
Because the file extensions of the source and target match, the target is assumed to be the file name, not a directory name.
The source contains csscoolstyle.css.
The packaged result is contentcsscoolstyle.css.
Content File Copy and Rename
Copy a content file from a source folder into a NuGet package to a different filename in the NuGet package:
<file src="iecssstyle.css" target="Contentcssie.css" />The source contains iecssstyle.css.
The packaged result is contentcssie.css.
Excluding Files from the Package Manifest
The <file> element within a .nuspec file can be used to include a specific file or a set of files, by using a wildcard character. When doing so, 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="contentdocs" exclude="docsadmin.txt" />
</files>
Use semicolons to specify multiple files:
<files>
<file src="*.txt" target="contentdocs" exclude="admin.txt;log.txt" />
</files>
Use a wildcard character 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 character to exclude a set of files recursively across directories:
<files>
<file src="tools***.*" target="tools" exclude="***.log" />
</files>
Note By convention, NuGet ignores a series of files automatically. Every file starting with a dot (.) is ignored by default. The reason for this is that NuGet packages should not contain files and folders created by some source control clients for Subversion, Mercurial, or Git. If these files are required to be shipped in a NuGet package, make sure to explicitly add them by using the file element or specify the -NoDefaultExcludes command-line switch to the nuget pack command.