nuget.exe CLI を使用してパッケージを作成するCreate a package using the nuget.exe CLI

パッケージの動作やそれに含まれているコードに関係なく、CLI ツールのいずれか (nuget.exe または dotnet.exe) を使用して、他の開発者が何人でも共有して使用できるコンポーネントにその機能をパッケージ化できます。No matter what your package does or what code it contains, you use one of the CLI tools, either nuget.exe or dotnet.exe, to package that functionality into a component that can be shared with and used by any number of other developers. NuGet CLI ツールをインストールするには、「NuGet クライアント ツールのインストール」をご覧ください。To install NuGet CLI tools, see Install NuGet client tools. Visual Studio に CLI ツールが自動的に含まれることはないことにご注意ください。Note that Visual Studio does not automatically include a CLI tool.

技術的には、NuGet パッケージは .nupkg 拡張子で名前が変更された ZIP ファイルに過ぎません。コンテンツは特定の規則に一致します。Technically speaking, a NuGet package is just a ZIP file that's been renamed with the .nupkg extension and whose contents match certain conventions. このトピックでは、そのような規則に一致するパッケージの作成過程について説明します。This topic describes the detailed process of creating a package that meets those conventions.

パッケージ化は、コンパイルされたコード (アセンブリ)、シンボル、パッケージとして届けるその他のファイルで始まります (「Overview and workflow」 (概要とワークフロー) を参照してください)。Packaging begins with the compiled code (assemblies), symbols, and/or other files that you want to deliver as a package (see Overview and workflow). このプロセスは、パッケージに入るファイルのコンパイル (またはコンパイル以外の方法による生成) とは関係ありません。ただし、パッケージ ファイルの情報を引き出し、コンパイル済みアセンブリとパッケージの同期を維持することはできます。This process is independent from compiling or otherwise generating the files that go into the package, although you can draw from information in a project file to keep the compiled assemblies and packages in sync.

重要

このトピックは、非 SDK スタイルのプロジェクト、つまり通常は、Visual Studio 2017 以降のバージョンと NuGet 4.0 以降を使った .NET Core および .NET Standard プロジェクト以外のプロジェクトを対象としています。This topic applies to non-SDK-style projects, typically projects other than .NET Core and .NET Standard projects using Visual Studio 2017 and higher versions and NuGet 4.0+.

パッケージ化するアセンブリを決定するDecide which assemblies to package

ほとんどの汎用パッケージには、他の開発者が自分のプロジェクトで使用できるアセンブリが 1 つまたは複数含まれています。Most general-purpose packages contain one or more assemblies that other developers can use in their own projects.

  • 一般的に、各アセンブリが他に依存せずに有用であれば、NuGet パッケージあたりアセンブリを 1 つにすることが最善です。In general, it's best to have one assembly per NuGet package, provided that each assembly is independently useful. たとえば、Utilities.dllParser.dll に依存し、Parser.dll がそれ自体で有用であれば、それぞれに 1 つパッケージを作成します。For example, if you have a Utilities.dll that depends on Parser.dll, and Parser.dll is useful on its own, then create one package for each. それにより、開発者は Utilities.dll に依存せず Parser.dll を使用できます。Doing so allows developers to use Parser.dll independently of Utilities.dll.

  • 非依存では有用でない複数のアセンブリからライブラリが構成される場合、それらを組み合わせて 1 つのパッケージを作成できます。If your library is composed of multiple assemblies that aren't independently useful, then it's fine to combine them into one package. 前の例を使えば、Utilities.dll でのみ使用されるコードが Parser.dll に含まれる場合、同じパッケージで Parser.dll を維持できます。Using the previous example, if Parser.dll contains code that's used only by Utilities.dll, then it's fine to keep Parser.dll in the same package.

  • 同様に、Utilities.dllUtilities.resources.dll に依存し、後者がそれ自体で有用ではない場合、両方を同じパッケージに入れます。Similarly, if Utilities.dll depends on Utilities.resources.dll, where again the latter is not useful on its own, then put both in the same package.

リソースは、実際には特殊なケースです。Resources are, in fact, a special case. プロジェクトにパッケージをインストールするとき、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 (see Creating localized packages). そのため、避けなければ不可欠なパッケージ コードが含まれてしまうファイルには .resources.dll を使わないようにします。For this reason, avoid using .resources.dll for files that otherwise contain essential package code.

ライブラリに COM 相互運用アセンブリが含まれる場合は、COM 相互運用アセンブリを含むパッケージの作成に関するページに記載されている追加ガイドラインに従ってください。If your library contains COM interop assemblies, follow additional the guidelines in Create packages with COM interop assemblies.

.nuspec ファイルのロールと構造The role and structure of the .nuspec file

パッケージ化するファイルがわかったら、次の手順は、.nuspec XML ファイルでパッケージ マニフェストを作成することです。Once you know what files you want to package, the next step is creating a package manifest in a .nuspec XML file.

