NuGetNuGet

NuGet は .NET エコシステムのパッケージ マネージャーであり、開発者が .NET オープンソース ライブラリを見つけて入手するための主要な方法です。NuGet is a package manager for the .NET ecosystem and is the primary way developers discover and acquire .NET open-source libraries. NuGet パッケージをホストするために Microsoft が提供している無料サービスの NuGet.org は、パブリック NuGet パッケージのプライマリ ホストですが、MyGet および Azure Artifacts などのカスタム NuGet サービスに公開できます。NuGet.org, a free service provided by Microsoft for hosting NuGet packages, is the primary host for public NuGet packages, but you can publish to custom NuGet services like MyGet and Azure Artifacts.

NuGetNuGet

NuGet パッケージの作成Create a NuGet package

NuGet パッケージ (*.nupkg) は、.NET アセンブリと関連するメタデータを含む zip ファイルです。A NuGet package (*.nupkg) is a zip file that contains .NET assemblies and associated metadata.

NuGet パッケージを作成するには、主な方法が 2 つあります。There are two main ways to create a NuGet package. より新しいお勧めの方法は、SDK 形式のプロジェクト (コンテンツが <Project Sdk="Microsoft.NET.Sdk"> から始まるプロジェクト ファイル) からパッケージを作成することです。The newer and recommended way is to create a package from a SDK-style project (project file whose content starts with <Project Sdk="Microsoft.NET.Sdk">). アセンブリとターゲットが自動的にパッケージに追加され、パッケージ名やバージョン番号などの残りのメタデータが、MSBuild ファイルに追加されます。Assemblies and targets are automatically added to the package and remaining metadata is added to the MSBuild file, like package name and version number. dotnet pack コマンドを使ってコンパイルすると、アセンブリの代わりに *.nupkg ファイルが出力されます。Compiling with the dotnet pack command outputs a *.nupkg file instead of assemblies.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <AssemblyName>Contoso.Api</AssemblyName>
    <PackageVersion>1.1.0</PackageVersion>
    <Authors>John Doe</Authors>
  </PropertyGroup>
</Project>

NuGet パッケージを作成する従来からの方法では、*.nuspec ファイルと nuget.exe コマンドライン ツールを使用します。The older way of creating a NuGet package is with a *.nuspec file and the nuget.exe command-line tool. nuspec ファイルを使用すると、優れた制御を利用できますが、最終的な NuGet パッケージに含めるアセンブリとターゲットを慎重に指定する必要があります。A nuspec file gives you great control but you must carefully specify what assemblies and targets to include in the final NuGet package. 間違えやすいうえに、変更を加える際にユーザーは nuspec の更新を忘れやすいです。It's easy to make a mistake or for someone to forget to update the nuspec when making changes. nuspec の利点は、まだ SDK 形式のプロジェクト ファイルをサポートしていないフレームワークの NuGet パッケージを作成するために使用できることです。The advantage of a nuspec is you can use it create NuGet packages for frameworks that don't yet support an SDK-style project file.

✔️ SDK 形式のプロジェクト ファイルを使用して NuGet パッケージを作成することを検討してください。✔️ CONSIDER using an SDK-style project file to create the NuGet package.

パッケージの依存関係Package dependencies

NuGet パッケージの依存関係については、「Dependencies」 (依存関係) の記事で説明しています。NuGet package dependencies are covered in detail in the Dependencies article.

重要な NuGet パッケージ メタデータImportant NuGet package metadata

NuGet パッケージは、多数のメタデータ プロパティをサポートしています。A NuGet package supports many metadata properties. 次の表に、NuGet.org 上のすべてのパッケージで指定する必要があるコア メタデータを示します。The following table contains the core metadata that every package on NuGet.org should provide:

MSBuild プロパティの名前MSBuild Property name Nuspec の名前Nuspec name 説明Description
PackageId id パッケージ ID。The package identifier. 条件を満たしている場合、ID のプレフィックスは予約できます。A prefix from the identifier can be reserved if it meets the criteria.
PackageVersion version NuGet パッケージ バージョン。NuGet package version. 詳細については、「NuGet package version」(NuGet package version パッケージ バージョン) をご覧ください。For more information, see NuGet package version.
Title title わかりやすいパッケージ タイトル。A human-friendly title of the package. 既定値は PackageId です。It defaults to the PackageId.
Description description UI に表示されるパッケージの長い説明。A long description of the package displayed in UI.
Authors authors パッケージ作成者のコンマで区切りの一覧。nuget.org のプロファイル名と一致します。A comma-separated list of package authors, matching the profile names on nuget.org.
PackageTags tags パッケージを説明するタグとキーワードのスペース区切りの一覧。A space-delimited list of tags and keywords that describe the package. タグは、パッケージを検索するときに使用されます。Tags are used when searching for packages.
PackageIcon icon パッケージ アイコンとして使用するパッケージ内の画像へのパス。A path to an image in the package to use as a package icon. icon メタデータの詳細については、こちらをご覧ください。Read more about icon metadata.
PackageProjectUrl projectUrl プロジェクトのホーム ページまたはソース リポジトリの URL。A URL for the project homepage or source repository.
PackageLicenseExpression license プロジェクト ライセンスの SPDX 識別子The project license's SPDX identifier. OSI と FSF によって承認されたライセンスのみが識別子を使用できます。Only OSI and FSF approved licenses can use an identifier. その他のライセンスでは、PackageLicenseFile を使用する必要があります。Other licenses should use PackageLicenseFile. license メタデータの詳細については、こちらをご覧ください。Read more about license metadata.

重要

ライセンスのないプロジェクトは、排他的な著作権を侵害しているため、他のユーザーが合法的に使用できなくなります。A project without a license defaults to exclusive copyright, making it legally impossible for other people to use.

✔️ NuGet のプレフィックスの予約条件を満たしているプレフィックスを持つ NuGet パッケージ名を選択することを検討してください。✔️ CONSIDER choosing a NuGet package name with a prefix that meets NuGet's prefix reservation criteria.

✔️ パッケージのアイコンに HTTPS href を使用してください。✔️ DO use an HTTPS href to your package icon.

NuGet.org のようなサイトは HTTPS を有効にした状態で実行され、HTTPS ではないイメージを表示すると、コンテンツの混合を示す警告が作成されます。Sites like NuGet.org run with HTTPS enabled and displaying a non-HTTPS image will create a mixed content warning.

✔️ 最良な表示結果になるように、64 x 64 で透明な背景を持つパッケージ アイコン イメージを使用してください。✔️ DO use a package icon image that is 64x64 and has a transparent background for best viewing results.

✔️ ソース リンクを設定して、お使いのアセンブリと NuGet パッケージにソース管理のメタデータを追加することを検討してください。✔️ CONSIDER setting up Source Link to add source control metadata to your assemblies and NuGet package.

ソース リンクによってメタデータの RepositoryUrlRepositoryType が NuGet パッケージに自動的に追加されます。Source Link automatically adds RepositoryUrl and RepositoryType metadata to the NuGet package. また、ソース リンクによって、パッケージの作成元のソース コードに関する情報が追加されます。Source Link also adds information about the exact source code the package was built from. たとえば、Git リポジトリから作成されたパッケージでは、コミット ハッシュがメタデータとして追加されます。For example, a package created from a Git repository will have the commit hash added as metadata.

プレリリース パッケージPre-release packages

バージョン サフィックスがある NuGet パッケージは、プレリリースと見なされます。NuGet packages with a version suffix are considered pre-release. プレリリース パッケージが制限付きユーザーのテスト実行に最適になるように、ユーザーがプレリリース パッケージを選択しない限り、既定では、NuGet パッケージ マネージャーの UI は、安定版リリースを表示します。By default, the NuGet Package Manager UI shows stable releases unless a user opts-in to pre-release packages, making pre-release packages ideal for limited user testing.

<PackageVersion>1.0.1-beta1</PackageVersion>

注意

安定版パッケージは、プレリリース パッケージに依存できません。A stable package cannot depend on a pre-release package. 独自のパッケージをプレリリースにするか、または旧来の安定版バージョンに依存する必要があります。You must either make your own package pre-release or depend on an older stable version.

NuGet プレリリース パッケージの依存関係NuGet pre-release package dependency

✔️ テスト、プレビュー、または実験時には、プレリリース パッケージを公開してください。✔️ DO publish a pre-release package when testing, previewing, or experimenting.

✔️ 他の安定版パッケージから参照できるように、準備ができ次第、安定版パッケージを公開してください。✔️ DO publish a stable package when its ready so other stable packages can reference it.

シンボル パッケージSymbol packages

