.nuspec リファレンス

  • [アーティクル]

.nuspec ファイルは、パッケージのメタデータが含まれている XML マニフェストです。 このマニフェストは、パッケージを作成するためと、コンシューマーに情報を提供するための、両方に使われます。 パッケージにはマニフェストが常に含まれています。

このトピックの内容は以下のとおりです。

プロジェクトの種類の互換性

  • packages.configを使用するSDK スタイル以外のプロジェクト でnuget.exe packとともに.nuspecを使用します。

  • .nuspecSDK スタイルのプロジェクト (通常は、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 ファイルの一般的な形式は次のとおりです。

<?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 スキーマ エクスプローラーで表示] を選びます。 どちらの方法でも次のように表示されます (ほとんどを展開した場合)。

Visual Studio Schema Explorer with nuspec.xsd open

.nuspec ファイル内のすべての XML 要素名前は、XML 全般の場合と同様に、大文字と小文字の区別があります。 例えば、メタデータ要素 <description> の使用は正しく、 <Description> 正しくありません。 各要素名の適切な大文字と小文字を次に示します。

メタデータの必須要素

以下の要素はパッケージの最低要件であり、メタデータの省略可能な要素を追加してパッケージに関する開発者の全体的なエクスペリエンスを向上させることを検討する必要があります。

これらの要素は、<metadata> 要素内で指定する必要があります。

ID

パッケージの識別子。大文字と小文字が区別されます。nuget.org 全体で、またはパッケージが存在するギャラリー全体で、一意である必要があります。 ID は、スペースまたは URL で無効な文字を含んでいてはならず、一般に .NET 名前空間の規則に従います。 ガイダンスについては、一意のパッケージ識別子の選択に関するページをご覧ください。

パッケージを nuget.org にアップロードする場合、 id フィールドは 128 文字に制限されます。

version

パッケージのバージョン。major.minor.patch のパターンに従います。 「Package versioning」(パッケージのバージョン管理) で説明されているように、バージョン番号にはプレリリースのサフィックスを含めることができます。

パッケージを nuget.org にアップロードする場合、 version フィールドは 64 文字に制限されます。

description

UI ディスプレイ用のパッケージの説明。

パッケージを nuget.org にアップロードする場合、 description フィールドは 4,000 文字に制限されます。

authors

nuget.org のプロフィール名と一致するパッケージ作成者のコンマ区切りのリスト。これらは、nuget.org の NuGet ギャラリーに表示され、同じ作成者によるパッケージの相互参照に使用されます。

パッケージを nuget.org にアップロードする場合、 authors フィールドは 4,000 文字に制限されます。

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

owners

重要

所有者は非推奨のです。 代わりに編集者を使用します。

nuget.org でプロフィール名を使用するパッケージ作成者のコンマ区切りのリスト。これは多くの場合、authorsと同じリストであり、パッケージを nuget.org にアップロードする場合は無視されます。nuget.org でのパッケージ所有者の管理を参照してください。

projectUrl

パッケージのホーム ページの URL。多くの場合、UI 画面と nuget.org に表示されます。

パッケージを nuget.org にアップロードする場合、 projectUrl フィールドは 4,000 文字に制限されます。

licenseUrl

重要

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>

Note

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

重要

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>

パッケージ アイコンの nuspec サンプル。

MSBuild と同等の場合は、「アイコン イメージ ファイルのパッキング」を参照してください。

ヒント

まだサポートiconしていないクライアントとソースとの下位互換性メイン維持するには、両方iconを指定しますiconUrl。 Visual Studio では、 icon フォルダー ベースのソースからのパッケージに対応する。

readme

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 ファイルのパッキング」を参照してください。

requireLicenseAcceptance

パッケージをインストールする前にクライアントがユーザーに対してパッケージのライセンスへの同意を求めるプロンプトを表示する必要があるかどうかを示すブール値。

developmentDependency

(2.8 以降) 開発専用の依存関係としてパッケージをマークするかどうかを指定するブール値。指定すると、そのパッケージは他のパッケージに依存関係として含まれなくなります。 PackageReference (NuGet 4.8 以降) では、このフラグは、コンパイルからコンパイル時アセットを除外することも意味します。 パッケージリファレンスの開発依存関係サポートをご覧ください。

まとめ

重要

summaryは現在非推奨のものです。 代わりに description を使用してください

UI 画面用のパッケージの短い説明。 省略すると、description を切り詰めたバージョンが使われます。

パッケージを nuget.org にアップロードする場合、 summary フィールドは 4,000 文字に制限されます。

releaseNotes

(1.5 以降) このリリースのパッケージで行われた変更の説明。Visual Studio パッケージ マネージャーの [更新] タブなどの UI で、パッケージの説明の代わりによく使われます。

パッケージを nuget.org にアップロードする場合、 releaseNotes フィールドは 35,000 文字に制限されます。

(1.5 以降) パッケージの著作権の詳細。

