.nuspec リファレンス
.nuspec
ファイルは、パッケージのメタデータが含まれている XML マニフェストです。 このマニフェストは、パッケージを作成するためと、コンシューマーに情報を提供するための、両方に使われます。 パッケージにはマニフェストが常に含まれています。
このトピックの内容は以下のとおりです。
- 一般的な形式とスキーマ
- 置換トークン (Visual Studio プロジェクトで使われるとき)
- 依存関係
- 明示的なアセンブリ参照
- フレームワーク アセンブリ参照
- アセンブリ ファイルを含める
- コンテンツ ファイルを含める
- nuspec ファイルの例
packages.config
を使用するSDK スタイル以外のプロジェクト でnuget.exe pack
とともに.nuspec
を使用します。.nuspec
SDK スタイルのプロジェクト (通常は、SDK 属性を使用する .NET Core および .NET Standard プロジェクト) のパッケージを作成するためにファイルは不要)。 (.nuspec
はパッケージの作成時に生成されることに注意してください)dotnet.exe pack
かmsbuild pack target
を使用してパッケージを作成する場合、.nuspec
ファイル内にあるすべてのプロパティ を、プロジェクト ファイルに含めることをお勧めします。 ただし、代わりに.nuspec
ファイルをdotnet.exe
かmsbuild pack target
を使用してパック可能です。packages.config
からPackageReferenceに移行されたプロジェクトの場合、パッケージを作成するために.nuspec
ファイルは必要ありません。 代わりに、msbuild -t:pack を使用します。
nuspec.xsd
スキーマ ファイルは、NuGet GitHub リポジトリにあります。
このファイルは、.nuspec
ファイルの最新のスキーマのみを表します。
正式に発行されたバージョンは存在せず、特定の NuGet バージョンに対応するそのファイルのバージョンもありません。
このスキーマでの .nuspec
ファイルの一般的な形式は次のとおりです。
<?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 スキーマ エクスプローラー] リンクをクリックします。 または、コードとしてファイルを開き、エディター内を右クリックして、[XML スキーマ エクスプローラーで表示] を選びます。 どちらの方法でも次のように表示されます (ほとんどを展開した場合)。
.nuspec ファイル内のすべての XML 要素名前は、XML 全般の場合と同様に、大文字と小文字の区別があります。 例えば、メタデータ要素 <description>
の使用は正しく、 <Description>
正しくありません。 各要素名の適切な大文字と小文字を次に示します。
重要
.nuspec
ファイルにはスキーマへの参照 (xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd"
) が含まれていますが、NuGet-Team がスキーマの自動検証に使用できるスキーマ ファイルを発行することはありません。
以下の要素はパッケージの最低要件であり、メタデータの省略可能な要素を追加してパッケージに関する開発者の全体的なエクスペリエンスを向上させることを検討する必要があります。
これらの要素は、<metadata>
要素内で指定する必要があります。
パッケージの識別子。大文字と小文字が区別されます。nuget.org 全体で、またはパッケージが存在するギャラリー全体で、一意である必要があります。 ID は、スペースまたは URL で無効な文字を含んでいてはならず、一般に .NET 名前空間の規則に従います。 ガイダンスについては、一意のパッケージ識別子の選択に関するページをご覧ください。
パッケージを nuget.org にアップロードする場合、 id
フィールドは 128 文字に制限されます。
パッケージのバージョン。major.minor.patch のパターンに従います。 「Package versioning」(パッケージのバージョン管理) で説明されているように、バージョン番号にはプレリリースのサフィックスを含めることができます。
パッケージを nuget.org にアップロードする場合、 version
フィールドは 64 文字に制限されます。
UI ディスプレイ用のパッケージの説明。
パッケージを nuget.org にアップロードする場合、 description
フィールドは 4,000 文字に制限されます。
パッケージ作成者のコンマ区切りのリスト。
パッケージを nuget.org にアップロードする場合、nuspec の authors
と owners
は無視されます。nuget.org でパッケージの所有権を設定する方法については、「nuget.org でのパッケージ所有者の管理」をご覧ください。
重要
所有者は非推奨です。 代わりに編集者を使用します。
パッケージ所有者のコンマ区切りのリスト。
nuspec の owners
は、パッケージを nuget.org にアップロードするときに無視されます。nuget.org でパッケージの所有権を設定する方法については、「nuget.org でのパッケージ所有者の管理」をご覧ください。
パッケージのホーム ページの URL。多くの場合、UI 画面と nuget.org に表示されます。
パッケージを nuget.org にアップロードする場合、 projectUrl
フィールドは 4,000 文字に制限されます。
重要
licenseUrl は非推奨です。 代わりにライセンスを使用してください。
パッケージのライセンスの URL。通常、nuget.org のようなUI 画面に表示されます。
パッケージを nuget.org にアップロードする場合、 licenseUrl
フィールドは 4,000 文字に制限されます。
NuGet 4.9.0 以降で対応しています。
パッケージ内のライセンス ファイルへの SPDX ライセンス式またはパス。たいていはnuget.org などの UI に表示されます。MIT や BSD-2-Clause などの共通ライセンスでパッケージのライセンスを取得する場合は、関連付けられている SPDX ライセンス識別子を使用します。 次に例を示します。
<license type="expression">MIT</license>
注意
NuGet.org で受け入れられるのは、オープンソースイニシアティブまたはFree ソフトウェア財団によって承認されたライセンスのライセンス式のみです。
パッケージが複数の共通ライセンスでライセンスされている場合は、SPDX 式構文バージョン 2.0 を使用して複合ライセンスを指定できます。 次に例を示します。
<license type="expression">BSD-2-Clause OR MIT</license>
ライセンス式で対応していないカスタム ライセンスを使用する場合は、ライセンスのテキストを含む .txt
または.md
ファイルをパッケージ化できます。 次に例を示します。
<package>
<metadata>
...
<license type="file">LICENSE.txt</license>
...
</metadata>
<files>
...
<file src="licenses\LICENSE.txt" target="" />
...
</files>
</package>
MSBuild 同等項目については、ライセンス式またはライセンスファイルのパッキングを参照してください。
NuGetライセンス式のEXACT構文については、ABNF をご覧ください。
license-id = <short form license identifier from https://spdx.org/spdx-specification-21-web-version#h.luq9dgcle9mo>
license-exception-id = <short form license exception identifier from https://spdx.org/spdx-specification-21-web-version#h.ruv3yl8g6czd>
simple-expression = license-id / license-id”+”
compound-expression = 1*1(simple-expression /
simple-expression "WITH" license-exception-id /
compound-expression "AND" compound-expression /
compound-expression "OR" compound-expression ) /
"(" compound-expression ")" )
license-expression = 1*1(simple-expression / compound-expression / UNLICENSED)
重要
iconUrl は非推奨です。 代わりにアイコンだけを使用する。
UI ディスプレイでパッケージのアイコンとして使われる、背景効果が透過的な128x128Imageの URL。 この要素の値は、"画像を直接示す URL" であり、画像を含む Web ページの URL ではないことに注意してください。 例えば、GitHub のイメージを使用するには、https://github.com/<username>/<repository>/raw/<branch>/<logo.png>などの AW ファイル の URL を使用します。
パッケージを nuget.org にアップロードする場合、 iconUrl
フィールドは 4,000 文字に制限されます。
NuGet 5.3.0 以降で対応しています。
パッケージ内のイメージ ファイルへのパスであり、パッケージ アイコンとして nuget.org などの UI に表示されることがよくあります。 画像ファイルのサイズは 1 MB (メガバイト)に制限されています。 対応しているファイル形式: JPEG、PNG。 画像の解像度は 128 x 128 にすることをお勧めします。
例えば、nuget.exe を使用してパッケージを作成するときに、nuspec に次のコードを追加します。
<package>
<metadata>
...
<icon>images\icon.png</icon>
...
</metadata>
<files>
...
<file src="..\icon.png" target="images\" />
...
</files>
</package>
MSBuild と同等の場合は、「アイコン イメージ ファイルのパッキング」を参照してください。
ヒント
まだサポートicon
していないクライアントとソースとの下位互換性メイン維持するには、両方icon
を指定しますiconUrl
。 Visual Studio では、 icon
フォルダー ベースのソースからのパッケージに対応する。
NuGet 5.10.0 プレビュー 2 以降で対応しています。
readme ファイルをパックする場合は、要素を readme
使用して、パッケージのrootを基準としたパッケージ パスを指定する必要があります。 これに加えて、ファイルがパッケージに含まれていることを確認する必要があります。 対応しているファイル形式には、Markdown (.md) のみが含まれます。
例えば、readme ファイルをプロジェクトにパックするために、nuspec に次のコードを追加します。
<package>
<metadata>
...
<readme>docs\readme.md</readme>
...
</metadata>
<files>
...
<file src="..\readme.md" target="docs\" />
...
</files>
</package>
同等の MSBuild については、「Readme ファイルのパッキング」を参照してください。
パッケージをインストールする前にクライアントがユーザーに対してパッケージのライセンスへの同意を求めるプロンプトを表示する必要があるかどうかを示すブール値。
(2.8 以降) 開発専用の依存関係としてパッケージをマークするかどうかを指定するブール値。指定すると、そのパッケージは他のパッケージに依存関係として含まれなくなります。 PackageReference (NuGet 4.8 以降) では、このフラグは、コンパイルからコンパイル時アセットを除外することも意味します。 パッケージリファレンスの開発依存関係サポートをご覧ください。
重要
summary
は現在非推奨になっています。 代わりに description
を使用してください
UI 画面用のパッケージの短い説明。 省略すると、description
を切り詰めたバージョンが使われます。
パッケージを nuget.org にアップロードする場合、 summary
フィールドは 4,000 文字に制限されます。
(1.5 以降) このリリースのパッケージで行われた変更の説明。Visual Studio パッケージ マネージャーの [更新] タブなどの UI で、パッケージの説明の代わりによく使われます。
パッケージを nuget.org にアップロードする場合、 releaseNotes
フィールドは 35,000 文字に制限されます。
(1.5 以降) パッケージの著作権の詳細。
パッケージを nuget.org にアップロードする場合、 copyright
フィールドは 4,000 文字に制限されます。
パッケージのロケール ID。 「ローカライズされたパッケージの作成」をご覧ください。
パッケージについて説明し、検索やフィルターでパッケージを見つけやすくするタグやキーワードを、スペースで区切って列記したリスト。
パッケージを nuget.org にアップロードする場合、 tags
フィールドは 4,000 文字に制限されます。
(3.3 以降) NuGet 内部でのみ使われます。
4 つの省略可能な属性 type
と url
(4.0 以降)、branch
と commit
(4.6 以降) で構成されるリポジトリ メタデータ。 これらの属性を使用すると、それを構築したリポジトリにマップ .nupkg
でき、個々のブランチ名と同じ詳細を取得したり、パッケージをビルドした SHA-1 ハッシュをコミットしたりすることができます。 これは、バージョン管理ソフトウェアによって直接呼び出すことができる、公開されている URL である必要があります。 これはコンピューター用であるため、HTML ページにすることはできません。 プロジェクト ページにリンクするには、代わりにprojectUrl
フィールドを使用します。
次に例を示します。
<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
<metadata>
...
<repository type="git" url="https://github.com/NuGet/NuGet.Client.git" branch="dev" commit="e1c65e4524cd70ee6e22abe33e6cb6ec73938cb3" />
...
</metadata>
</package>
パッケージを nuget.org にアップロードする場合、 type
属性は 100 文字に制限され、 url
属性は 4,000 文字に制限されます。
一部の UI ディスプレイで使用できる人間に優しいパッケージのタイトル。 (nuget.org と Visual Studio のパッケージ マネージャーにタイトルが表示されない)
パッケージを nuget.org にアップロードする場合、 title
フィールドは 256 文字に制限されますが、表示目的には使用されません。
(3.5 以降) 従来の依存関係パッケージ以外の場合に、パッケージの種類を指定する 0 個以上の <packageType>
要素のコレクション。 各 packageType は、name 属性と version 属性を持っています。 「Setting a package type」(パッケージの種類の設定) をご覧ください。
パッケージの依存関係を指定する 0 個以上の <dependency>
要素のコレクション。 各 dependency は、id、version、include (3.x 以降)、exclude (3.x 以降) の各属性を持っています。 後の「依存関係」をご覧ください。
(1.2 以降) このパッケージで必要な .NET Framework アセンブリ参照を示す 0 個以上の <frameworkAssembly>
要素のコレクション。パッケージを使うプロジェクトに参照が確実に追加されるようにします。 各 frameworkAssembly は、assemblyName 属性と targetFramework 属性を持っています。 フレームワーク アセンブリ参照 GAC の指定に関する後の説明をご覧ください。
(1.5 以降) パッケージの lib
フォルダー内のアセンブリのうちプロジェクト参照として追加するものを指定する、0 個以上の <reference>
要素のコレクション。 各参照は、file 属性を持っています。 <references>
は <group>
要素を含むこともでき、その targetFramework 属性に <reference>
要素を含めることができます。 省略すると、lib
のすべての参照が含まれます。 明示的なアセンブリ参照の指定に関する後の説明をご覧ください。
(3.3 以降) 使用する側のプロジェクトに含めるコンテンツ ファイルを示す <files>
要素のコレクション。 これらのファイルは、プロジェクト システム内でのファイルの使用方法が記述されている属性のセットで指定されます。 パッケージに含めるファイルの指定に関する後の説明をご覧ください。
<package>
ノードでは、<metadata>
の兄弟として <files>
Nodeを追加するか、または <metadata>
の子として <contentFiles>
を追加して、パッケージに含めるアセンブリと内容ファイルを包含できます。 詳しくは、このトピックで後述する「アセンブリ ファイルを含める」と「コンテンツ ファイルを含める」をご覧ください。
nuget.exe および Visual Studio パッケージ マネージャーで強制する、このパッケージをインストールできる NuGet クライアントの最小バージョンを指定します。 これは、NuGet クライアントの特定のバージョンで追加された .nuspec
ファイルの特定の機能にパッケージが依存しているときに、常に使われます。 例えば、developmentDependency
属性を使っているパッケージでは、minClientVersion
に "2.8" を指定する必要があります。 同様に、contentFiles
要素 (次のセクションを参照) を使っているパッケージでは、minClientVersion
を "3.3" に設定する必要があります。 また、バージョン 2.5 より前の NuGet クライアントはこのフラグを認識しないので、minClientVersion
の値が何であっても、"常に" パッケージをインストールしないことにも注意してください。
<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
<metadata minClientVersion="100.0.0.1">
<id>dasdas</id>
<version>2.0.0</version>
<title />
<authors>dsadas</authors>
<owners />
<requireLicenseAcceptance>false</requireLicenseAcceptance>
<description>My package description.</description>
</metadata>
<files>
<file src="content\one.txt" target="content\one.txt" />
</files>
</package>
パッケージを作成するとき、nuget pack
コマンドは、.nuspec
ファイルの <metadata>
とpack
ノード内の $ で区切られたトークンを、プロジェクト ファイルまたは <files>
コマンドの-properties
スイッチで指定されている値に置き換えます。
コマンド ラインでは、nuget pack -properties <name>=<value>;<name>=<value>
でトークンの値を指定します。 例えば、.nuspec
では $owners$
や $desc$
などのトークンを使っておき、パッキング時に次のようにして値を指定できます。
nuget pack MyProject.csproj -properties
owners=janedoe,harikm,kimo,xiaop;desc="Awesome app logger utility"
プロジェクトの値を使うには、次の表で説明するトークンを指定します (AssemblyInfo は、Properties
内の AssemblyInfo.cs
や AssemblyInfo.vb
などのファイルを参照します)。
これらのトークンを使うには、nuget pack
を実行するときに、.nuspec
だけでなくプロジェクト ファイルも指定します。 例えば、次のコマンドを使うと、.nuspec
ファイルの $id$
および $version$
トークンが、プロジェクトの AssemblyName
および AssemblyVersion
の値に置き換えられます。
nuget pack MyProject.csproj
通常、プロジェクトがある場合は、最初に nuget spec MyProject.csproj
を使って .nuspec
を作成すると、一部の標準的なトークンが自動的に追加されます。 ただし、.nuspec
の必須要素に対する値がプロジェクトにないと、nuget pack
は失敗します。 さらに、プロジェクトの値を変更する場合は、パッケージを作成する前に必ずビルドし直してください。これは、pack コマンドの build
スイッチで簡単に行うことができます。
例外である $configuration$
を除き、コマンド ラインの同じトークンに割り当てられている値より、プロジェクトの値の方が優先的に使われます。
Token | 値ソース | Value |
---|---|---|
$id$ | プロジェクト ファイル | プロジェクト ファイルの AssemblyName (タイトル) |
$version$ | AssemblyInfo | ある場合は AssemblyInformationalVersion、ない場合は AssemblyVersion |
$author$ | AssemblyInfo | AssemblyCompany |
$title$ | AssemblyInfo | AssemblyTitle |
$description$ | AssemblyInfo | AssemblyDescription |
$copyright$ | AssemblyInfo | AssemblyCopyright |
$configuration$ | アセンブリ DLL | アセンブリのビルドに使われる構成。既定値は Debug。 Release 構成を使ってパッケージを作成するには、常にコマンド ラインで -properties Configuration=Release を使うことに注意してください。 |
アセンブリ ファイルおよびコンテンツ ファイルを含めるときは、トークンを使ってパスを解決することもできます。 トークンの名前は MSBuild のプロパティと同じであり、現在のビルド構成に基づいて含めるファイルを選ぶことができます。 例えば、.nuspec
ファイルで次のトークンを使うものとします。
<files>
<file src="bin\$configuration$\$id$.pdb" target="lib\net40" />
</files>
そして、MSBuild で AssemblyName
が LoggingLibrary
であるアセンブリを Release
構成でビルドすると、パッケージ内の .nuspec
ファイルの行は結果として次のようになります。
<files>
<file src="bin\Release\LoggingLibrary.pdb" target="lib\net40" />
</files>
<metadata>
内の <dependencies>
要素は、最上位のパッケージが依存している他のパッケージを示す <dependency>
要素をいくつでも含むことができます。 各 <dependency>
の属性は次にとおりです。
属性 | 説明 |
---|---|
id |
(必須) "EntityFramework" や "NUnit" などの依存関係のパッケージ ID。これはパッケージ ページに表示されるパッケージ nuget.org の名前となります。 |
version |
(必須) 依存関係として許容されるバージョンの範囲。 厳密な構文については、「Package versioning」(パッケージのバージョン管理) をご覧ください。 floatバージョンは未対応。 |
include | 最終的なパッケージに含める依存関係を示す包含/除外タグ (下記参照) のコンマ区切りリスト。 既定値は all です。 |
exclude | 最終的なパッケージから除外する依存関係を示す包含/除外タグ (下記参照) のコンマ区切りリスト。 既定値は、 build,analyzers 過剰に書き込むことができる値です。 ただし、 content/ ContentFiles は、過剰に書き込むことができない最終的なパッケージでも暗黙的に除外されます。 exclude で指定されているタグの方が、include で指定されているタグより優先されます。 例えば、include="runtime, compile" exclude="compile" は include="runtime" と同じです。 |
パッケージを nuget.org にアップロードする場合、各依存関係の id
属性は 128 文字に制限され、 version
属性は 256 文字に制限されます。
包含/除外タグ | ターゲットの影響を受けるフォルダー |
---|---|
contentFiles | コンテンツ |
ランタイム | Runtime、Resources、FrameworkAssemblies |
コンパイル | lib |
build | build (MSBuild のプロパティとターゲット) |
native | native |
なし | フォルダーなし |
すべて | すべてのフォルダー |
例えば、次の行は PackageA
バージョン 1.1.0 以降および PackageB
バージョン 1.x での依存関係を示します。
<dependencies>
<dependency id="PackageA" version="1.1.0" />
<dependency id="PackageB" version="[1,2)" />
</dependencies>
次の行も同じパッケージでの依存関係を示しますが、PackageA
の contentFiles
および build
フォルダーを含めて、PackageB
の native
および compile
フォルダーを除くすべてを含めることを指定します。
<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
結果ファイルに自動的に含まれます。 代わりに、nuget pack myproject.csproj
を使用し、生成された .nupkg ファイルから .nuspec ファイルを取得します。 この .nuspec には依存関係を含む。
バージョン 2.0 以降
1 つのフラット リストの代わりに、<dependencies>
の <group>
要素を使い、ターゲット プロジェクトのフレームワーク プロファイルに従って依存関係を指定できます。
各グループには、targetFramework
という名前の属性があり、0 個以上の <dependency>
要素が含まれます。 ターゲット フレームワークにプロジェクトのフレームワーク プロファイルとの互換性がある場合、これらの依存関係が一緒にインストールされます。
依存関係の既定のリストまたはフォールバック リストとしては、targetFramework
属性のない <group>
要素が使われます。 正確なフレームワーク識別子については、「ターゲット フレームワーク」をご覧ください。
重要
グループの形式をフラット リストと併用することはできません。
注意
lib/ref
フォルダーで使用されるターゲット フレームワーク モニカー (TFM) の形式はdependency groups
で使用される TFM と比較して異なります。 dependencies group
で宣言されたターゲット フレームワークと.nuspec
ファイルのフォルダーが完全一致でないと、pack
コマンドは NuGet 警告 NU5128を発生させます。
次の例では、<group>
要素のさまざまなバリエーションを示します。
<dependencies>
<group>
<dependency id="RouteMagic" version="1.1.0" />
</group>
<group targetFramework=".NETFramework4.7.2">
<dependency id="jQuery" version="1.6.2" />
<dependency id="WebActivator" version="1.4.4" />
</group>
<group targetFramework="netcoreapp3.1">
</group>
</dependencies>
<references>
要素は、パッケージを使うときにターゲットにする プロジェクトがリファレンスする必要のあるアセンブリを明示的に指定するためpackages.config
を使うプロジェクトが使用します。 明示的な参照は、通常、設計時のみのアセンブリに使われます。 詳細については、プロジェクトによってリファレンスされるアセンブリの選択に関するページを参照してください。
例えば、次の <references>
要素は、パッケージに他のアセンブリがある場合でも、xunit.dll
と xunit.extensions.dll
に対する参照だけを追加するよう NuGet に指示します。
<references>
<reference file="xunit.dll" />
<reference file="xunit.extensions.dll" />
</references>
1 つのフラット リストの代わりに、<references>
の <group>
要素を使い、ターゲット プロジェクトのフレームワーク プロファイルに従って参照を指定できます。
各グループには、targetFramework
という名前の属性があり、0 個以上の <reference>
要素が含まれます。 ターゲットのフレームワークにプロジェクトのフレームワーク プロファイルとの互換性がある場合、これらの参照はプロジェクトに追加されます。
参照の既定のリストまたはフォールバック リストとしては、targetFramework
属性のない <group>
要素が使われます。 正確なフレームワーク識別子については、「ターゲット フレームワーク」をご覧ください。
重要
グループの形式をフラット リストと併用することはできません。
次の例では、<group>
要素のさまざまなバリエーションを示します。
<references>
<group>
<reference file="a.dll" />
</group>
<group targetFramework="net45">
<reference file="b45.dll" />
</group>
<group targetFramework="netcore45">
<reference file="bcore45.dll" />
</group>
</references>
フレームワーク アセンブリは、.NET Framework の一部であり、指定されたコンピューターのグローバル アセンブリ キャッシュ (GAC) に既に存在している必要があります。 <frameworkAssemblies>
要素でこれらのアセンブリを指定することにより、プロジェクトに必要な参照がまだない場合であっても、そのような参照をプロジェクトに確実に追加できます。 もちろん、そのようなアセンブリがパッケージに直接含まれることはありません。
<frameworkAssemblies>
要素には 0 個以上の <frameworkAssembly>
要素を含めることができ、それぞれで次の属性を指定します。
属性 | 説明 |
---|---|
assemblyName | (必須) 完全修飾アセンブリ名。 |
targetFramework | (省略可能) この参照を適用するターゲット フレームワークを指定します。 省略した場合は、参照がすべてのフレームワークに適用されることを示します。 正確なフレームワーク識別子については、「ターゲット フレームワーク」をご覧ください。 |
次の例は、System.Net
への参照はすべてのターゲット フレームワークに適用され、System.ServiceModel
への参照は .NET Framework 4.0 のみに適用されることを示します。
<frameworkAssemblies>
<frameworkAssembly assemblyName="System.Net" />
<frameworkAssembly assemblyName="System.ServiceModel" targetFramework="net40" />
</frameworkAssemblies>
「パッケージを作成する」で説明されている規則に従う場合、.nuspec
ファイルでファイルの一覧を明示的に指定する必要はありません。 nuget pack
コマンドが必要なファイルを自動的に選びます。
重要
プロジェクトにパッケージをインストールするとき、NuGet はパッケージの DLL にアセンブリ参照を自動的に追加します。ただし、指定されている .resources.dll
は、ローカライズされたサテライト アセンブリであると見なされるため "除外" されます。 そのため、避けなければ不可欠なパッケージ コードが含まれてしまうファイルには .resources.dll
を使わないようにします。
この自動動作をバイパスして、パッケージに含めるファイルを明示的に制御するには、<files>
要素を <package>
の子要素 (および <metadata>
の兄弟要素) として配置し、各ファイルを個別の <file>
要素で示します。 次に例を示します。
<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>
要素はパッケージのインストール時に変更できないコンテンツ ファイルを含めるためにも使われます。 NuGet 3.3 以降で、PackageReference を使用しているプロジェクトでは、代わりに <contentFiles>
要素が使用されます。 詳しくは、後の「コンテンツ ファイルを含める」をご覧ください。
各 <file>
要素では、次の属性を指定します。
属性 | 説明 |
---|---|
src | 含める 1 つまたは複数のファイルの場所。exclude 属性によって指定される除外の対象になります。 絶対パスを指定しない限り、パスは .nuspec ファイルが基準になります。 ワイルドカード文字 * を使うことができ、2 個のワイルドカード ** は再帰的なフォルダー検索を意味します。 |
ターゲット | ソース ファイルが格納されるパッケージ内のフォルダーへの相対パス。lib 、content 、build 、または tools で始まっている必要があります。 規則に基づく作業ディレクトリからの .nuspec の作成に関するページをご覧ください。 |
exclude | src の場所から除外するファイルまたはファイル パターンをセミコロンで区切ったリスト。 ワイルドカード文字 * を使うことができ、2 個のワイルドカード ** は再帰的なフォルダー検索を意味します。 |
1 つのアセンブリ
Source file:
library.dll
.nuspec entry:
<file src="library.dll" target="lib" />
Packaged result:
lib\library.dll
ターゲット フレームワークに固有の 1 つのアセンブリ
Source file:
library.dll
.nuspec entry:
<file src="assemblies\net40\library.dll" target="lib\net40" />
Packaged result:
lib\net40\library.dll
ワイルドカードを使った DLL のセット
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
異なるフレームワークの DLL
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
ファイルの除外
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)
コンテンツ ファイルは、パッケージでプロジェクトに含める必要がある変更できないファイルです。 変更できないので、それを使うプロジェクトによる変更は意図されていません。 コンテンツ ファイルの例を次に示します。
- リソースとして埋め込まれる画像
- コンパイル済みのソース ファイル
- プロジェクトのビルド出力と共に含まれる必要があるスクリプト
- プロジェクトに含まれる必要はあるが、プロジェクト固有の変更は必要ない、パッケージの構成ファイル
コンテンツ ファイルをパッケージに含めるには、<files>
要素を使い、target
属性で content
フォルダーを指定します。 ただし、PackageReference を使用しているプロジェクトにパッケージをインストールする場合、このようなファイルは無視され、代わりに <contentFiles>
要素が使用されます。
使用する側のプロジェクトとの最大限の互換性のため、パッケージでは両方の要素でコンテンツ ファイルを指定するのが理想的です。
コンテンツ ファイルでは、アセンブリ ファイルの場合と同じ形式を使用しますが、次の例のように、target
属性で基本フォルダーとして content
を指定します。
基本的なコンテンツ ファイル
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
ディレクトリ構造を持つコンテンツ ファイル
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
ターゲット フレームワークに固有のコンテンツ ファイル
Source file:
css\cool\style.css
.nuspec entry
<file src="css\cool\style.css" target="Content" />
Packaged result:
content\style.css
名前のドットでフォルダーにコピーされるコンテンツ ファイル
この場合、NuGet は target
の拡張子が src
の拡張子と一致しないものと判断し、target
での名前のその部分をフォルダーとして扱います。
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
拡張子のないコンテンツ ファイル
拡張子のないファイルを含めるには、ワイルドカード *
または **
を使います。
Source file:
flags\installed
.nuspec entry:
<file src="flags\**" target="flags" />
Packaged result:
flags\installed
深いパスと深いターゲットのコンテンツ ファイル
この場合、ソースとターゲットのファイル拡張子が一致するので、NuGet はターゲットがフォルダーではなくファイル名であると想定します。
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
パッケージ内のコンテンツ ファイルの名前の変更
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
ファイルの除外
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)
NuGet 4.0 以降で、PackageReference を使用している場合
既定では、パッケージはコンテンツを contentFiles
フォルダーに配置し (下記参照)、nuget pack
は既定の属性を使ってそのフォルダーにすべてのファイルを格納します。 この場合は、contentFiles
ノードを .nuspec
に含める必要はまったくありません。
含まれるファイルを制御するには、含めるファイルを厳密に示す <files>
要素のコレクションである <contentFiles>
要素を指定します。
これらのファイルは、プロジェクト システム内でのファイルの使用方法が記述されている属性のセットで指定されます。
属性 | 説明 |
---|---|
include | (必須) 含める 1 つまたは複数のファイルの場所。exclude 属性によって指定される除外の対象になります。 絶対パスを指定しない限り、パスは contentFiles フォルダ―が基準になります。 ワイルドカード文字 * を使うことができ、2 個のワイルドカード ** は再帰的なフォルダー検索を意味します。 |
exclude | src の場所から除外するファイルまたはファイル パターンをセミコロンで区切ったリスト。 ワイルドカード文字 * を使うことができ、2 個のワイルドカード ** は再帰的なフォルダー検索を意味します。 |
buildAction | MSBuild のコンテンツ項目に割り当てるビルド アクション。Content 、None 、Embedded Resource 、Compile などです。デフォルトはCompile 。 |
copyToOutput | ビルド(または公開する)出力フォルダーに内容項目をコピーするかどうかを示すブール値。 既定値は false です。 |
flatten | コンテンツ項目をビルド出力の単一フォルダーにコピーするか (true)、それともパッケージのフォルダー構造を保持するか (false) を示すブール値。 このフラグは、copyToOutput が true に設定されている場合のみ機能します。 既定値は false です。 |
パッケージをインストールするとき、NuGet は <contentFiles>
の子要素を上から下に順番に適用します。 複数のエントリが同じファイルに一致する場合は、すべてのエントリが適用されます。 同じ属性に対して競合がある場合は、最上位のエントリが下位のエントリをオーバーライドします。
パッケージ プロジェクトでは、次のパターンを使ってコンテンツを構成する必要があります。
/contentFiles/{codeLanguage}/{TxM}/{any?}
codeLanguages
には、cs
、vb
、fs
、any
、または指定された$(ProjectLanguage)
に相当する小文字表現を指定できます。TxM
は、NuGet がサポートする任意の有効なターゲット フレームワーク モニカーです (「ターゲット フレームワーク」を参照)。- この構文の末尾に、任意のフォルダー構造を追加できます。
次に例を示します。
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 の特定の組み合わせにコンテンツを提供しないようにすることができます。次はその例です。
/contentFiles/vb/any/code.vb
/contentFiles/cs/any/_._
<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
<metadata>
...
<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>
</metadata>
</package>
バージョン 5.1 以降の wih PackageReference のみ
フレームワークリファレンスは、WPF やWindows フォームなどの共有フレームワークを表す .NET Core の概念です。 共有フレームワークを指定することで、パッケージは、そのフレームワークのすべての依存関係がリファレンス元プロジェクトに確実に含まれるようにします。
各 <group>
要素に targetFramework
属性とゼロ個以上の<frameworkReference>
要素が必要です。
次の例は、.NET Core WPF プロジェクト用に生成された nuspec を示しています。 フレームワークリファレンスを含む nuspec を手動で作成することは推奨されないことに注意してください。 代わりにターゲットパックを使用することを検討してください。このパックはプロジェクトから自動的に推論されます。
<package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
<metadata>
<dependencies>
<group targetFramework=".NETCoreApp3.1" />
</dependencies>
<frameworkReferences>
<group targetFramework=".NETCoreApp3.1">
<frameworkReference name="Microsoft.WindowsDesktop.App.WPF" />
</group>
</frameworkReferences>
</metadata>
</package>
依存関係またはファイルを指定しない単純な .nuspec
<?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>
<license type="expression">MIT</license>
</metadata>
</package>
依存関係を含む .nuspec
<?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>
ファイルを含む .nuspec
<?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>
フレームワーク アセンブリを含む .nuspec
<?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>
この例では、指定したプロジェクト ターゲットに次のものがインストールされます。
- .NET4 ->
System.Web
,System.Net
- .NET4 クライアントプロフィール ->
System.Net
- Silverlight 3 - >
System.Json
- WindowsPhone ->
Microsoft.Devices.Sensors