.nuspec リファレンス.nuspec reference

.nuspec ファイルは、パッケージのメタデータが含まれている XML マニフェストです。A .nuspec file is an XML manifest that contains package metadata. このマニフェストは、パッケージを作成するためと、コンシューマーに情報を提供するための、両方に使われます。This manifest is used both to build the package and to provide information to consumers. パッケージにはマニフェストが常に含まれています。The manifest is always included in a package.

このトピックの内容:In this topic:

一般的な形式とスキーマGeneral form and schema

最新の nuspec.xsd スキーマ ファイルは、NuGet GitHub リポジトリにあります。The current nuspec.xsd schema file can be found in the NuGet GitHub repository.

このスキーマでの .nuspec ファイルの一般的な形式は次のとおりです。Within this schema, a .nuspec file has the following general form:

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <!-- Required elements-->
        <id></id>
        <version></version>
        <description></description>
        <authors></authors>

        <!-- Optional elements -->
        <!-- ... -->
    </metadata>
    <!-- Optional 'files' node -->
</package>

スキーマの視覚的な表現をはっきり表示したい場合は、Visual Studio のデザイン モードでスキーマ ファイルを開き、[XML スキーマ エクスプローラー] リンクをクリックします。For a clear visual representation of the schema, open the schema file in Visual Studio in Design mode and click on the XML Schema Explorer link. または、コードとしてファイルを開き、エディター内を右クリックして、[XML スキーマ エクスプローラーで表示] を選びます。Alternately, open the file as code, right-click in the editor, and select Show XML Schema Explorer. どちらの方法でも次のように表示されます (ほとんどを展開した場合)。Either way you get a view like the one below (when mostly expanded):

Visual Studio のスキーマ エクスプローラーで開いた nuspec.xsd

メタデータの属性Metadata attributes

<metadata> 要素では、次の表で説明する属性を指定できます。The <metadata> element supports the attributes described in the following table.

属性Attribute 必須Required 説明Description
minClientVersionminClientVersion いいえNo nuget.exe および Visual Studio パッケージ マネージャーで強制する、このパッケージをインストールできる NuGet クライアントの最小バージョンを指定します。Specifies the minimum version of the NuGet client that can install this package, enforced by nuget.exe and the Visual Studio Package Manager. これは、NuGet クライアントの特定のバージョンで追加された .nuspec ファイルの特定の機能にパッケージが依存しているときに、常に使われます。This is used whenever the package depends on specific features of the .nuspec file that were added in a particular version of the NuGet client. たとえば、developmentDependency 属性を使っているパッケージでは、minClientVersion に "2.8" を指定する必要があります。For example, a package using the developmentDependency attribute should specify "2.8" for minClientVersion. 同様に、contentFiles 要素 (次のセクションを参照) を使っているパッケージでは、minClientVersion を "3.3" に設定する必要があります。Similarly, a package using the contentFiles element (see the next section) should set minClientVersion to "3.3". また、バージョン 2.5 より前の NuGet クライアントはこのフラグを認識しないので、minClientVersion の値が何であっても、"常に" パッケージをインストールしないことにも注意してください。Note also that because NuGet clients prior to 2.5 do not recognize this flag, they always refuse to install the package no matter what minClientVersion contains.

メタデータの必須要素Required metadata elements

以下の要素はパッケージの最低要件であり、メタデータの省略可能な要素を追加してパッケージに関する開発者の全体的なエクスペリエンスを向上させることを検討する必要があります。Although the following elements are the minimum requirements for a package, you should consider adding the optional metadata elements to improve the overall experience developers have with your package.

これらの要素は、<metadata> 要素内で指定する必要があります。These elements must appear within a <metadata> element.

要素Element 説明Description
IDid パッケージの識別子。大文字と小文字が区別されます。nuget.org 全体で、またはパッケージが存在するギャラリー全体で、一意である必要があります。The case-insensitive package identifier, which must be unique across nuget.org or whatever gallery the package resides in. ID は、スペースまたは URL で無効な文字を含んでいてはならず、一般に .NET 名前空間の規則に従います。IDs may not contain spaces or characters that are not valid for a URL, and generally follow .NET namespace rules. ガイダンスについては、一意のパッケージ識別子の選択に関するページをご覧ください。See Choosing a unique package identifier for guidance.
versionversion パッケージのバージョン。major.minor.patch のパターンに従います。The version of the package, following the major.minor.patch pattern. Package versioning」(パッケージのバージョン管理) で説明されているように、バージョン番号にはプレリリースのサフィックスを含めることができます。Version numbers may include a pre-release suffix as described in Package versioning.
descriptiondescription UI 画面用のパッケージの長い説明。A long description of the package for UI display.
authorsauthors パッケージ作成者の一覧。コンマで区切られています。nuget.org のプロファイル名と一致します。これらは nuget.org の NuGet ギャラリーに表示され、同じ作成者によるパッケージの相互参照に使用されます。A comma-separated list of packages authors, matching the profile names on nuget.org. These are displayed in the NuGet Gallery on nuget.org and are used to cross-reference packages by the same authors.

メタデータの省略可能な要素Optional metadata elements

これらの要素は、<metadata> 要素内に表示されることがあります。These elements may appear within a <metadata> element.

単一要素Single elements

