パッケージ作成のベスト プラクティス

  • [アーティクル]

このガイダンスの目的は、NuGet パッケージの作成者に対して、高品質なパッケージを作成および発行するための簡易なリファレンスを提供することです。 ここでは主に、メタデータやパックなどのパッケージ固有のベスト プラクティスに焦点を当てます。 高品質なライブラリを構築するためのより詳細な提案については、.NET の「オープン ソース ライブラリのガイダンス」を参照してください。

推奨事項の種類

各記事で 4 種類の推奨事項 (実施、検討、回避、実施しない) が提示されます。 推奨事項の種類は、どの程度厳密に従うべきかを示しています。

実施の推奨事項にはほとんど常に従う必要があります。 次に例を示します。

✔️ パッケージの目的について説明する、パッケージの簡単な説明を含めてください。

その一方で、検討の推奨事項には一般に従うべきですが、その規則には正当な例外があります。

✔️ NuGet のプレフィックスの予約条件を満たしているプレフィックスを持つ NuGet パッケージ名を選択することを検討してください。

回避の推奨事項は一般には良いアイデアではありませんが、規則に違反することが効果的である場合があります。

❌ 正確なバージョンを要求する NuGet パッケージ参照は回避してください。

最後に、実施しないの推奨事項は、ほとんどの場合でやってはいけないことを示しています。

❌LicenseUrl メタデータ プロパティは使用しないでください。

NuGet パッケージの作成

NuGet パッケージを作成するために推奨される最新の方法は、SDK スタイルのプロジェクトから作成することです。 ターゲット フレームワークやパッケージ メタデータなど、SDK スタイルのプロジェクトのプロパティは、プロジェクト ファイルに定義されています。

SDK スタイルのプロジェクトからパッケージを作成するには、必要なプロパティを定義し、Visual Studio または dotnet CLI でパックします。

✔️ SDK スタイルのプロジェクトを作成し、Visual Studio または dotnet CLI を使用してパッケージを作成 (パック) してください。

必要なクライアント ツール、プロジェクト ファイルの例、コマンドなど、パッケージの作成に関するより詳細なガイダンスについては、「dotnet CLI を使用して NuGet パッケージを作成する」を参照してください。

どの .NET Framework をターゲットにするか決める際に、クロス プラットフォーム ターゲットに関する最新のガイダンスを参照してください。

パッケージ メタデータ

メタデータは、すべての NuGet パッケージの基本コンポーネントです。 メタデータの品質は、パッケージの見つけやすさ、使いやすさ、および信頼性に大きな影響を与えます。

Visual Studio の場合、パッケージ メタデータを指定するお勧めの方法は、プロジェクト > [プロジェクト名] プロパティ > パッケージにアクセスすることです。

パッケージ メタデータ要素は、プロジェクト ファイルで直接指定することもできます。

次の表に、使用可能なパッケージ メタデータ要素へのマッピングと説明を示します。

Visual Studio のプロパティ名 プロジェクト ファイルまたは MSBuild のプロパティ名 Nuspec のプロパティ名 説明
Package id PackageId id パッケージの名前または識別子。
Package version PackageVersion version NuGet パッケージ バージョン。
Authors Authors authors パッケージ作成者のコンマ区切りのリスト。多くの場合、個人または組織の "わかりやすい名前" を使用します。
Description Description description パッケージの説明。
Copyright Copyright copyright パッケージの著作権の詳細。
Project URL PackageProjectUrl projectUrl プロジェクトのホームページの URL。
Icon File PackageIcon icon パッケージのアイコン画像ファイルへのパス。
README PackageReadmeFile readme パッケージ README マークダウン ファイルへのパス。
Repository URL RepositoryUrl repository url パッケージのビルド元であるリポジトリの URL。
Repository type RepositoryType repository type リポジトリ URL が指しているリポジトリの種類 (つまり "git")。
Tags PackageTags tags パッケージを説明するタグとキーワードのスペース区切りの一覧。 タグは、パッケージを検索するときに使用されます。
Release notes PackageReleaseNotes releaseNotes パッケージの今回のリリースで加えられた変更内容の説明。
Licensing - Expression PackageLicenseExpression license type="expression" SPDX ライセンス式。
Licensing - File PackageLicenseFile license type="file" カスタム ライセンス ファイルへのパス。

パッケージ ID

まったく新しいパッケージを発行する場合:

✔️ NuGet.org において一意かつ既存のパッケージと明確に区別されるパッケージ ID を選択してください。

パッケージ ID が一意で区別可能かどうかを確認するには、NuGet.org でその ID を検索するか、次のリンクが存在するかどうかを確認します: https://www.nuget.org/packages/<パッケージ名>。

✔️ NuGet のプレフィックスの予約条件を満たしているプレフィックスを持つ NuGet パッケージ名を選択することを検討してください。

パッケージのプレフィックス ID を予約すると、検証済みのチェック マークを取得できるようになります。image

詳細については、「パッケージ ID プレフィックスの予約」に関するドキュメントを参照してください。

パッケージのバージョン

✔️ NuGet パッケージのバージョン管理に SemVer を使用することを検討してください。

基本的に、これは Major.Minor.Patch[-prerelease] の形式を使用することを意味します。

✔️ パッケージが非安定版またはプレビュー版の場合は、プレリリース パッケージとして発行してください。