マニフェスト:The manifest:

  1. パッケージの内容を説明し、それ自体、パッケージに含まれます。Describes the package's contents and is itself included in the package.
  2. パッケージの作成を推進し、パッケージをプロジェクトにインストールする方法を NuGet に指示します。Drives both the creation of the package and instructs NuGet on how to install the package into a project. たとえば、マニフェストは他の依存関係を特定します。それにより、NuGet はメイン パッケージのインストール時にそのような依存関係もインストールできます。For example, the manifest identifies other package dependencies such that NuGet can also install those dependencies when the main package is installed.
  3. 下の説明のように、必須プロパティと任意プロパティの両方が含まれます。Contains both required and optional properties as described below. ここにはない他のプロパティなど、詳しくは、.nuspec リファレンスをご覧ください。For exact details, including other properties not mentioned here, see the .nuspec reference.

必須プロパティ:Required properties:

  • パッケージの識別子。パッケージをホストするギャラリー全体で一意にする必要があります。The package identifier, which must be unique across the gallery that hosts the package.
  • Major.Minor.Patch[-Suffix] という形式の特別なバージョン番号。 -Suffixプレリリース版を識別します。A specific version number in the form Major.Minor.Patch[-Suffix] where -Suffix identifies pre-release versions
  • ホスト (nuget.org など) に表示されるパッケージ タイトル。The package title as it should appear on the host (like nuget.org)
  • 作成者と所有者の情報。Author and owner information.
  • パッケージの詳しい説明。A long description of the package.

共通の任意プロパティ:Common optional properties:

次は典型的な .nuspec ファイルです (ただし、架空のものです)。プロパティを説明するコメントが付いています。The following is a typical (but fictitious) .nuspec file, with comments describing the properties:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
    <metadata>
        <!-- The identifier that must be unique within the hosting gallery -->
        <id>Contoso.Utility.UsefulStuff</id>

        <!-- The package version number that is used when resolving dependencies -->
        <version>1.8.3-beta</version>

        <!-- Authors contain text that appears directly on the gallery -->
        <authors>Dejana Tesic, Rajeev Dey</authors>

        <!-- 
            Owners are typically nuget.org identities that allow gallery
            users to easily find other packages by the same owners.  
        -->
        <owners>dejanatc, rjdey</owners>
        
         <!-- Project URL provides a link for the gallery -->
        <projectUrl>http://github.com/contoso/UsefulStuff</projectUrl>

         <!-- License information is displayed on the gallery -->
        <license type="expression">Apache-2.0</license>
        

        <!-- The icon is used in Visual Studio's package manager UI -->
        <iconUrl>http://github.com/contoso/UsefulStuff/nuget_icon.png</iconUrl>

        <!-- 
            If true, this value prompts the user to accept the license when
            installing the package. 
        -->
        <requireLicenseAcceptance>false</requireLicenseAcceptance>

        <!-- Any details about this particular release -->
        <releaseNotes>Bug fixes and performance improvements</releaseNotes>

        <!-- 
            The description can be used in package manager UI. Note that the
            nuget.org gallery uses information you add in the portal. 
        -->
        <description>Core utility functions for web applications</description>

        <!-- Copyright information -->
        <copyright>Copyright ©2016 Contoso Corporation</copyright>

        <!-- Tags appear in the gallery and can be used for tag searches -->
        <tags>web utility http json url parsing</tags>

        <!-- Dependencies are automatically installed when the package is installed -->
        <dependencies>
            <dependency id="Newtonsoft.Json" version="9.0" />
        </dependencies>
    </metadata>

    <!-- A readme.txt to display when the package is installed -->
    <files>
        <file src="readme.txt" target="" />
    </files>
</package>

依存関係の宣言とバージョン番号の指定の詳細については、「packages.config 参照」と「パッケージのバージョン管理」を参照してください。For details on declaring dependencies and specifying version numbers, see packages.config and Package versioning. パッケージで直接、依存関係からアセットを表面化させることもできます。dependency 要素で include 属性と exclude 属性を使用します。It is also possible to surface assets from dependencies directly in the package by using the include and exclude attributes on the dependency element. .nuspec リファレンスの依存関係をご覧ください。See .nuspec Reference - Dependencies.

マニフェストはそれから作成されたパッケージに含まれるため、既存のパッケージを調べることで追加の例をいくつも見つけることができます。Because the manifest is included in the package created from it, you can find any number of additional examples by examining existing packages. 探す場所としては、コンピューターの "グローバル パッケージ" フォルダーが適しています。この場所は次のコマンドで返されます。A good source is the global-packages folder on your computer, the location of which is returned by the following command:

nuget locals -list global-packages

package\version フォルダーに進み、.nupkg ファイルを .zip ファイルにコピーし、その .zip ファイルを開き、その中の .nuspec を調べます。Go into any package\version folder, copy the .nupkg file to a .zip file, then open that .zip file and examine the .nuspec within it.

注意

Visual Studio プロジェクトから .nuspec を作成すると、マニフェストに含まれるトークンは、パッケージのビルド時、プロジェクトからの情報で置換されます。When creating a .nuspec from a Visual Studio project, the manifest contains tokens that are replaced with information from the project when the package is built. Visual Studio プロジェクトから .nuspec を作成する」を参照してください。See Creating the .nuspec from a Visual Studio project.