要素Element 説明Description
titletitle 人が読みやすいパッケージのタイトル。通常、nuget.org と、Visual Studio のパッケージ マネージャーの UI 画面で使用されます。A human-friendly title of the package, typically used in UI displays as on nuget.org and the Package Manager in Visual Studio. 指定しないと、パッケージ ID が使われます。If not specified, the package ID is used.
ownersowners コンマで区切って指定したパッケージ作成者の一覧。nuget.org でのプロファイル名です。多くの場合は authors と同じ一覧であり、nuget.org にパッケージをアップロードするときは無視されます。「nuget.org でパッケージ所有者を管理する」をご覧ください。A comma-separated list of the package creators using profile names on nuget.org. This is often the same list as in authors, and is ignored when uploading the package to nuget.org. See Managing package owners on nuget.org.
projectUrlprojectUrl パッケージのホーム ページの URL。多くの場合、UI 画面と nuget.org に表示されます。A URL for the package's home page, often shown in UI displays as well as nuget.org.
licenseUrllicenseUrl パッケージのライセンスの URL。通常、UI 画面および nuget.org に表示されます。A URL for the package's license, often shown in UI displays as well as nuget.org.
iconUrliconUrl UI 表示でパッケージのアイコンとして使われる、背景が透明な 64 x 64 の画像の URL。A URL for a 64x64 image with transparency background to use as the icon for the package in UI display. この要素の値は、"画像を直接示す URL" であり、画像を含む Web ページの URL ではないことに注意してください。Be sure this element contains the direct image URL and not the URL of a web page containing the image. たとえば、GitHub からイメージを使用する URL と同様に、raw ファイルを使用して https://github.com/<username>/<repository>/raw/<branch>/<logo.png>です。For example, to use an image from GitHub, use the raw file URL like https://github.com/<username>/<repository>/raw/<branch>/<logo.png>.
requireLicenseAcceptancerequireLicenseAcceptance パッケージをインストールする前にクライアントがユーザーに対してパッケージのライセンスへの同意を求めるプロンプトを表示する必要があるかどうかを示すブール値。A Boolean value specifying whether the client must prompt the consumer to accept the package license before installing the package.
developmentDependencydevelopmentDependency (2.8 以降) 開発専用の依存関係としてパッケージをマークするかどうかを指定するブール値。指定すると、そのパッケージは他のパッケージに依存関係として含まれなくなります。(2.8+) A Boolean value specifying whether the package is be marked as a development-only-dependency, which prevents the package from being included as a dependency in other packages.
summarysummary UI 画面用のパッケージの短い説明。A short description of the package for UI display. 省略すると、description を切り詰めたバージョンが使われます。If omitted, a truncated version of description is used.
releaseNotesreleaseNotes (1.5 以降) このリリースのパッケージで行われた変更の説明。Visual Studio パッケージ マネージャーの [更新] タブなどの UI で、パッケージの説明の代わりによく使われます。(1.5+) A description of the changes made in this release of the package, often used in UI like the Updates tab of the Visual Studio Package Manager in place of the package description.
copyrightcopyright (1.5 以降) パッケージの著作権の詳細。(1.5+) Copyright details for the package.
languagelanguage パッケージのロケール ID。The locale ID for the package. ローカライズされたパッケージの作成」をご覧ください。See Creating localized packages.
tagstags パッケージについて説明し、検索やフィルターでパッケージを見つけやすくするタグやキーワードを、スペースで区切って列記したリスト。A space-delimited list of tags and keywords that describe the package and aid discoverability of packages through search and filtering.
serviceableserviceable (3.3 以降) NuGet 内部でのみ使われます。(3.3+) For internal NuGet use only.

コレクション要素Collection elements

要素Element 説明Description
packageTypespackageTypes (3.5 以降) 従来の依存関係パッケージ以外の場合に、パッケージの種類を指定する 0 個以上の <packageType> 要素のコレクション。(3.5+) A collection of zero or more <packageType> elements specifying the type of the package if other than a traditional dependency package. 各 packageType は、name 属性と version 属性を持っています。Each packageType has attributes of name and version. Setting a package type」(パッケージの種類の設定) をご覧ください。See Setting a package type.
dependenciesdependencies パッケージの依存関係を指定する 0 個以上の <dependency> 要素のコレクション。A collection of zero or more <dependency> elements specifying the dependencies for the package. 各 dependency は、idversioninclude (3.x 以降)、exclude (3.x 以降) の各属性を持っています。Each dependency has attributes of id, version, include (3.x+), and exclude (3.x+). 後の「依存関係」をご覧ください。See Dependencies below.
frameworkAssembliesframeworkAssemblies (1.2 以降) このパッケージで必要な .NET Framework アセンブリ参照を示す 0 個以上の <frameworkAssembly> 要素のコレクション。パッケージを使うプロジェクトに参照が確実に追加されるようにします。(1.2+) A collection of zero or more <frameworkAssembly> elements identifying .NET Framework assembly references that this package requires, which ensures that references are added to projects consuming the package. 各 frameworkAssembly は、assemblyName 属性と targetFramework 属性を持っています。Each frameworkAssembly has assemblyName and targetFramework attributes. フレームワーク アセンブリ参照 GAC の指定に関する後の説明をご覧ください。See Specifying framework assembly references GAC below.
referencesreferences (1.5 以降) パッケージの lib フォルダー内のアセンブリのうちプロジェクト参照として追加するものを指定する、0 個以上の <reference> 要素のコレクション。(1.5+) A collection of zero or more <reference> elements naming assemblies in the package's lib folder that are added as project references. 各参照は、file 属性を持っています。Each reference has a file attribute. <references><group> 要素を含むこともでき、その targetFramework 属性に <reference> 要素を含めることができます。<references> can also contain a <group> element with a targetFramework attribute, that then contains <reference> elements. 省略すると、lib のすべての参照が含まれます。If omitted, all references in lib are included. 明示的なアセンブリ参照の指定に関する後の説明をご覧ください。See Specifying explicit assembly references below.
contentFilescontentFiles (3.3 以降) 使用する側のプロジェクトに含めるコンテンツ ファイルを示す <files> 要素のコレクション。(3.3+) A collection of <files> elements that identify content files to include in the consuming project. これらのファイルは、プロジェクト システム内でのファイルの使用方法が記述されている属性のセットで指定されます。These files are specified with a set of attributes that describe how they should be used within the project system. パッケージに含めるファイルの指定に関する後の説明をご覧ください。See Specifying files to include in the package below.