詳細なガイダンスについては、.NET ライブラリのバージョン管理に関するガイドを参照してください。

作者

✔️ 作成者のフィールドは、ユーザーまたはユーザーの組織の "わかりやすい名前" のために使用してください。

たとえば、NuGet.org のユーザー名が "jdoe" である場合、作成者のフィールドに "Jane Doe" を使用すると、コンシューマーがそのユーザーを作成者として認識しやすくなります。 組織の NuGet.org ユーザー名が "ContosoToolkit" である場合、"Contoso Corporation" を使用したほうが認識しやすく、コンシューマーの信頼性が高くなります。

説明

✔️ パッケージについて説明する、短い説明 (最大 4000 文字) を含めてください。

パッケージの説明は、NuGet 検索に表示される最も目立つフィールドの 1 つであり、パッケージが適切かどうかを判断するために、潜在的なコンシューマーが最初に見るものになる可能性が高くなります。

✔️ パッケージに "Copyright (c) <name/company><year>" と著作権情報を追加してください。

基本的に、著作権表記によって、お客様の作業内容はお客様の許可がないとコピーできないということが示されます。 パッケージに著作権表記を含めることは簡単であり、何の害もありません。

例: Copyright (c) Contoso 2020

プロジェクト URL

✔️ 関連付けられているプロジェクト、リポジトリ、または会社の Web サイトへのリンクを含めてください。

プロジェクト サイトには、パッケージについてユーザーが知りたいすべてのことが含まれている必要があります。またおそらく、ユーザーがドキュメントを探す場所となります。

アイコン

✔️ 視覚的に区別しやすくなるように、パッケージにアイコンを含めることを検討してください。 これは、パッケージの品質に関する認識を向上させることができる、比較的小さな追加です。

アイコンは、個々のパッケージに固有であるか、またはブランドのロゴであることがあります。

✔️ 最良な表示結果になるように、128 x 128 で透明な背景を持つ画像 (PNG) を使用してください。

NuGet では、表示されるクライアントに合わせて画像が自動的にスケーリングされます。

❌ 非推奨の IconUrl メタデータ プロパティは使用しないでください。

README

✔️ パッケージの機能と開始方法の概要を説明する README マークダウン ファイルを追加してください。

パッケージの README があると、パッケージの品質に関する認識と新規ユーザーの獲得が大幅に向上します。 また、アップロードする前に README を再確認することも検討してください。 詳細については、「NuGet パッケージ に README ファイルを含める方法」を参照してください。

リポジトリの種類と URL

✔️ ソース リンクを設定して、ソース管理メタデータが NuGet パッケージに自動的に追加され、ライブラリのデバッグが容易になるようにすることを検討してください。

ソース リンクによって、Repository URL と Repository Type がパッケージ メタデータに自動的に追加されます。 また、パッケージのバージョンに関連付けられている特定のコミットも追加されます。

タグ

✔️ 見つけやすさを向上させるために、パッケージに関連する重要な用語を含むいくつかのタグを追加してください。

タグは NuGet.org の検索アルゴリズムにおいて考慮されます。また、パッケージ ID に含まれていないが重要である用語のために特に役立ちます。

たとえば、コンソールに対する文字列をログに記録するためのパッケージを発行した場合は、"ログ記録、ログ、コンソール、文字列、出力" などを含めます

リリース ノート

✔️ 各更新に、どのような変更が実施されたかを説明するリリース ノートを含めてください。

リリース ノートに必要な特定の形式はありませんが、以下を含めることをお勧めします。

  1. 重大な変更
  2. 新機能
  3. バグ修正

リポジトリ内でリリース ノートまたは変更ログを既に追跡している場合は、関連するファイルへのリンクを含めることもできます。

ライセンス

✔️ ライセンス式またはライセンス ファイルをパッケージに含めることを実施してください。

重要

ライセンスを持たないプロジェクトは、既定で排他的な著作権になります。これは、プロジェクトを使用する権限を誰にも付与していないことを意味します。

❌ 非推奨の LicenseUrl メタデータ プロパティは使用しないでください。

URL でのライセンスの変更によって、以前のパッケージ バージョンに対して表示されたライセンスが遡及的に変更されるため、法的なあいまいさが生じます。

パッケージがオープンソースの場合

✔️ パッケージをオープンソースにするために、オープンソース ライセンスを選択してください。

"オープンソース ライセンスは、オープンソースの定義に準拠するライセンスです。簡単に言うと、ソフトウェアの自由な使用、変更、および共有を許可するということです。" - オープンソース イニシアチブ。 オープンソース ソフトウェアとオープンソース イニシアチブの詳細については、https://opensource.org/ を参照してください。

✔️ パッケージにライセンス式を含めることを検討してください。

ライセンス式は最も明確に表示され、コンシューマーに対して、パッケージを使用できるかどうか、またはライセンスが変更されたかどうかがより明確になります。

Note

NuGet.org で受け入れられるのは、オープンソース イニシアチブまたはフリー ソフトウェア財団によって承認されたライセンスのライセンス式のみです。

パッケージがオープンソースでない場合

✔️ ライセンス ファイルをパッケージに含めることを実施してください。

標準以外のライセンスも含め、任意のライセンス ファイル (.txt または .md) をパッケージに追加できます。