diff --git a/NuGet.Docs/ndocs/Schema/nuspec.md b/NuGet.Docs/ndocs/Schema/nuspec.md index 46cd51c2..d7e1431f 100644 --- a/NuGet.Docs/ndocs/Schema/nuspec.md +++ b/NuGet.Docs/ndocs/Schema/nuspec.md @@ -5,134 +5,152 @@ A .nuspec file is a manifest that uses XML to describe a package. NuGet uses the 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. -
versionThe version of the package, in a format like 1.2.3.
title - The human-friendly title of the package displayed in the Manage NuGet Packages - dialog. If none is specified, the ID is used instead. -
authorsA 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. This is ignored when uploading the package - to the NuGet.org Gallery. -
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. -
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. +

+
versionThe 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. +
authorsA 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. -
languageThe locale ID for the package, such as en-us.
projectUrlA URL for the home page of the package.
iconUrlA 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.
licenseUrlA link to the license that the package is under.
copyrightv1.5 Copyright details for the package.
requireLicenseAcceptanceA Boolean value that specifies whether the client needs to ensure that the package license (described by licenseUrl) is accepted before the package is installed.
dependenciesThe list of dependencies for the package. For more information, see Specifying Dependencies later in this document.
referencesv1.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.
frameworkAssembliesv1.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.
tagsA 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.
developmentDependencyv2.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.
contentFilesv3.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.
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. +
languageThe locale ID for the package, such as en-us.
projectUrlA URL for the home page of the package.
iconUrlA 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.
licenseUrlA link to the license that the package is under.
copyrightv1.5 Copyright details for the package.
requireLicenseAcceptanceA boolean value that specifies whether the client needs to ensure that the package license (described by licenseUrl) is accepted before the package is installed.
dependenciesThe list of dependencies for the package. For more information, see Specifying Dependencies later in this document.
referencesv1.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.
frameworkAssembliesv1.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.
tagsA 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.
developmentDependencyv2.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.
contentFilesv3.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 or above 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. 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. +
@@ -144,9 +162,9 @@ When you create a package from a project file, replacement tokens might appear a For example, when you use the following command: - nuget pack MyProject.csproj + nuget pack MyProject.csproj -The `MyProject.nuspec` file adjacent to the `MyProject.csproj` file may contain the following replacement tokens which +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](/ndocs/tools/nuget-cli-reference#pack) feature. @@ -158,7 +176,7 @@ using the [nuget pack -Properties](/ndocs/tools/nuget-cli-reference#pack) featur $version$ - The assembly version as specified in the assembly’s AssemblyVersionAttribute. If the assembly’s AssemblyInformationalVersionAttribute is specified, that one is used instead. + The assembly version as specified in the assembly's AssemblyVersionAttribute. If the assembly's AssemblyInformationalVersionAttribute is specified, that one is used instead. $author$ @@ -171,24 +189,25 @@ using the [nuget pack -Properties](/ndocs/tools/nuget-cli-reference#pack) featur $references$ - This element contains a set of <reference> elements, each of which + 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](#specifying-files-to-include-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: - + Assuming you are building the project that produces an assembly called Foo in release mode this will produce the following transformed xml: - + - + ##Dependencies @@ -196,10 +215,10 @@ Assuming you are building the project that produces an assembly called Foo in re ###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. - - - - + + + + The following table lists attributes of the dependency element. @@ -217,60 +236,60 @@ The following table lists attributes of the dependency element. ## Specifying Dependencies in version 2.0 and above -Starting from [version 2.0] (/Release-Notes/NuGet-2.0), package dependencies can be specified to vary according to the framework profile of the target project. The `` element contains a set of `` elements. Each group contains zero or more `` 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. +Starting from [version 2.0](/Release-Notes/NuGet-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. - - - - + + + + - - - - + + + + - - - + + + -The following table lists the attributes of a `` element. +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 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 `` element is the same as described in previous section. +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 `` 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. +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. - - - + + + - - - - + + + + ## Specifying Explicit Assembly References -Use the `` element to explicitly specify assemblies that the target project should +Use the <references /> element to explicitly specify assemblies that the target project should reference. For example, if you add the following: - - - - + + + + Then only the _xunit.dll_ and _xunit.extensions.dll_ will be referenced from the appropriate [framework/profile subdirectory](../Create/Enforced-Package-Conventions#Grouping-Assemblies-by-Framework-Version) -of the `lib` folder even if there are other assemblies in the folder. +of the lib folder even if there are other assemblies in the folder. If this element is omitted, then the usual behavior applies, which is to reference every assembly in the lib folder. @@ -287,58 +306,58 @@ assemblies to be located next to the runtime assemblies, but excluded from proje ## Specifying Explicit Assembly References in version 2.5 and above -Starting from [version 2.5] (/Release-Notes/NuGet-2.5), package assembly references can be specified to vary according to the framework profile of the target project. The `` element contains a set of `` elements. Each group contains zero or more `` 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. +Starting from [version 2.5](/Release-Notes/NuGet-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. - - - - - - - - - - - + + + + + + + + + + + -The following table lists the attributes of a `` element. +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.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 `` element is the same as described in previous section. +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 `` 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. +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. - - - - - - - - + + + + + + + + -## Specifying Framework Assembly References - GAC +## 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 +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 `` element, a child element of the metadata element, allows you to +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. - - - - + + + + The following table lists attributes of the frameworkAssembly element. @@ -371,8 +390,8 @@ of files in the .nuspec file. Note that if you specify any files, the convention 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. +Each file element specifies the source and destination of a file to include in the package via the src +attribute and target attribute respectively. @@ -397,76 +416,76 @@ attribute and `target` attribute respectively.
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 + 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. +The following is an example of a files element. - - - - - - + + + + + +

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. +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. +Copies a single assembly in the same folder as the NuSpec file into the package's lib folder. -Source Contains: `foo.dll` +Source Contains: foo.dll - - -Packaged Result: `lib\foo.dll` + + +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 +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` +Source Contains: foo.dll - + -Packaged Result: `lib\net40\foo.dll` +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. +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` +* bin\release\MyLib.dll +* bin\release\CoolLib.dll NuSpec File Element - + Packaged Result -* `lib\MyLib.dll` -* `lib\CoolLib.dll` +* lib\Mylib.dll +* lib\coollib.dll #### DLLs for different frameworks Source contains: -* `lib\net40\foo.dll` -* `lib\net20\foo.dll` +* lib\net40\foo.dll +* lib\net20\foo.dll NuSpec File Element: - + Packaged Result: -* `lib\net40\foo.dll` -* `lib\net20\foo.dll` +* lib\net40\foo.dll +* lib\net20\foo.dll Note: The double wildcard implies a recursive search in the source for matching files. @@ -479,112 +498,112 @@ These instructions define a technique used in pre-3.0 versions of NuGet that inc Source Contains: -* `css\mobile\style1.css` -* `css\mobile\style2.css` +* css\mobile\style1.css +* css\mobile\style2.css NuSpec File Element: - + Packaged Result: -* `Content\css\mobile\style1.css` -* `Content\css\mobile\style2.css` +* 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` +* css\mobile\style.css +* css\mobile\wp7\style.css +* css\browser\style.css NuSpec file element - + Packaged Result: -* `content\css\mobile\style.css` -* `content\css\mobile\wp7\style.css` -* `content\css\browser\style.css` +* 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` +Source Contains: css\cool\style.css - + -Packaged Result: `Content\style.css` +Packaged Result: content\style.css #### Content File copied to Folder with dot in name - + -Packaged Result: `Content\images\foo.bar\Neatpick.png` +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 `*` +To make sure extensionless files are captured by wildcard match use ** or * -Source Contains: `flags\installed` +Source Contains: flags\installed - + -Packaged Result: `flags\installed` +Packaged Result: flags\installed #### Content file with deep path and deep target - + -Packaged Result: `Content\css\cool\style.css` +Packaged Result: content\css\cool\style.css Note: This also works: - + 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 - + -Packaged Result: `Content\css\ie.css` +Packaged Result: content\css\ie.css ### Excluding files in the NuSpec -The `` element within a NuSpec file can be used to include a specific file or a set of files +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. - - - + + + Use semicolons to specify multiple files. - - - + + + Use a wildcard to exclude a set of files such as all backup files. - - - + + + Or use a double wildcard to exclude a set of files recursively across directories. - - - + + + ### ContentFiles with Visual Studio 2015 Update 1 and later -In order to provide a better experience and clearer definition of what files should be included 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. +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 `` element as demonstrated above. +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: @@ -598,33 +617,33 @@ 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)** +* 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` +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: +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 / files attributes +#### NuSpec contentFiles or files attributes - + - + @@ -641,11 +660,12 @@ Empty folders can use `_._` to opt out of providing content for certain combinat
AttributeDescription
includeinclude [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*/*.
excludeexclude Exclude provides either a file path or a wild card path. All matching files will be excluded from the include.
-**Attributes Defaults** +## Attributes Defaults + - - + + @@ -661,7 +681,7 @@ Empty folders can use `_._` to opt out of providing content for certain combinat
AttributeValueAttributeValue
buildAction
-**Example contentFiles section** +## Example contentFiles section @@ -688,76 +708,76 @@ The contentFiles section is optional, by default all files in the nupkg contentF The following example shows a simple .nuspec file that does not specify dependencies or files. - - - - sample - 1.2.3 - Kim Abercrombie, Franck Halmaert - Sample exists only to show a sample .nuspec file. - en-US - http://xunit.codeplex.com/ - http://xunit.codeplex.com/license - - + + + + sample + 1.2.3 + Kim Abercrombie, Franck Halmaert + Sample exists only to show a sample .nuspec file. + en-US + http://xunit.codeplex.com/ + http://xunit.codeplex.com/license + + The following example shows a .nuspec file that specifies dependencies. - - - - sample - 1.0.0 - Microsoft - - - - - - + + + + sample + 1.0.0 + Microsoft + + + + + + The following example shows a .nuspec file that specifies files. - - - - routedebugger - 1.0.0 - Jay Hamlin - false - Route Debugger is a little utility I wrote... - - - - - + + + + routedebugger + 1.0.0 + Jay Hamlin + false + Route Debugger is a little utility I wrote... + + + + + The following example shows a .nuspec file that specifies framework assemblies. - - - - PackageWithGacReferences - 1.0 - Author here - false - - A package that has framework assemblyReferences depending - on the target framework. - - - - - - - - - + + + + PackageWithGacReferences + 1.0 + Author here + false + + A package that has framework assemblyReferences depending + on the target framework. + + + + + + + + + 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 +* 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