Files 要素Files element

<package> ノードでは、<metadata> の兄弟として <files> ノードを追加するか、または <metadata> の子として <contentFiles> を追加して、パッケージに含めるアセンブリとコンテンツ ファイルを指定できます。The <package> node may contain a <files> node as a sibling to <metadata>, and a or <contentFiles> child under <metadata>, to specify which assembly and content files to include in the package. 詳しくは、このトピックで後述する「アセンブリ ファイルを含める」と「コンテンツ ファイルを含める」をご覧ください。See Including assembly files and Including content files later in this topic for details.

置換トークンReplacement tokens

パッケージを作成するとき、nuget pack コマンドは、.nuspec ファイルの <metadata> ノード内の $ で区切られたトークンを、プロジェクト ファイルまたは pack コマンドの -properties スイッチで指定されている値に置き換えます。When creating a package, the nuget pack command replaces $-delimited tokens in the .nuspec file's <metadata> node with values that come from either a project file or the pack command's -properties switch.

コマンド ラインでは、nuget pack -properties <name>=<value>;<name>=<value> でトークンの値を指定します。On the command line, you specify token values with nuget pack -properties <name>=<value>;<name>=<value>. たとえば、.nuspec では $owners$$desc$ などのトークンを使っておき、パッキング時に次のようにして値を指定できます。For example, you can use a token such as $owners$ and $desc$ in the .nuspec and provide the values at packing time as follows:

nuget pack MyProject.csproj -properties
    owners=janedoe,harikm,kimo,xiaop;desc="Awesome app logger utility"

プロジェクトの値を使うには、次の表で説明するトークンを指定します (AssemblyInfo は、Properties 内の AssemblyInfo.csAssemblyInfo.vb などのファイルを参照します)。To use values from a project, specify the tokens described in the table below (AssemblyInfo refers to the file in Properties such as AssemblyInfo.cs or AssemblyInfo.vb).

これらのトークンを使うには、nuget pack を実行するときに、.nuspec だけでなくプロジェクト ファイルも指定します。To use these tokens, run nuget pack with the project file rather than just the .nuspec. たとえば、次のコマンドを使うと、.nuspec ファイルの $id$ および $version$ トークンが、プロジェクトの AssemblyName および AssemblyVersion の値に置き換えられます。For example, when using the following command, the $id$ and $version$ tokens in a .nuspec file are replaced with the project's AssemblyName and AssemblyVersion values:

nuget pack MyProject.csproj

通常、プロジェクトがある場合は、最初に nuget spec MyProject.csproj を使って .nuspec を作成すると、一部の標準的なトークンが自動的に追加されます。Typically, when you have a project, you create the .nuspec initially using nuget spec MyProject.csproj which automatically includes some of these standard tokens. ただし、.nuspec の必須要素に対する値がプロジェクトにないと、nuget pack は失敗します。However, if a project lacks values for required .nuspec elements, then nuget pack fails. さらに、プロジェクトの値を変更する場合は、パッケージを作成する前に必ずビルドし直してください。これは、pack コマンドの build スイッチで簡単に行うことができます。Furthermore, if you change project values, be sure to rebuild before creating the package; this can be done conveniently with the pack command's build switch.

例外である $configuration$ を除き、コマンド ラインの同じトークンに割り当てられている値より、プロジェクトの値の方が優先的に使われます。With the exception of $configuration$, values in the project are used in preference to any assigned to the same token on the command line.

トークンToken 値のソースValue source [値]Value
$id$$id$ プロジェクト ファイルProject file プロジェクト ファイルから AssemblyName (タイトル)AssemblyName (title) from the project file
$version$$version$ AssemblyInfoAssemblyInfo ある場合は AssemblyInformationalVersion、ない場合は AssemblyVersionAssemblyInformationalVersion if present, otherwise AssemblyVersion
$author$$author$ AssemblyInfoAssemblyInfo AssemblyCompanyAssemblyCompany
$title$$title$ AssemblyInfoAssemblyInfo AssemblyTitleAssemblyTitle
$description$$description$ AssemblyInfoAssemblyInfo AssemblyDescriptionAssemblyDescription
$copyright$$copyright$ AssemblyInfoAssemblyInfo AssemblyCopyrightAssemblyCopyright
$configuration$$configuration$ アセンブリ DLLAssembly DLL アセンブリのビルドに使われる構成。既定値は Debug。Configuration used to build the assembly, defaulting to Debug. Release 構成を使ってパッケージを作成するには、常にコマンド ラインで -properties Configuration=Release を使うことに注意してください。Note that to create a package using a Release configuration, you always use -properties Configuration=Release on the command line.