.nuspec ファイルの作成Create the .nuspec file

完全なマニフェストの作成は、一般的に、次のいずれかの方法で生成された基本 .nuspec ファイルで始まります。Creating a complete manifest typically begins with a basic .nuspec file generated through one of the following methods:

最終パッケージの厳密な内容が説明されるように、ファイルを手作業で編集します。You then edit the file by hand so that it describes the exact content you want in the final package.

重要

生成された .nuspec ファイルに含まれるプレースホルダーは、nuget pack コマンドでパッケージを作成する前に変更する必要があります。Generated .nuspec files contain placeholders that must be modified before creating the package with the nuget pack command. .nuspec にプレースホルダーが含まれる場合、このコマンドは失敗します。That command fails if the .nuspec contains any placeholders.

規則ベースの作業ディレクトリからFrom a convention-based working directory

NuGet パッケージは .nupkg 拡張子で名前が変更されている ZIP ファイルに過ぎないため、多くの場合、ローカルのファイル システムに必要なフォルダー構造を作り、その構造から .nuspec ファイルを直接作成するのが最も簡単です。Because a NuGet package is just a ZIP file that's been renamed with the .nupkg extension, it's often easiest to create the folder structure you want on your local file system, then create the .nuspec file directly from that structure. nuget pack コマンドはその後、そのフォルダー構造にすべてのファイルを自動的に追加します。ただし、. で始まるフォルダーを除きます。同じ構造にプライベート ファイルを維持できます。The nuget pack command then automatically adds all files in that folder structure (excluding any folders that begin with ., allowing you to keep private files in the same structure).

この手法の長所は、パッケージに含めるファイルをマニフェストに指定する必要がないことです (このトピックの後半で説明します)。The advantage to this approach is that you don't need to specify in the manifest which files you want to include in the package (as explained later in this topic). パッケージに入るまさにそのフォルダー構造をビルド プロセスで生成させることができます。また、その他の方法ではプロジェクトに含まれないことがある他のファイルを簡単に含めることができます。You can simply have your build process produce the exact folder structure that goes into the package, and you can easily include other files that might not be part of a project otherwise:

  • ターゲット プロジェクトに挿入する必要があるコンテンツとソース コード。Content and source code that should be injected into the target project.
  • Powershell スクリプトPowerShell scripts
  • プロジェクトの既存の構成とソース コード ファイルへの変換。Transformations to existing configuration and source code files in a project.

フォルダー規則は次のとおりです。The folder conventions are as follows:

フォルダーFolder 説明Description パッケージ インストール時のアクションAction upon package install
(ルート)(root) ReadMe.txt の場所Location for readme.txt Visual Studio では、パッケージのインストール時に ReadMe.txt ファイルが表示されます。Visual Studio displays a readme.txt file in the package root when the package is installed.
lib/{tfm}lib/{tfm} 指定されたターゲット フレームワーク モニカー (TFM) のアセンブリ (.dll)、ドキュメント (.xml)、シンボル (.pdb)Assembly (.dll), documentation (.xml), and symbol (.pdb) files for the given Target Framework Moniker (TFM) アセンブリはランタイムに加えてコンパイル時にも参照として追加されます。.xml.pdb はプロジェクト フォルダーにコピーされます。Assemblies are added as references for compile as well as runtime; .xml and .pdb copied into project folders. フレームワーク ターゲット固有のサブフォルダーを作成するには、「複数のターゲット フレームワークのサポート」を参照してください。See Supporting multiple target frameworks for creating framework target-specific sub-folders.
ref/{tfm}ref/{tfm} 指定したターゲット フレームワーク モニカー (TFM) のアセンブリ (.dll) およびシンボル (.pdb) ファイルAssembly (.dll), and symbol (.pdb) files for the given Target Framework Moniker (TFM) アセンブリはコンパイル時にのみ参照として追加されます。したがって、プロジェクトの bin フォルダーには何もコピーされません。Assemblies are added as references only for compile time; So nothing will be copied into project bin folder.
runtimesruntimes アーキテクチャ固有のアセンブリ (.dll)、シンボル (.pdb)、ネイティブ リソース (.pri) ファイルArchitecture-specific assembly (.dll), symbol (.pdb), and native resource (.pri) files アセンブリはランタイムでのみ参照として追加されます。その他のファイルはプロジェクト フォルダーにコピーされます。Assemblies are added as references only for runtime; other files are copied into project folders. 対応するコンパイル時のアセンブリを指定するために、対応する (TFM) AnyCPU 固有のアセンブリが常に /ref/{tfm} フォルダーの下にあります。There should always be a corresponding (TFM) AnyCPU specific assembly under /ref/{tfm} folder to provide corresponding compile time assembly. 複数のターゲット フレームワークのサポート」を参照してください。See Supporting multiple target frameworks.
contentcontent 任意のファイルArbitrary files コンテンツはプロジェクト ルートにコピーされます。Contents are copied to the project root. コンテンツ フォルダーは最終的にパッケージを使用するターゲット アプリケーションのルートであると考えてください。Think of the content folder as the root of the target application that ultimately consumes the package. パッケージでアプリケーションの /images フォルダーに画像が追加されるようにするには、パッケージの content/images フォルダーにそれを置きます。To have the package add an image in the application's /images folder, place it in the package's content/images folder.
buildbuild (3.x+) MSBuild の .targets ファイルと .props ファイル(3.x+) MSBuild .targets and .props files プロジェクトに自動的に挿入されます。Automatically inserted into the project.
buildMultiTargetingbuildMultiTargeting (4.0+) MSBuild の .targets ファイルと .props ファイル (フレームワーク間でのターゲット設定用)(4.0+) MSBuild .targets and .props files for cross-framework targeting プロジェクトに自動的に挿入されます。Automatically inserted into the project.
buildTransitivebuildTransitive (5.0 以降) 任意の使用するフォルダーに推移的にフローする MSBuild の .targets および .props ファイル。(5.0+) MSBuild .targets and .props files that flow transitively to any consuming project. 機能に関するページをご覧ください。See the feature page. プロジェクトに自動的に挿入されます。Automatically inserted into the project.
toolstools Powershell のスクリプトとプログラムにはパッケージ マネージャー コンソールからアクセスできます。Powershell scripts and programs accessible from the Package Manager Console tools フォルダーはパッケージ マネージャー コンソールだけの PATH 環境変数に追加されます (厳密に言うと、プロジェクトのビルド時に MSBuild に設定される PATH にではありません)。The tools folder is added to the PATH environment variable for the Package Manager Console only (Specifically, not to the PATH as set for MSBuild when building the project).

