バージョン管理
ソフトウェア ライブラリがバージョン 1.0 で完成することはほとんどありません。 優れたライブラリは、時間の経過と共に進化し、機能を追加し、バグを修正し、パフォーマンスを向上させます。 既存のユーザーを壊すことなく、新しいバージョンの .NET ライブラリをリリースできることは重要です。
重大な変更
バージョン間の破壊的変更の処理については、「破壊的変更を参照してください。
バージョン番号
.NET ライブラリには、バージョンを指定するさまざまな方法があります。 これらのバージョンが最も重要です。
NuGet パッケージのバージョン
NuGet パッケージ バージョン は、NuGet.org と Visual Studio NuGet パッケージ マネージャーに表示され、パッケージが使用されるときにソース コードに追加されます。 NuGet パッケージのバージョンは、ユーザーが一般的に表示するバージョン番号であり、使用しているライブラリのバージョンについて説明するときに参照します。 NuGet パッケージ バージョンは NuGet によって使用され、ランタイムの動作には影響しません。
<PackageVersion>1.0.0-alpha1</PackageVersion>
NuGet パッケージのバージョンと組み合わせた NuGet パッケージ識別子は、NuGet でパッケージを識別するために使用されます。 たとえば、Newtonsoft.Json + 11.0.2します。 サフィックスが付いたパッケージはプレリリース パッケージであり、テストに最適な特別な動作を備えます。 詳細については、プレリリース パッケージ 参照してください。
NuGet パッケージのバージョンは開発者に最も目に見えるバージョンであるため、セマンティック バージョン管理 (SemVer)を使用して更新することをお勧めします。 SemVer は、リリース間の変更の重要性を示し、開発者が使用するバージョンを選択する際に情報に基づいた意思決定を行うのに役立ちます。 たとえば、1.0 から 2.0 に移動すると、重大な変更が発生する可能性があることを示します。
✔️ SemVer 2.0.0 を使用して NuGet パッケージをバージョン管理することを検討してください。
✔️ パブリック ドキュメントの NuGet パッケージ バージョンは、ユーザーに一般的に表示されるバージョン番号であるため、使用してください。
✔️ リリースできないパッケージをリリースする場合は、プレリリース サフィックスを含めます。 (API をプレビューまたは試験段階としてマークする方法の詳細については、プレビュー APIを参照してください)。
ユーザーは、パッケージが完全ではないことを理解できるように、プレリリース パッケージの取得をオプトインする必要があります。
アセンブリ バージョン
アセンブリ バージョンは、読み込むアセンブリのバージョンを選択するために実行時に CLR が使用するバージョンです。 バージョン管理を使用してアセンブリを選択することは、厳密な名前を持つアセンブリにのみ適用されます。
<AssemblyVersion>1.0.0.0</AssemblyVersion>
.NET Framework CLR では、厳密な名前のアセンブリを読み込むには条件が完全に一致することを要求します。 たとえば、Library1, Version=1.0.0.0 は Newtonsoft.Json, Version=11.0.0.0への参照を使用してコンパイルされました。 .NET Framework では、その正確なバージョン 11.0.0.0のみが読み込まれます。 実行時に別のバージョンを読み込むには、バインド リダイレクトを .NET アプリケーションの構成ファイルに追加する必要があります。
厳密な名前付けがアセンブリ バージョンと組み合わさることで、厳密なアセンブリ バージョンの読み込みを可能にします。 ライブラリの厳密な名前付けには多くの利点があります。多くの場合、アセンブリが見つからないという実行時例外が発生し、app.config または web.config のバインド リダイレクト を修正する必要があります。 .NET (Core) では、アセンブリの読み込みがより緩和されます。 .NET (Core) ランタイムは、実行時に上位バージョンのアセンブリを自動的に読み込みます。
✔️ 検討対象は、AssemblyVersion にメジャー バージョンのみを含めます。
たとえば、ライブラリ 1.0 とライブラリ 1.0.1 の両方に
1.0.0.0の AssemblyVersion があり、Library 2.0 には AssemblyVersion が2.0.0.0です。 アセンブリのバージョンの変更頻度が低い場合、バインド リダイレクトが減ります。
✔️ AssemblyVersion のメジャー バージョン番号と NuGet パッケージバージョンの同期を維持することを検討してください。
AssemblyVersion は、例外メッセージ内のアセンブリ名やアセンブリ修飾型名など、ユーザーに表示される一部の情報メッセージに含まれます。 バージョン間の関係を維持すると、使用しているバージョンに関する詳細情報が開発者に提供されます。
❌ には固定の AssemblyVersion がありません。
変更しない AssemblyVersion を使用すると、バインド リダイレクトが不要になりますが、グローバル アセンブリ キャッシュ (GAC) にインストールできるアセンブリのバージョンは 1 つだけです。 また、GAC 内のアセンブリを参照するアプリケーションは、別のアプリケーションが破壊的変更で GAC アセンブリを更新した場合に中断します。
アセンブリ ファイルのバージョン
アセンブリ ファイルのバージョンは、Windows でファイル バージョンを表示するために使用され、実行時の動作には影響しません。 このバージョンの設定は省略可能です。 Windows エクスプローラーの [ファイルのプロパティ] ダイアログに表示されます。
<FileVersion>11.0.2.21924</FileVersion>
✔️ 検討 AssemblyFileVersion リビジョンとして、継続的インテグレーションのビルド番号を含める。
たとえば、プロジェクトのバージョン 1.0.0 をビルドしており、継続的インテグレーションビルド番号は 99 であるため、AssemblyFileVersion は 1.0.0.99 です。
✔️ ファイル バージョンに Major.Minor.Build.Revision 形式を使用してください。
ファイル バージョンは .NET では使用されませんが、Windows では、ファイル バージョン
Major.Minor.Build.Revision形式であることが想定されています。 バージョンがこの形式に従っていない場合は、警告が発生します。
アセンブリの情報バージョン
アセンブリ情報バージョンは、追加のバージョン情報を記録するために使用され、実行時の動作には影響しません。 このバージョンの設定は省略可能です。 ソース リンクを使用している場合、このバージョンは NuGet パッケージバージョンとソース管理バージョンを使用してビルド時に設定されます。 たとえば、1.0.0-beta1+204ff0a には、アセンブリのビルド元のソース コードのコミット ハッシュが含まれます。 詳細については、「ソース リンク」をご覧ください。
<InformationalVersion>The quick brown fox jumped over the lazy dog.</InformationalVersion>
手記
以前のバージョンの Visual Studio では、このバージョンが Major.Minor.Build.Revision形式に従っていない場合、ビルド警告が表示されます。 警告は無視しても問題ありません。
❌ アセンブリ情報バージョンを自分で設定しないでください。
SourceLink で、NuGet とソース管理のメタデータを含むバージョンを自動的に生成できるようにします。
.NET