アセンブリ ファイルおよびコンテンツ ファイルを含めるときは、トークンを使ってパスを解決することもできます。Tokens can also be used to resolve paths when you include assembly files and content files. トークンの名前は MSBuild のプロパティと同じであり、現在のビルド構成に基づいて含めるファイルを選ぶことができます。The tokens have the same names as the MSBuild properties, making it possible to select files to be included depending on the current build configuration. たとえば、.nuspec ファイルで次のトークンを使うものとします。For example, if you use the following tokens in the .nuspec file:

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

そして、MSBuild で AssemblyNameLoggingLibrary であるアセンブリを Release 構成でビルドすると、パッケージ内の .nuspec ファイルの行は結果として次のようになります。And you build an assembly whose AssemblyName is LoggingLibrary with the Release configuration in MSBuild, the resulting lines in the .nuspec file in the package is as follows:

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

依存関係Dependencies

<metadata> 内の <dependencies> 要素は、最上位のパッケージが依存している他のパッケージを示す <dependency> 要素をいくつでも含むことができます。The <dependencies> element within <metadata> contains any number of <dependency> elements that identify other packages upon which the top-level package depends. <dependency> の属性は次にとおりです。The attributes for each <dependency> are as follows:

属性Attribute 説明Description
id (必須) "EntityFramework" や "NUnit" などの依存関係のパッケージ ID。これはパッケージ ページに表示されるパッケージ nuget.org の名前となります。(Required) The package ID of the dependency, such as "EntityFramework" and "NUnit", which is the name of the package nuget.org shows on a package page.
version (必須) 依存関係として許容されるバージョンの範囲。(Required) The range of versions acceptable as a dependency. 厳密な構文については、「Package versioning」(パッケージのバージョン管理) をご覧ください。See Package versioning for exact syntax.
includeinclude 最終的なパッケージに含める依存関係を示す包含/除外タグ (下記参照) のコンマ区切りリスト。A comma-delimited list of include/exclude tags (see below) indicating of the dependency to include in the final package. 既定値は none です。The default value is none.
excludeexclude 最終的なパッケージから除外する依存関係を示す包含/除外タグ (下記参照) のコンマ区切りリスト。A comma-delimited list of include/exclude tags (see below) indicating of the dependency to exclude in the final package. 既定値は all です。The default value is all. exclude で指定されているタグの方が、include で指定されているタグより優先されます。Tags specified with exclude take precedence over those specified with include. たとえば、include="runtime, compile" exclude="compile"include="runtime" と同じです。For example, include="runtime, compile" exclude="compile" is the same as include="runtime".
包含/除外タグInclude/Exclude tag ターゲットの影響を受けるフォルダーAffected folders of the target
contentFilescontentFiles ContentContent
ランタイムruntime Runtime、Resources、FrameworkAssembliesRuntime, Resources, and FrameworkAssemblies
compilecompile liblib
ビルドbuild build (MSBuild のプロパティとターゲット)build (MSBuild props and targets)
nativenative nativenative
nonenone フォルダーなしNo folders
すべてall すべてのフォルダーAll folders

たとえば、次の行は PackageA バージョン 1.1.0 以降および PackageB バージョン 1.x での依存関係を示します。For example, the following lines indicate dependencies on PackageA version 1.1.0 or higher, and PackageB version 1.x.

<dependencies>
    <dependency id="PackageA" version="1.1.0" />
    <dependency id="PackageB" version="[1,2)" />
</dependencies>

次の行も同じパッケージでの依存関係を示しますが、PackageAcontentFiles および build フォルダーを含めて、PackageBnative および compile フォルダーを除くすべてを含めることを指定します。The following lines indicate dependencies on the same packages, but specify to include the contentFiles and build folders of PackageA and everything but the native and compile folders of PackageB"

<dependencies>
    <dependency id="PackageA" version="1.1.0" include="contentFiles, build" />
    <dependency id="PackageB" version="[1,2)" exclude="native, compile" />
</dependencies>

注: nuget spec を使ってプロジェクトから .nuspec を作成すると、そのプロジェクトに存在する依存関係が結果の .nuspec ファイルに自動的に含まれます。Note: When creating a .nuspec from a project using nuget spec, dependencies that exist in that project are automatically included in the resulting .nuspec file.

依存関係グループDependency groups

バージョン 2.0 以降Version 2.0+

1 つのフラット リストの代わりに、<dependencies><group> 要素を使い、ターゲット プロジェクトのフレームワーク プロファイルに従って依存関係を指定できます。As an alternative to a single flat list, dependencies can be specified according to the framework profile of the target project using <group> elements within <dependencies>.

各グループには、targetFramework という名前の属性があり、0 個以上の <dependency> 要素が含まれます。Each group has an attribute named targetFramework and contains zero or more <dependency> elements. ターゲットのフレームワークにプロジェクトのフレームワーク プロファイルとの互換性がある場合、これらの依存関係が一緒にインストールされます。Those dependencies are installed together when the target framework is compatible with the project's framework profile.