シンボル ファイル (*.pdb) は、アセンブリと共に .NET コンパイラによって生成されます。Symbol files (*.pdb) are produced by the .NET compiler alongside assemblies. デバッガ―を使用して実行しながらソース コード全体をステップ実行できるように、シンボル ファイルは、実行場所を元のソース コードにマップします。Symbol files map execution locations to the original source code so you can step through source code as it is running using a debugger. NuGet では、.NET アセンブリを含む主要なパッケージと共に、シンボル ファイルを格納している別個のシンボル パッケージ (*.snupkg) の生成をサポートしています。NuGet supports generating a separate symbol package (*.snupkg) containing symbol files alongside the main package containing .NET assemblies. シンボル サーバー上でホストされ、Visual Studio などのツールによってオンデマンドでしかダウンロードできないのが、シンボル パッケージの考え方です。The idea of symbol packages is they're hosted on a symbol server and are only downloaded by a tool like Visual Studio on demand.

NuGet.org は独自のシンボル サーバー リポジトリをホストしています。NuGet.org hosts its own symbols server repository. 開発者は Visual Studio でシンボル ソースhttps://symbols.nuget.org/download/symbols を追加することで NuGet.org シンボル サーバーに公開されたシンボルを使用できます。Developers can use the symbols published to the NuGet.org symbol server by adding https://symbols.nuget.org/download/symbols to their symbol sources in Visual Studio.

重要

NuGet.org シンボル サーバーでは、SDK スタイルのプロジェクトで作成された新しいポータブル シンボル ファイル (*.pdb) のみがサポートされます。The NuGet.org symbol server only supports the new portable symbol files (*.pdb) created by SDK-style projects.

.NET ライブラリのデバッグ時に NuGet.org シンボル サーバーを使用するには、開発者が Visual Studio 2017 バージョン 15.9 以降を持っている必要があります。To use the NuGet.org symbol server when debugging a .NET library, developers must have Visual Studio 2017 version 15.9 or later.

シンボル パッケージを作成する代わりに、主要 NuGet パッケージにシンボル ファイルを埋め込むという方法もあります。An alternative to creating a symbol package is embedding symbol files in the main NuGet package. 主要 NuGet パッケージは大容量になりますが、シンボル ファイルを埋め込む場合、開発者は NuGet.org シンボル サーバーを設定する必要がないことを意味します。The main NuGet package will be larger, but the embedded symbol files means developers don't need to configure the NuGet.org symbol server. SDK 形式のプロジェクトを使用して NuGet パッケージを構築している場合、AllowedOutputExtensionsInPackageBuildOutputFolder プロパティを設定してシンボル ファイルを埋め込むことができます。If you're building your NuGet package using an SDK-style project, then you can embed symbol files by setting the AllowedOutputExtensionsInPackageBuildOutputFolder property:

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
    <!-- Include symbol files (*.pdb) in the built .nupkg -->
    <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
  </PropertyGroup>
</Project>

シンボル ファイルを埋め込むことの短所は、SDK スタイルのプロジェクトでコンパイルした .NET ライブラリの場合、パッケージ サイズが約 30% 増えるということです。The downside of embedding symbol files is that they increase the package size by about 30% for .NET libraries compiled using SDK-style projects. パッケージ サイズが問題であれば、代わりにシンボル パッケージでシンボルを公開してください。If package size is a concern, you should publish symbols in a symbol package instead.

✔️ シンボルをシンボル パッケージ (*.snupkg) として NuGet.org に発行することを検討してください。✔️ CONSIDER publishing symbols as a symbol package (*.snupkg) to NuGet.org

シンボル パッケージ (*.snupkg) は、メイン パッケージのサイズを肥大化させることなく、また NuGet パッケージをデバッグする予定のない人の復元パフォーマンスに影響を及ぼすことなく、オンデマンドの良好なデバッグ エクスペリエンスを開発者に提供します。Symbol packages (*.snupkg) provide developers a good on-demand debugging experience without bloating the main package size and impacting restore performance for those who don't intend to debug the NuGet package.

注意点は、ユーザーが自分の IDE 内で NuGet シンボル サーバーを見つけ、(1 回限りのセットアップとして) 構成し、シンボル ファイルを取得する必要があることです。The caveat is that users may need to find and configure the NuGet symbol server in their IDE (as a one-time setup) to get symbol files. Visual Studio 2019 バージョン 16.1 では、既定のシンボル サーバーの一覧に NuGet.org のシンボル サーバーが追加されました。Visual Studio 2019 version 16.1 added NuGet.org's symbol server to the list of default symbol servers.