フォルダー構造には、任意の数のターゲット フレームワークに対して任意の数のアセンブリを含めることができるため、複数のフレームワークをサポートするパッケージの作成時、この方法は必須となります。Because your folder structure can contain any number of assemblies for any number of target frameworks, this method is necessary when creating packages that support multiple frameworks.

いずれの場合でも、必要なフォルダー構造を配置したら、そのフォルダーで次のコマンドを実行し、.nuspec ファイルを作成します。In any case, once you have the desired folder structure in place, run the following command in that folder to create the .nuspec file:

nuget spec

繰り返しになりますが、生成された .nuspec には、フォルダー構造のファイルに対する明示的な参照が含まれません。Again, the generated .nuspec contains no explicit references to files in the folder structure. NuGet は、パッケージが作成されるとき、すべてのファイルを自動的に含めます。NuGet automatically includes all files when the package is created. ただし、マニフェストのその他の部分でプレースホルダー値を編集する必要があります。You still need to edit placeholder values in other parts of the manifest, however.

アセンブリ DLL からFrom an assembly DLL

単純にアセンブリからパッケージを作成する場合、次のコマンドを使用し、アセンブリでメタデータから .nuspec ファイルを生成できます。In the simple case of creating a package from an assembly, you can generate a .nuspec file from the metadata in the assembly using the following command:

nuget spec <assembly-name>.dll

このフォームを使用すると、マニフェストのいくつかのプレースホルダーがアセンブリからの具体的な値で置換されます。Using this form replaces a few placeholders in the manifest with specific values from the assembly. たとえば、<id> プロパティはアセンブリ名に設定され、<version> はアセンブリ バージョンに設定されます。For example, the <id> property is set to the assembly name, and <version> is set to the assembly version. しかしながら、マニフェストの他のプロパティには、アセンブリのそれに該当する値が与えられず、引き続きプレースホルダーが含まれます。Other properties in the manifest, however, don't have matching values in the assembly and thus still contain placeholders.

Visual Studio プロジェクトからFrom a Visual Studio project

.csproj または .vbproj ファイルから .nuspec を作成する方法が便利です。これらのプロジェクトにインストールされているその他のパッケージが依存関係として自動的に参照されるためです。Creating a .nuspec from a .csproj or .vbproj file is convenient because other packages that have been installed into those project are automatically referenced as dependencies. プロジェクト ファイルと同じフォルダーで次のコマンドを使用します。Simply use the following command in the same folder as the project file:

# Use in a folder containing a project file <project-name>.csproj or <project-name>.vbproj
nuget spec

結果的に生成される <project-name>.nuspec ファイルには、パッケージ化のときにプロジェクトからの値で置換されるトークンが含まれます。他のパッケージが既にインストールされている場合、その参照が含まれます。The resulting <project-name>.nuspec file contains tokens that are replaced at packaging time with values from the project, including references to any other packages that have already been installed.

.nuspec にパッケージの依存関係を含める場合は、代わりに nuget pack を使い、生成された .nupkg ファイル内から .nuspec ファイルを取得します。If you have package dependencies to include in the .nuspec, instead use nuget pack, and get the .nuspec file from within the generated .nupkg file. たとえば、次のコマンドを使用します。For example, use the following command.

# Use in a folder containing a project file <project-name>.csproj or <project-name>.vbproj
nuget pack myproject.csproj