依存関係の既定のリストまたはフォールバック リストとしては、targetFramework 属性のない <group> 要素が使われます。The <group> element without a targetFramework attribute is used as the default or fallback list of dependencies. 正確なフレームワーク識別子については、「ターゲット フレームワーク」をご覧ください。See Target frameworks for the exact framework identifiers.

重要

グループの形式をフラット リストと併用することはできません。The group format cannot be intermixed with a flat list.

次の例では、<group> 要素のさまざまなバリエーションを示します。The following example shows different variations of the <group> element:

<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>

明示的なアセンブリ参照Explicit assembly references

<references> 要素は、パッケージを使うときにターゲット プロジェクトが参照する必要のあるアセンブリを明示的に指定します。The <references> element explicitly specifies the assemblies that the target project should reference when using the package. この要素がある場合、NuGet は一覧で指定されているアセンブリのみへの参照を追加します。パッケージの lib フォルダーに含まれる他のアセンブリに対する参照は追加されません。When this element is present, NuGet add references to only the listed assemblies; it does not add references for any other assemblies in the package's lib folder.

たとえば、次の <references> 要素は、パッケージに他のアセンブリがある場合でも、xunit.dllxunit.extensions.dll に対する参照だけを追加するよう NuGet に指示します。For example, the following <references> element instructs NuGet to add references to only xunit.dll and xunit.extensions.dll even if there are additional assemblies in the package:

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

明示的な参照は、通常、設計時のみのアセンブリに使われます。Explicit references are typically used for design-time only assemblies. たとえば、コード コントラクトを使うときは、Visual Studio がコントラクト アセンブリを検出できるように、コントラクト アセンブリはそれが拡張するランタイム アセンブリの隣に存在する必要がありますが、プロジェクトでコントラクト アセンブリを参照したり、プロジェクトの bin フォルダーにコントラクト アセンブリをコピーしたりする必要はありません。When using Code Contracts, for example, contract assemblies need to be next to the runtime assemblies that they augment so that Visual Studio can find them, but the contract assemblies need not be referenced by the project or copied into the project's bin folder.

同様に、明示的な参照は XUnit などの単体テスト フレームワークに使うことができ、その場合、ツール アセンブリはランタイム アセンブリの隣に存在する必要がありますが、プロジェクト参照として含まれる必要はありません。Similarly, explicit references can be used for unit test frameworks, such as XUnit, which needs its tools assemblies located next to the runtime assemblies, but does not need them included as project references.

[参照グループ]Reference groups

1 つのフラット リストの代わりに、<references><group> 要素を使い、ターゲット プロジェクトのフレームワーク プロファイルに従って参照を指定できます。As an alternative to a single flat list, references can be specified according to the framework profile of the target project using <group> elements within <references>.

各グループには、targetFramework という名前の属性があり、0 個以上の <reference> 要素が含まれます。Each group has an attribute named targetFramework and contains zero or more <reference> elements. ターゲットのフレームワークにプロジェクトのフレームワーク プロファイルとの互換性がある場合、これらの参照はプロジェクトに追加されます。Those references are added to a project when the target framework is compatible with the project's framework profile.

参照の既定のリストまたはフォールバック リストとしては、targetFramework 属性のない <group> 要素が使われます。The <group> element without a targetFramework attribute is used as the default or fallback list of references. 正確なフレームワーク識別子については、「ターゲット フレームワーク」をご覧ください。See Target frameworks for the exact framework identifiers.

重要

グループの形式をフラット リストと併用することはできません。The group format cannot be intermixed with a flat list.

次の例では、<group> 要素のさまざまなバリエーションを示します。The following example shows different variations of the <group> element:

<references>
    <group>
        <reference file="a.dll" />
    </group>

    <group targetFramework="net45">
        <reference file="b45.dll" />
    </group>

    <group targetFramework="netcore45">
        <reference file="bcore45.dll" />
    </group>
</references>

フレームワーク アセンブリ参照Framework assembly references

フレームワーク アセンブリは、.NET Framework の一部であり、指定されたコンピューターのグローバル アセンブリ キャッシュ (GAC) に既に存在している必要があります。Framework assemblies are those that are part of the .NET framework and should already be in the global assembly cache (GAC) for any given machine. <frameworkAssemblies> 要素でこれらのアセンブリを指定することにより、プロジェクトに必要な参照がまだない場合であっても、そのような参照をプロジェクトに確実に追加できます。By identifying those assemblies within the <frameworkAssemblies> element, a package can ensure that required references are added to a project in the event that the project doesn't have such references already. もちろん、そのようなアセンブリがパッケージに直接含まれることはありません。Such assemblies, of course, are not included in a package directly.

<frameworkAssemblies> 要素には 0 個以上の <frameworkAssembly> 要素を含めることができ、それぞれで次の属性を指定します。The <frameworkAssemblies> element contains zero or more <frameworkAssembly> elements, each of which specifies the following attributes:

属性Attribute 説明Description
assemblyNameassemblyName (必須) 完全修飾アセンブリ名。(Required) The fully qualified assembly name.
targetFrameworktargetFramework (省略可能) この参照を適用するターゲット フレームワークを指定します。(Optional) Specifies the target framework to which this reference applies. 省略した場合は、参照がすべてのフレームワークに適用されることを示します。If omitted, indicates that the reference applies to all frameworks. 正確なフレームワーク識別子については、「ターゲット フレームワーク」をご覧ください。See Target frameworks for the exact framework identifiers.

次の例は、System.Net への参照はすべてのターゲット フレームワークに適用され、System.ServiceModel への参照は .NET Framework 4.0 のみに適用されることを示します。The following example shows a reference to System.Net for all target frameworks, and a reference to System.ServiceModel for .NET Framework 4.0 only:

<frameworkAssemblies>
    <frameworkAssembly assemblyName="System.Net"  />

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

アセンブリ ファイルを含めるIncluding assembly files

パッケージを作成する」で説明されている規則に従う場合、.nuspec ファイルでファイルの一覧を明示的に指定する必要はありません。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. nuget pack コマンドが必要なファイルを自動的に選びます。The nuget pack command automatically picks up the necessary files.

重要

プロジェクトにパッケージをインストールするとき、NuGet はパッケージの DLL にアセンブリ参照を自動的に追加します。ただし、指定されている .resources.dll は、ローカライズされたサテライト アセンブリであると見なされるため "除外" されます。When a package is installed into a project, NuGet automatically adds assembly references to the package's DLLs, excluding those that are named .resources.dll because they are assumed to be localized satellite assemblies. そのため、避けなければ不可欠なパッケージ コードが含まれてしまうファイルには .resources.dll を使わないようにします。For this reason, avoid using .resources.dll for files that otherwise contain essential package code.

この自動動作をバイパスして、パッケージに含めるファイルを明示的に制御するには、<files> 要素を <package> の子要素 (および <metadata> の兄弟要素) として配置し、各ファイルを個別の <file> 要素で示します。To bypass this automatic behavior and explicitly control which files are included in a package, place a <files> element as a child of <package> (and a sibling of <metadata>), identifying each file with a separate <file> element. 例えば:For example:

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

NuGet 2.x 以前および packages.config を使っているプロジェクトでは、<files> 要素はパッケージのインストール時に変更できないコンテンツ ファイルを含めるためにも使われます。With NuGet 2.x and earlier, and projects using packages.config, the <files> element is also used to include immutable content files when a package is installed. NuGet 3.3 以降で、PackageReference を使用しているプロジェクトでは、代わりに <contentFiles> 要素が使用されます。With NuGet 3.3+ and projects PackageReference, the <contentFiles> element is used instead. 詳しくは、後の「コンテンツ ファイルを含める」をご覧ください。See Including content files below for details.

File 要素の属性File element attributes

<file> 要素では、次の属性を指定します。Each <file> element specifies the following attributes:

属性Attribute 説明Description
srcsrc 含める 1 つまたは複数のファイルの場所。exclude 属性によって指定される除外の対象になります。The location of the file or files to include, subject to exclusions specified by the exclude attribute. 絶対パスを指定しない限り、パスは .nuspec ファイルが基準になります。The path is relative to the .nuspec file unless an absolute path is specified. ワイルドカード文字 * を使うことができ、2 個のワイルドカード ** は再帰的なフォルダー検索を意味します。The wildcard character * is allowed, and the double wildcard ** implies a recursive folder search.
targettarget ソース ファイルが格納されるパッケージ内のフォルダーへの相対パス。libcontentbuild、または tools で始まっている必要があります。The relative path to the folder within the package where the source files are placed, which must begin with lib, content, build, or tools. 規則に基づく作業ディレクトリからの .nuspec の作成に関するページをご覧ください。See Creating a .nuspec from a convention-based working directory.
excludeexclude src の場所から除外するファイルまたはファイル パターンをセミコロンで区切ったリスト。A semicolon-delimited list of files or file patterns to exclude from the src location. ワイルドカード文字 * を使うことができ、2 個のワイルドカード ** は再帰的なフォルダー検索を意味します。The wildcard character * is allowed, and the double wildcard ** implies a recursive folder search.

使用例Examples

1 つのアセンブリSingle assembly

Source file:
    library.dll

.nuspec entry:
    <file src="library.dll" target="lib" />

Packaged result:
    lib\library.dll

ターゲット フレームワークに固有の 1 つのアセンブリSingle assembly specific to a target framework

Source file:
    library.dll

.nuspec entry:
    <file src="assemblies\net40\library.dll" target="lib\net40" />

Packaged result:
    lib\net40\library.dll

ワイルドカードを使った DLL のセットSet of DLLs using a wildcard

Source files:
    bin\release\libraryA.dll
    bin\release\libraryB.dll

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

Packaged result:
    lib\libraryA.dll
    lib\libraryB.dll

異なるフレームワークの DLLDLLs for different frameworks

Source files:
    lib\net40\library.dll
    lib\net20\library.dll

.nuspec entry (using ** recursive search):
    <file src="lib\**" target="lib" />

Packaged result:
    lib\net40\library.dll
    lib\net20\library.dll

ファイルの除外Excluding files

Source files:
    \tools\fileA.bak
    \tools\fileB.bak
    \tools\fileA.log
    \tools\build\fileB.log

.nuspec entries:
    <file src="tools\*.*" target="tools" exclude="tools\*.bak" />
    <file src="tools\**\*.*" target="tools" exclude="**\*.log" />