パッケージを nuget.org にアップロードする場合、 copyright フィールドは 4,000 文字に制限されます。

言語

パッケージのロケール ID。 「ローカライズされたパッケージの作成」をご覧ください。

tags

パッケージについて説明し、検索やフィルターでパッケージを見つけやすくするタグやキーワードを、スペースで区切って列記したリスト。

パッケージを nuget.org にアップロードする場合、 tags フィールドは 4,000 文字に制限されます。

serviceable

(3.3 以降) NuGet 内部でのみ使われます。

repository

4 つの省略可能な属性 typeとurl(4.と+)、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 文字に制限されますが、表示目的には使用されません。

コレクション要素

packageTypes

(3.5 以降) 従来の依存関係パッケージ以外の場合に、パッケージの種類を指定する 0 個以上の <packageType> 要素のコレクション。 各 packageType は、name 属性と version 属性を持っています。 「Setting a package type」(パッケージの種類の設定) をご覧ください。

依存関係

パッケージの依存関係を指定する 0 個以上の <dependency> 要素のコレクション。 各 dependency は、id、version、include (3.x 以降)、exclude (3.x 以降) の各属性を持っています。 後の「依存関係」をご覧ください。

frameworkAssemblies

(1.2 以降) このパッケージで必要な .NET Framework アセンブリ参照を示す 0 個以上の <frameworkAssembly> 要素のコレクション。パッケージを使うプロジェクトに参照が確実に追加されるようにします。 各 frameworkAssembly は、assemblyName 属性と targetFramework 属性を持っています。 フレームワーク アセンブリ参照 GAC の指定に関する後の説明をご覧ください。

references

(1.5 以降) パッケージの lib フォルダー内のアセンブリのうちプロジェクト参照として追加するものを指定する、0 個以上の <reference> 要素のコレクション。 各参照は、file 属性を持っています。 <references> は <group> 要素を含むこともでき、その targetFramework 属性に <reference> 要素を含めることができます。 省略すると、lib のすべての参照が含まれます。 明示的なアセンブリ参照の指定に関する後の説明をご覧ください。

contentFiles

(3.3 以降) 使用する側のプロジェクトに含めるコンテンツ ファイルを示す <files> 要素のコレクション。 これらのファイルは、プロジェクト システム内でのファイルの使用方法が記述されている属性のセットで指定されます。 パッケージに含めるファイルの指定に関する後の説明をご覧ください。

files

<package> ノードでは、<metadata> の兄弟として <files> Nodeを追加するか、または <metadata> の子として <contentFiles> を追加して、パッケージに含めるアセンブリと内容ファイルを包含できます。 詳しくは、このトピックで後述する「アセンブリ ファイルを含める」と「コンテンツ ファイルを含める」をご覧ください。

metadata の属性

minClientVersion

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>

Dependencies 要素

<metadata> 内の <dependencies> 要素は、最上位のパッケージが依存している他のパッケージを示す <dependency> 要素をいくつでも含むことができます。 各 <dependency> の属性は次にとおりです。

属性 説明
id (必須) "EntityFramework" や "NUnit" などの依存関係のパッケージ ID。これはパッケージ ページに表示されるパッケージ nuget.org の名前となります。
version (必須) 依存関係として許容されるバージョンの範囲。 厳密な構文については、「Package versioning」(パッケージのバージョン管理) をご覧ください。 floatバージョンは未対応。
include 最終的なパッケージに含める依存関係を示す包含/除外タグ (下記参照) のコンマ区切りリスト。 既定値は all です。
除外 最終的なパッケージから除外する依存関係を示す包含/除外タグ (下記参照) のコンマ区切りリスト。 既定値は、 build,analyzers 過剰に書き込むことができる値です。 ただし、 content/ ContentFiles は、過剰に書き込むことができない最終的なパッケージでも暗黙的に除外されます。 exclude で指定されているタグの方が、include で指定されているタグより優先されます。 例えば、include="runtime, compile" exclude="compile" は include="runtime" と同じです。

パッケージを nuget.org にアップロードする場合、各依存関係の id 属性は 128 文字に制限され、 version 属性は 256 文字に制限されます。

包含/除外タグ ターゲットの影響を受けるフォルダー
contentFiles Content
ランタイム Runtime、Resources、FrameworkAssemblies
compile 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> 要素が使われます。 正確なフレームワーク識別子については、「ターゲット フレームワーク」をご覧ください。

重要

グループの形式をフラット リストと併用することはできません。

Note

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 要素の属性

各 <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> 要素が使用されます。

使用する側のプロジェクトとの最大限の互換性のため、パッケージでは両方の要素でコンテンツ ファイルを指定するのが理想的です。

コンテンツ ファイルに対する files 要素の使用

コンテンツ ファイルでは、アセンブリ ファイルの場合と同じ形式を使用しますが、次の例のように、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)

コンテンツ ファイルに対する contentFiles 要素の使用

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

contentFiles セクションの例

<?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 ファイルの例

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