トークンは、プロジェクト プロパティの両側で $ 記号によって区切られます。A token is delimited by $ symbols on both sides of the project property. たとえば、この方法で生成されるマニフェストの <id> 値は通常、次のように表示されます。For example, the <id> value in a manifest generated in this way typically appears as follows:

<id>$id$</id>

このトークンは、パッケージ化のとき、プロジェクト ファイルからの AssemblyName 値で置換されます。This token is replaced with the AssemblyName value from the project file at packing time. プロジェクト値と .nuspec トークンのマッピングについては、置換トークンの参照に関するトピックを参照してください。For the exact mapping of project values to .nuspec tokens, see the Replacement Tokens reference.

トークンを利用することで、プロジェクトを更新するとき、.nuspec のバージョン番号などの重要な値を自分で更新する必要がなくなります。Tokens relieve you from needing to update crucial values like the version number in the .nuspec as you update the project. (必要であれば、トークンはいつでもリテラル値に変更できます。)(You can always replace the tokens with literal values, if desired).

この後の「nuget パックを実行し、.nupkg ファイルを生成する」で説明するように、Visual Studio プロジェクトから作業するとき、いくつかの追加パッケージ化オプションを利用できます。Note that there are several additional packaging options available when working from a Visual Studio project, as described in Running nuget pack to generate the .nupkg file later on.

ソリューションレベル パッケージSolution-level packages

NuGet 2.x のみ。NuGet 3.0+ では利用できません。NuGet 2.x only. Not available in NuGet 3.0+.

NuGet 2.x では、パッケージ マネージャー コンソールのツールまたは追加コマンドをインストールするソリューションレベル パッケージの概念がサポートされました (tools フォルダーのコンテンツ)。しかしながら、参照、コンテンツ、またはソリューションのプロジェクトに対するビルド カスタマイズは追加されません。NuGet 2.x supported the notion of a solution-level package that installs tools or additional commands for the Package Manager Console (the contents of the tools folder), but does not add references, content, or build customizations to any projects in the solution. このようなパッケージのその直接の libcontentbuild フォルダーにはファイルは含まれておらず、その依存関係の libcontentbuild フォルダーにもファイルは含まれていません。Such packages contain no files in its direct lib, content, or build folders, and none of its dependencies have files in their respective lib, content, or build folders.

NuGet は、プロジェクトの packages.config ファイルではなく、.nuget フォルダーの packages.config ファイルで、インストールされたソリューションレベル パッケージを追跡記録します。NuGet tracks installed solution-level packages in a packages.config file in the .nuget folder, rather than the project's packages.config file.

新しいファイルと既定値New file with default values

次のコマンドでは、プレースホルダーを含む既定のマニフェストが作成されます。それにより、適切なファイル構造で始められます。The following command creates a default manifest with placeholders, which ensures you start with the proper file structure:

nuget spec [<package-name>]

<package-name> を省略した場合、結果的に生成されるファイルは Package.nuspec になります。If you omit <package-name>, the resulting file is Package.nuspec. Contoso.Utility.UsefulStuff のような名前を指定すると、ファイルは Contoso.Utility.UsefulStuff.nuspec になります。If you provide a name such as Contoso.Utility.UsefulStuff, the file is Contoso.Utility.UsefulStuff.nuspec.

結果的に生成される .nuspec には、projectUrl のような値のプレースホルダーが含まれます。The resulting .nuspec contains placeholders for values like the projectUrl. 必ずファイルを編集してからそれを利用し、最終的な .nupkg ファイルを作成してください。Be sure to edit the file before using it to create the final .nupkg file.

一意のパッケージ識別子を選択し、バージョン番号を設定するChoose a unique package identifier and setting the version number

パッケージ識別子 (<id> 要素) とバージョン番号 (<version> 要素) は、パッケージに含まれるコードを一意に識別するため、マニフェストの中で最も重要な値です。The package identifier (<id> element) and the version number (<version> element) are the two most important values in the manifest because they uniquely identify the exact code that's contained in the package.