Package result:
    (no files)

コンテンツ ファイルを含めるIncluding content files

コンテンツ ファイルは、パッケージでプロジェクトに含める必要がある変更できないファイルです。Content files are immutable files that a package needs to include in a project. 変更できないので、それを使うプロジェクトによる変更は意図されていません。Being immutable, they are not intended to be modified by the consuming project. コンテンツ ファイルの例を次に示します。Example content files include:

  • リソースとして埋め込まれる画像Images that are embedded as resources
  • コンパイル済みのソース ファイルSource files that are already compiled
  • プロジェクトのビルド出力と共に含まれる必要があるスクリプトScripts that need to be included with the build output of the project
  • プロジェクトに含まれる必要はあるが、プロジェクト固有の変更は必要ない、パッケージの構成ファイルConfiguration files for the package that need to be included in the project but don't need any project-specific changes

コンテンツ ファイルをパッケージに含めるには、<files> 要素を使い、target 属性で content フォルダーを指定します。Content files are included in a package using the <files> element, specifying the content folder in the target attribute. ただし、PackageReference を使用しているプロジェクトにパッケージをインストールする場合、このようなファイルは無視され、代わりに <contentFiles> 要素が使用されます。However, such files are ignored when the package is installed in a project using PackageReference, which instead uses the <contentFiles> element.

使用する側のプロジェクトとの最大限の互換性のため、パッケージでは両方の要素でコンテンツ ファイルを指定するのが理想的です。For maximum compatibility with consuming projects, a package ideally specifies the content files in both elements.

コンテンツ ファイルに対する files 要素の使用Using the files element for content files

コンテンツ ファイルでは、アセンブリ ファイルの場合と同じ形式を使用しますが、次の例のように、target 属性で基本フォルダーとして content を指定します。For content files, simply use the same format as for assembly files, but specify content as the base folder in the target attribute as shown in the following examples.

基本的なコンテンツ ファイルBasic content files

Source files:
    css\mobile\style1.css
    css\mobile\style2.css

.nuspec entry:
    <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 files:
    css\mobile\style.css
    css\mobile\wp7\style.css
    css\browser\style.css

.nuspec entry:
    <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 specific to a target framework

Source file:
    css\cool\style.css

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

Packaged result:
    content\style.css

名前のドットでフォルダーにコピーされるコンテンツ ファイルContent file copied to a folder with dot in name

この場合、NuGet は target の拡張子が src の拡張子と一致しないものと判断し、target での名前のその部分をフォルダーとして扱います。In this case, NuGet sees that the extension in target does not match the extension in src and thus treats that part of the name in target as a folder:

Source file:
    images\picture.png

.nuspec entry:
    <file src="images\picture.png" target="Content\images\package.icons" />

Packaged result:
    content\images\package.icons\picture.png

拡張子のないコンテンツ ファイルContent files without extensions

拡張子のないファイルを含めるには、ワイルドカード * または ** を使います。To include files without an extension, use the * or ** wildcards:

Source file:
    flags\installed

.nuspec entry:
    <file src="flags\**" target="flags" />

Packaged result:
    flags\installed

深いパスと深いターゲットのコンテンツ ファイルContent files with deep path and deep target

この場合、ソースとターゲットのファイル拡張子が一致するので、NuGet はターゲットがフォルダーではなくファイル名であると想定します。In this case, because the file extensions of the source and target match, NuGet assumes that the target is a file name and not a folder:

Source file:
    css\cool\style.css

.nuspec entry:
    <file src="css\cool\style.css" target="Content\css\cool" />
    or:
    <file src="css\cool\style.css" target="Content\css\cool\style.css" />

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

パッケージ内のコンテンツ ファイルの名前の変更Renaming a content file in the package

Source file:
    ie\css\style.css

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

Packaged result:
    content\css\ie.css

ファイルの除外Excluding files

Source file:
    docs\*.txt (multiple files)

.nuspec entry:
    <file src="docs\*.txt" target="content\docs" exclude="docs\admin.txt" />
    or
    <file src="*.txt" target="content\docs" exclude="admin.txt;log.txt" />

Packaged result:
    All .txt files from docs except admin.txt (first example)
    All .txt files from docs except admin.txt and log.txt (second example)

コンテンツ ファイルに対する contentFiles 要素の使用Using the contentFiles element for content files

NuGet 4.0 以降で、PackageReference を使用している場合NuGet 4.0+ with PackageReference

既定では、パッケージはコンテンツを contentFiles フォルダーに配置し (下記参照)、nuget pack は既定の属性を使ってそのフォルダーにすべてのファイルを格納します。By default, a package places content in a contentFiles folder (see below) and nuget pack included all files in that folder using default attributes. この場合は、contentFiles ノードを .nuspec に含める必要はまったくありません。In this case it's not necessary to include a contentFiles node in the .nuspec at all.

含まれるファイルを制御するには、含めるファイルを厳密に示す <files> 要素のコレクションである <contentFiles> 要素を指定します。To control which files are included, the <contentFiles> element specifies is a collection of <files> elements that identify the exact files include.

これらのファイルは、プロジェクト システム内でのファイルの使用方法が記述されている属性のセットで指定されます。These files are specified with a set of attributes that describe how they should be used within the project system:

属性Attribute 説明Description
includeinclude (必須) 含める 1 つまたは複数のファイルの場所。exclude 属性によって指定される除外の対象になります。(Required) The location of the file or files to include, subject to exclusions specified by the exclude attribute. 絶対パスを指定しない限り、パスは .nuspec ファイルが基準になります。The path is relative to the .nuspec file unless an absolute path is specified. ワイルドカード文字 * を使うことができ、2 個のワイルドカード ** は再帰的なフォルダー検索を意味します。The wildcard character * is allowed, and the double wildcard ** implies a recursive folder search.
excludeexclude src の場所から除外するファイルまたはファイル パターンをセミコロンで区切ったリスト。A semicolon-delimited list of files or file patterns to exclude from the src location. ワイルドカード文字 * を使うことができ、2 個のワイルドカード ** は再帰的なフォルダー検索を意味します。The wildcard character * is allowed, and the double wildcard ** implies a recursive folder search.
buildActionbuildAction MSBuild のコンテンツ項目に割り当てるビルド アクション。ContentNoneEmbedded ResourceCompile などです。既定値は、Compile です。The build action to assign to the content item for MSBuild, such as Content, None, Embedded Resource, Compile, etc. The default is Compile.
copyToOutputcopyToOutput 出力フォルダーのコンテンツ項目、ビルドをコピーする (または発行) するかどうかを示すブール値。A Boolean indicating whether to copy content items to the build (or publish) output folder. 既定値は false です。The default is false.
flattenflatten コンテンツ項目をビルド出力の単一フォルダーにコピーするか (true)、それともパッケージのフォルダー構造を保持するか (false) を示すブール値。A Boolean indicating whether to copy content items to a single folder in the build output (true), or to preserve the folder structure in the package (false). このフラグは、copyToOutput が true に設定されている場合のみ機能します。This flag only works when copyToOutput flag is set to true. 既定値は false です。The default is false.

パッケージをインストールするとき、NuGet は <contentFiles> の子要素を上から下に順番に適用します。When installing a package, NuGet applies the child elements of <contentFiles> from top to bottom. 複数のエントリが同じファイルに一致する場合は、すべてのエントリが適用されます。If multiple entries match the same file then all entries are applied. 同じ属性に対して競合がある場合は、最上位のエントリが下位のエントリを上書きします。The top-most entry overrides the lower entries if there is a conflict for the same attribute.

パッケージ フォルダーの構造Package folder structure

パッケージ プロジェクトでは、次のパターンを使ってコンテンツを構成する必要があります。The package project should structure content using the following pattern:

/contentFiles/{codeLanguage}/{TxM}/{any?}
  • codeLanguages には、csvbfsany、または指定された $(ProjectLanguage) に相当する小文字表現を指定できます。codeLanguages may be cs, vb, fs, any, or the lowercase equivalent of a given $(ProjectLanguage)
  • TxM は、NuGet がサポートする任意の有効なターゲット フレームワーク モニカーです (「ターゲット フレームワーク」を参照)。TxM is any legal target framework moniker that NuGet supports (see Target frameworks).
  • この構文の末尾に、任意のフォルダー構造を追加できます。Any folder structure may be appended to the end of this syntax.

例えば:For example:

Language- and framework-agnostic:
    /contentFiles/any/any/config.xml

net45 content for all languages
    /contentFiles/any/net45/config.xml

C#-specific content for net45 and up
    /contentFiles/cs/net45/sample.cs

空のフォルダーでは、. を使って、言語と TxM の特定の組み合わせにコンテンツを提供しないようにすることができます。次はその例です。Empty folders can use . to opt out of providing content for certain combinations of language and TxM, for example:

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

contentFiles セクションの例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/ -->
    <files include="cs/**/*.png" buildAction="EmbeddedResource" />

    <!-- Copy config.xml to the root of the output folder -->
    <files include="cs/uap/config/config.xml" buildAction="None" copyToOutput="true" flatten="true" />

    <!-- Copy run.cmd to the output folder and keep the directory structure -->
    <files include="cs/commands/run.cmd" buildAction="None" copyToOutput="true" flatten="false" />

    <!-- Include everything in the scripts folder except exe files -->
    <files include="cs/net45/scripts/*" exclude="**/*.exe"  buildAction="None" copyToOutput="true" />
</contentFiles>

.nuspec ファイルの例Example .nuspec files

依存関係またはファイルを指定しない単純な .nuspecA simple .nuspec 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>

依存関係を含む .nuspecA .nuspec with 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" version="1.0.0" />
        </dependencies>
    </metadata>
</package>

ファイルを含む .nuspecA .nuspec with 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>

フレームワーク アセンブリを含む .nuspecA .nuspec with 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>

この例では、指定したプロジェクト ターゲットに次のものがインストールされます。In this example, the following are installed for specific project targets:

  • .NET4 -> System.WebSystem.Net.NET4 -> System.Web, System.Net
  • .NET4 Client Profile -> System.Net.NET4 Client Profile -> System.Net
  • Silverlight 3 -> System.JsonSilverlight 3 -> System.Json
  • Silverlight 4 -> System.Windows.Controls.DomainServicesSilverlight 4 -> System.Windows.Controls.DomainServices
  • WindowsPhone -> Microsoft.Devices.SensorsWindowsPhone -> Microsoft.Devices.Sensors