.nuspec 1.2 File Format

A .nuspec file is a manifest that uses XML to describe a package. The manifest is used to build a package and is also stored in the package after the package is built. For information about how to build a package, see Creating a Package.

In a .nuspec file, the top-level package element contains a metadata element that describes the package and its dependencies. Optionally, the package element can include a files element that specifies files to be included in the package. If the files element is omitted, all files and folders that are in the same folder as the .nuspec file are included in the package. The .nuspec file is included in the package after the package is built (but without the element that lists files if that element was included).

Child Elements in the metadata Element

Bold indicates a required element.

Element Description
id The unique identifier for the package. This is the package name that is shown when packages are listed and which you enter in PowerShell commands such as Install-Package. 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.
version The version of the package, in a format like 1.2.3.
title The human-friendly title of the package.
authors A comma-separated list of authors of the package code.
owners A comma-separated list of the package creators. This is often the same list as in authors.
description A description of the package.
summary A summary of the package.
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 Add Library Package Reference dialog box. This should be a 32x32-pixel .png file that has a transparent background.
licenseUrl A link to the license that the package is under.
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.
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.

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. The following table lists attributes of the dependency element.

Attribute Description
id The ID of a package that this package depends on.
version The required version of the dependency package. If you enter this value as a specific version number, such as 1.2.3 , NuGet assumes that any package of that version or later is allowable. You can be more specific about which versions are allowable by using interval notation; for more information, see Specifying Version Ranges.
<dependencies>
  <dependency id="RouteMagic" version="1.1.0" />
  <dependency id="RouteDebugger" version="1.0.0" />
</dependencies>

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 new 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. The following table lists attributes of the frameworkAssembly element.

Attribute Description
assemblyName Name of the assembly such as System.Net
targetFramework Optional. Allows specifying a framework and profile name (or alias) that this framework assembly applies to such as "net40" or "sl4". Uses the same format described in the section Supporting Multiple .NET Framework Versions of the Creating a package page.
<frameworkAssemblies>
  <frameworkAssembly assemblyName="System.ComponentModel.DataAnnotations" targetFramework="net40" />
  <frameworkAssembly assemblyName="System.ServiceModel" targetFramework="net40" />
</frameworkAssemblies>

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.

Attribute Description
src The location of the file to include. The specification can include wild cards, such as src="c:\docs\bin\*.xml".
target The destination folder for the file, such as target="lib".

The following example shows a typical files element.

<files>
<file src="c:\docs\bin\*.xml" target="lib" />
<file src="bin\Debug\*.dll" target="lib" />
<file src="bin\Debug\*.pdb" target="lib" />
<file src="tools\**\*.*" />
</files>

All paths are resolved relative to the .nuspec file unless an absolute path is specified. For details about how to specify the src and target attributes, see NuSpec File Element Specification.

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>
<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>
<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:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<metadata xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
<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>
  <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" />
      <frameworkAssembly assemblyName="System.Windows.Controls.DomainServices" targetFramework="sl4" />
    </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

Package Schema

For information about the .nuspec file schema, see the nuspec.xsd documentation. All .nuspec files are validated against this schema when you use nuget.exe or the PackageBuilder APIs to build a NuGet package.

Related Information

NuGet documentation

Last edited Aug 16, 2013 at 11:30 PM by JeffHandley, version 23