パッケージ識別子のベスト プラクティス:Best practices for the package identifier:

  • 一意性:この識別子は、nuget.org 全体で、あるいはパッケージをホストするギャラリー全体で一意になる必要があります。Uniqueness: The identifier must be unique across nuget.org or whatever gallery hosts the package. 識別子を決める前に、該当するギャラリーを検索し、その名前が既に使用されていないか確認してください。Before deciding on an identifier, search the applicable gallery to check if the name is already in use. 競合を避けるために、Contoso. のように、識別子の最初の部分に会社の名前を使用することが適しているパターンです。To avoid conflicts, a good pattern is to use your company name as the first part of the identifier, such as Contoso..
  • 名前空間のような名前:.NET の名前空間に似たパターンに従います。ハイフンの代わりにドット表記を使います。Namespace-like names: Follow a pattern similar to namespaces in .NET, using dot notation instead of hyphens. たとえば、Contoso-Utility-UsefulStuffContoso_Utility_UsefulStuff ではなく Contoso.Utility.UsefulStuff を使用します。For example, use Contoso.Utility.UsefulStuff rather than Contoso-Utility-UsefulStuff or Contoso_Utility_UsefulStuff. パッケージ識別子がコードで使用される名前空間と一致すれば、利用者にとっても便利です。Consumers also find it helpful when the package identifier matches the namespaces used in the code.
  • サンプル パッケージ:別のパッケージの使用方法を示すサンプル コードのパッケージを生成する場合、Contoso.Utility.UsefulStuff.Sample のように、識別子にサフィックスとして .Sample を付けます。Sample Packages: If you produce a package of sample code that demonstrates how to use another package, attach .Sample as a suffix to the identifier, as in Contoso.Utility.UsefulStuff.Sample. (サンプル パッケージは、もちろん、他のパッケージに依存します。)サンプル パッケージを作成するとき、前述のように、規則ベースの作業ディレクトリを使用します。(The sample package would of course have a dependency on the other package.) When creating a sample package, use the convention-based working directory method described earlier. content フォルダーで、\Samples\Contoso.Utility.UsefulStuff.Sample のように、\Samples\<identifier> という名前のフォルダーにサンプル コードを配置します。In the content folder, arrange the sample code in a folder called \Samples\<identifier> as in \Samples\Contoso.Utility.UsefulStuff.Sample.

パッケージ バージョンのベスト プラクティス:Best practices for the package version:

  • 必須ではありませんが、一般的に、ライブラリに合わせてパッケージの番号を設定します。In general, set the version of the package to match the library, though this is not strictly required. これはパッケージを 1 つのアセンブリに限定すれば簡単なことです。「パッケージ化するアセンブリを決定する」を参照してください。This is a simple matter when you limit a package to a single assembly, as described earlier in Deciding which assemblies to package. 概して、NuGet 自体は依存関係の解決時、パッケージ バージョンを使います。アセンブリ バージョンではありません。Overall, remember that NuGet itself deals with package versions when resolving dependencies, not assembly versions.
  • 非標準のバージョン スキーマを使用するとき、「パッケージのバージョン管理」で説明するように、NuGet バージョン管理ルールを検討してください。When using a non-standard version scheme, be sure to consider the NuGet versioning rules as explained in Package versioning.

バージョン管理の理解には、次の一連のブログ投稿が役立ちます。The following series of brief blog posts are also helpful to understand versioning:

ReadMe とその他のファイルの追加Add a readme and other files

パッケージに含めるファイルを直接指定するには、.nuspec ファイルの <files> ノードを使用します。このノードは <metadata> タグの後に入りますTo directly specify files to include in the package, use the <files> node in the .nuspec file, which follows the <metadata> tag:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
    <metadata>
    <!-- ... -->
    </metadata>
    <files>
        <!-- Add a readme -->
        <file src="readme.txt" target="" />

        <!-- Add files from an arbitrary folder that's not necessarily in the project -->
        <file src="..\..\SomeRoot\**\*.*" target="" />
    </files>
</package>

ヒント

規則ベースの作業ディレクトリ手法を利用するとき、ReadMe.txt をパッケージ ルートに、content フォルダーにその他のコンテンツを配置できます。When using the convention-based working directory approach, you can place the readme.txt in the package root and other content in the content folder. マニフェストで必須の <file> 要素はありません。No <file> elements are necessary in the manifest.

パッケージ ルートに readme.txt という名前のファイルを含めると、Visual Studio では、パッケージを直接インストールした直後、そのファイルの内容がプレーンテキストとして表示されます。When you include a file named readme.txt in the package root, Visual Studio displays the contents of that file as plain text immediately after installing the package directly. (パッケージが依存関係としてインストールされた場合、ReadMe ファイルは表示されません。)(Readme files are not displayed for packages installed as dependencies). たとえば、HtmlAgilityPack パッケージの ReadMe は次のように表示されます。For example, here's how the readme for the HtmlAgilityPack package appears:

インストール時の NuGet パッケージの ReadMe ファイルの表示

注意

.nuspec ファイルに空の <files> ノードを含める場合、NuGet では、lib フォルダーの内容以外の内容はパッケージに入りません。If you include an empty <files> node in the .nuspec file, NuGet doesn't include any other content in the package other than what's in the lib folder.

パッケージに MSBuild プロパティとターゲットを含めるInclude MSBuild props and targets in a package

ビルド時のカスタム ツールまたはプロセスの実行など、場合によっては、パッケージを使用するプロジェクト内のカスタム ビルド ターゲットまたはプロパティを追加する必要があります。In some cases, you might want to add custom build targets or properties in projects that consume your package, such as running a custom tool or process during build. これは、プロジェクトの \build フォルダー内に形式 <package_id>.targets または <package_id>.props で (Contoso.Utility.UsefulStuff.targets のように) ファイルを配置することで行います。You do this by placing files in the form <package_id>.targets or <package_id>.props (such as Contoso.Utility.UsefulStuff.targets) within the \build folder of the project.

ルート \build フォルダーのファイルは、すべてのターゲット フレームワークで適切であると見なされます。Files in the root \build folder are considered suitable for all target frameworks. ファイルをフレームワーク固有にするには、次のように、まず、適切なサブフォルダーにそのファイルを配置します。To provide framework-specific files, first place them within appropriate subfolders, such as the following:

\build
    \netstandard1.4
        \Contoso.Utility.UsefulStuff.props
        \Contoso.Utility.UsefulStuff.targets
    \net462
        \Contoso.Utility.UsefulStuff.props
        \Contoso.Utility.UsefulStuff.targets

次に .nuspec ファイルで、<files> ノードのそれらのファイルを参照するようにします。Then in the .nuspec file, be sure to refer to these files in the <files> node:

<?xml version="1.0"?>
<package >
    <metadata minClientVersion="2.5">
    <!-- ... -->
    </metadata>
    <files>
        <!-- Include everything in \build -->
        <file src="build\**" target="build" />

        <!-- Other files -->
        <!-- ... -->
    </files>
</package>

NuGet 2.5 で、パッケージに MSBuild のプロパティとターゲットを含めることができるようになりました。そのため、metadata 要素に minClientVersion="2.5" 属性を追加して、パッケージを使用するために必要な最小限の NuGet クライアント バージョンを示すことをお勧めします。Including MSBuild props and targets in a package was introduced with NuGet 2.5, therefore it is recommended to add the minClientVersion="2.5" attribute to the metadata element, to indicate the minimum NuGet client version required to consume the package.

NuGet で \build ファイルを使用してパッケージをインストールすると、.targets ファイルと .props ファイルを指す MSBuild <Import> 要素がプロジェクト ファイルに追加されます。When NuGet installs a package with \build files, it adds MSBuild <Import> elements in the project file pointing to the .targets and .props files. (.props はプロジェクト ファイルの一番上に、.targets は一番下に追加されます。)別個の条件付き MSBuild <Import> 要素が、各ターゲット フレームワークに追加されます。(.props is added at the top of the project file; .targets is added at the bottom.) A separate conditional MSBuild <Import> element is added for each target framework.

相互フレームワーク ターゲットの MSBuild .props および .targets ファイルは、\buildMultiTargeting フォルダーに配置できます。MSBuild .props and .targets files for cross-framework targeting can be placed in the \buildMultiTargeting folder. パッケージ インストール時に、NuGet は対応する <Import> 要素を条件付きのプロジェクト ファイルに追加します。その際、ターゲット フレームワークは設定されません (MSBuild プロパティ $(TargetFramework) は必ず空になっています)。During package installation, NuGet adds the corresponding <Import> elements to the project file with the condition, that the target framework is not set (the MSBuild property $(TargetFramework) must be empty).

NuGet 3.x を使用する場合、ターゲットはプロジェクトに追加されず、代わりに {projectName}.nuget.g.targets{projectName}.nuget.g.props を通じて使用できます。With NuGet 3.x, targets are not added to the project but are instead made available through {projectName}.nuget.g.targets and {projectName}.nuget.g.props.

nuget パックを実行し、.nupkg ファイルを生成するRun nuget pack to generate the .nupkg file

アセンブリまたは規則ベースの作業ディレクトリを使用するとき、自分の .nuspec ファイルで nuget pack を実行してパッケージを作成します。<project-name> を特定のファイル名で置換します。When using an assembly or the convention-based working directory, create a package by running nuget pack with your .nuspec file, replacing <project-name> with your specific filename:

nuget pack <project-name>.nuspec

Visual Studio プロジェクトを使用するとき、自分のプロジェクト ファイルで nuget pack を実行します。それにより、プロジェクトの .nuspec ファイルが自動的に読み込まれ、その中にトークンがあれば、プロジェクト ファイルの値を利用して置換されます。When using a Visual Studio project, run nuget pack with your project file, which automatically loads the project's .nuspec file and replaces any tokens within it using values in the project file:

nuget pack <project-name>.csproj

注意

トークンを置換するには、プロジェクト ファイルを直接使用する必要があります。プロジェクトがトークン値のソースであるからです。Using the project file directly is necessary for token replacement because the project is the source of the token values. .nuspec ファイルで nuget pack を使用する場合、トークンは置換されません。Token replacement does not happen if you use nuget pack with a .nuspec file.

いずれの場合も、nuget pack では、.git.hg のようなピリオドで始まるフォルダーは除外されます。In all cases, nuget pack excludes folders that start with a period, such as .git or .hg.

NuGet では、修正が必要なエラーが .nuspec ファイルで見つかった場合、それが示されます。マニフェストのプレースホルダー値を変更し忘れたなどです。NuGet indicates if there are any errors in the .nuspec file that need correcting, such as forgetting to change placeholder values in the manifest.

nuget pack が成功すると、.nupkg ファイルが生成されます。「パッケージの公開」に説明があるように、このファイルを適切なギャラリーに公開できます。Once nuget pack succeeds, you have a .nupkg file that you can publish to a suitable gallery as described in Publishing a Package.

ヒント

作成後のパッケージを調べる便利な方法は、パッケージ エクスプローラー ツールでそれを開くことです。A helpful way to examine a package after creating it is to open it in the Package Explorer tool. パッケージの内容とそのマニフェストがグラフィック表示されます。This gives you a graphical view of the package contents and its manifest. 生成された .nupkg ファイルの名前を .zip ファイルに変更し、その内容を直接調べることもできます。You can also rename the resulting .nupkg file to a .zip file and explore its contents directly.

追加オプションAdditional options

nuget pack ではさまざまなコマンドライン スイッチを使用できます。ファイルを除外したり、マニフェストのバージョン番号をオーバーライドしたり、出力フォルダーを変更したりできます。You can use various command-line switches with nuget pack to exclude files, override the version number in the manifest, and change the output folder, among other features. 完全な一覧は、pack コマンドに関するページを参照してください。For a complete list, refer to the pack command reference.

Visual Studio プロジェクトの共通オプションには以下のようなものがあります。The following options are a few that are common with Visual Studio projects:

  • 参照されるプロジェクト:プロジェクトが他のプロジェクトを参照する場合、参照されるプロジェクトをパッケージの一部あるいは依存関係として追加できます。-IncludeReferencedProjects オプションを使用します。Referenced projects: If the project references other projects, you can add the referenced projects as part of the package, or as dependencies, by using the -IncludeReferencedProjects option:

    nuget pack MyProject.csproj -IncludeReferencedProjects
    

    この包含プロセスは再帰的です。MyProject.csproj が B と C を参照し、それらのプロジェクトが D、E、F を参照する場合、B、C、D、E、F からのファイルがパッケージに含まれます。This inclusion process is recursive, so if MyProject.csproj references projects B and C, and those projects reference D, E, and F, then files from B, C, D, E, and F are included in the package.

    参照されるプロジェクトにそれ自体の .nuspec ファイルが含まれる場合、NuGet では、その参照されるプロジェクトが依存関係として追加されます。If a referenced project includes a .nuspec file of its own, then NuGet adds that referenced project as a dependency instead. そのプロジェクトを個別にパッケージ化し、公開する必要があります。You need to package and publish that project separately.

  • ビルド構成:既定では、NuGet では、プロジェクト ファイルに設定されている既定のビルド構成が使用されます。一般的には、"デバッグ" です。Build configuration: By default, NuGet uses the default build configuration set in the project file, typically Debug. リリースなど、別のビルド構成からファイルをパッケージ化するには、構成と共に -properties オプションを使用します。To pack files from a different build configuration, such as Release, use the -properties option with the configuration:

    nuget pack MyProject.csproj -properties Configuration=Release
    
  • シンボル: 利用者がデバッガーでパッケージ コードをステップ実行することを可能にするシンボルを含めるには、-Symbols オプションを使用します。Symbols: to include symbols that allow consumers to step through your package code in the debugger, use the -Symbols option:

    nuget pack MyProject.csproj -symbols
    

パッケージ インストールのテストTest package installation

パッケージを公開する前に、通常、パッケージをプロジェクトにインストールするプロセスをテストします。Before publishing a package, you typically want to test the process of installing a package into a project. このテストにより、必要なファイルがすべて、プロジェクト内の適切な場所に入ります。The tests make sure that the necessarily files all end up in their correct places in the project.

インストールは Visual Studio またはコマンド ラインで手動テストできます。通常のパッケージ インストール手順を利用します。You can test installations manually in Visual Studio or on the command line using the normal package installation steps.

自動テストの基本プロセスは次のようになります。For automated testing, the basic process is as follows:

  1. .nupkg ファイルをローカル フォルダーにコピーします。Copy the .nupkg file to a local folder.
  2. nuget sources add -name <name> -source <path> コマンドを利用し、パッケージ ソースにフォルダーを追加します (nuget ソースを参照してください)。Add the folder to your package sources using the nuget sources add -name <name> -source <path> command (see nuget sources). 指定されたコンピューターのいずれかで、このローカル ソースを 1 回設定します。Note that you need only set this local source once on any given computer.
  3. nuget install <packageID> -source <name> を利用し、そのソースからパッケージをインストールします。<name> は、nuget sources に指定されたソースの名前に一致します。Install the package from that source using nuget install <packageID> -source <name> where <name> matches the name of your source as given to nuget sources. ソースを指定することで、そのソースだけからパッケージがインストールされます。Specifying the source ensures that the package is installed from that source alone.
  4. ファイル システムで、ファイルが正しくインストールされていることを調べます。Examine your file system to check that files are installed correctly.

次の手順Next Steps

.nupkg ファイルとなるパッケージを作成したら、「パッケージの公開」の説明にあるように、選択したギャラリーにパッケージを公開できます。Once you've created a package, which is a .nupkg file, you can publish it to the gallery of your choice as described on Publishing a Package.

パッケージの機能を拡張したり、次のトピックで説明するように、その他の方法で他のシナリオをサポートしたりすると便利な場合があります。You might also want to extend the capabilities of your package or otherwise support other scenarios as described in the following topics:

最後になりますが、次のような種類のパッケージもあります。Finally, there are additional package types to be aware of: